Difference between revisions of "WEC"

Latest revision as of 00:05, 17 May 2014

About

WEC (short for WebEnd Configurator) is the WDLXTV configuration interface. Integrated into WDLXTV since version 0.4.2.9, it consists of two parts:

• An end-user web interface, for configuring various aspects of WDLXTV and external add-ons
• A complete framework making it easy for developers to add their own configuration entries on the web interface.

WEC for end-users

WEC can be accessed through WDLXTV's web interface. From there, click on WDLXTV Config to access it.

Through WEC you can configure various options offered by WDLXTV, third party OSDs and applications, WDTVExt plugins, and UMSP plugins.

You can also backup and restore your configuration. You will be able to download (or upload) the whole content of /conf.

WEC for developers

WEC makes it easy for third party developers to add their own configurable options on the web interface. To achieve this, a plugin written in PHP must be created, and either copied or symlinked to the /tmp/config-plugins/ folder at boot time.

Starting with 0.4.5.0 (WEC version 3), you can even supply your own functions to read/write your settings. This allows you to handle your own config file, not just the one used by WDTV's config_tool.

Also, starting with 0.4.5.0, WEC can handle UMSP plugins that contain user-configurable options.

Starting with 0.4.7.0 (WEC version 4), you can supply a function to be called after your setting was saved. This function will let you, for example, take care of stopping or starting the service after the user changed it.

Starting with 0.4.8.0 (WEC version 5), you can optionally define your groups with specific options. Groups can now be given a display priority (for ordering), and be made collapsible and collapsed by default.

WEC Plugin definition

A WEC plugin consists of a simple PHP file whose name ends in "_wec.php" and contains array entries that use the following structure:

$wec_options['CONFIGNAME'] = array('configname' => 'CONFIGNAME',
                                   'configdesc' => "",
                                   'longdesc' => "",
                                   'group' => 'Services',
                                   'type' => TYPE,
                                   'page' => PAGE,
                                   'displaypri' => 0,
                                   'availval' => array(),
                                   'availvalname' => array(),
                                   'defaultval' => '',
                                   'currentval' => '',
                                   'fieldheight' => '',
                                   'fieldlength' => '',
			           'readhook' => NULL,
			           'writehook' => NULL,
			           'postsavehook' => NULL);

CONFIGNAME is the name of your configuration entry. Fill the array with the following information:

configname

Option name

configdesc

Short description shown on the page

longdesc

Longer description, shown on a mouseover popup. Single quotes must be escaped (\').

group

Category name under which the option will be displayed. Groups can optionally be defined separately if you want to assign them a display priority or make them collapsible.

type

One of the WECT_ constants, defines the type of input field

availval

Array of available values (for dropdown menu)

availvalname

Array of available values (what's shown in the dropdown menu)

defaultval

Default value,

currentval

Leave empty (will be filled by parsed options)

page

One of the WECP_ constants, defines on which page to be displayed.

displaypri

Display order priority, between -50 (top) and +50 (bottom). (Optional, default is 0)

fieldheight

Number of lines to display (for WECT_FULLTEXT, WECT_MULTI) (Optional)

fieldlength

Number of chars to display in lenght (for WECT_FULLTEXT, _INT, _TEXT)(Optional)

writehook

Name of a function that handles writing that config entry (Optional)

readhook

Name of a function that handles reading that config entry (Optional)

postsavehook

Name of a function that will be called after this option value was saved. Typically used to stop, start, or reload a service that was modified by the user. (Optional)

These are the valid TYPE values (do NOT put quotes around them):

WECT_BOOL

Checkbox, valid values are either ON or OFF

WECT_INT

Integer input field

WECT_TEXT

Text input field

WECT_SELECT

Select dropdown menu

WECT_DESC

Simple block of text inside a group. Position it either using displaypri, or by giving it a name that would end up in the desired location after an alphabetical sort. For example, WDTVEXT.1 will show up right after WDTVEXT.

WECT_MULTI

Multiselect gadget. Define availval and defaultval as arrays. If you don't use your own read/write hooks,then the value will be written as a string, using a pipe character ("|") as delimiter between values.

WECT_FULLTEXT

Multiline text entry gadget. You will need to define a readhook and a writehook to handle reading/writing this entry to your configuration file.

WECT_HIDDEN

This is a special entry that won't get displayed or saved. It is mostly used to define custom hooks. For example, if all your custom settings within a group can be read with one single function call, define a WECT_HIDDEN entry with a very high displaypri value (so it gets processed AFTER your other entries inside that same group), with pointers to your custom read/write functions. Then, have the readhooks of all your config entries point to wec_hook_donothing().

These are the valid PAGE values (do NOT put quotes around them):

WECP_MAIN

Main options (only those built-in to WDLXTV)

WECP_APPS

apps.bin

WECP_OSD

OSD.bin

WECP_WDTVEXT

WDTVEXT system plugins (only those built-in to WDLXTV)

WECP_EXTPLUGS

WDTVEXT downloaded plugins

WECP_UMSP

UMSP plugin

Group Definition

Starting with WEC version 5, groups can optionally be defined. This allows you to re-order them within your page, and also make them collapsible. A collapsible group is one that you can click on its header to hide its content. By default all UMSP plugins are collapsible and collapsed, for example.

To define a group, add a new entry in the $wec_groups array.

$wec_groups['GROUPNAME'] = array('displaypri' => 0,
                    'collapsible' => TRUE,
                    'iscollapsed' => TRUE);

GROUPNAME

The name of your group, as used in your $wec_options entries.

displaypri

Display order priority, between -50 (top) and +50 (bottom).

collapsible

Boolean (TRUE or FALSE), if you want this group to be collapsible

iscollapsed

Boolean (TRUE or FALSE), if you want this group to be collapsed by default

Example of a group definition:

$wec_groups['System'] = array('displaypri' => -20,
                    'collapsible' => TRUE,
                    'iscollapsed' => TRUE);

This will give a display priority of -20, making it appear higher on your page. The group will be collapsible and collapsed by default.

This is fully backward compatible - no need to check for the WECVERSION before defining your group. It will simply be ignored under older WEC versions. Undefined groups will default to a displaypri of 0 and be non-collapsible (with the exception of UMSP plugins, which are automatically made collapsible and iscollapsed by default).

Example of a WEC plugin entry

This is an example, from the PsychoTHC WEC plugin:

$wec_options['THUMBPLAYBAR_COLOR_SCHEME'] = array('configname' => 'THUMBPLAYBAR_COLOR_SCHEME',
                                                  'configdesc' => "Change color for thumb frames and play bars:",
                                                  'longdesc' => "Default: Yellow/Black",
                                                  'group' => 'OSD: PsychoTHC',
                                                  'type' => WECT_SELECT,
                                                  'page' => WECP_OSD,
                                                  'availval' => array('1','2','3','4','5','6','7','8','9','10','11','12'),
                                                  'availvalname' => array('Blue','Red','Yellow','White','Green','Purple','Blue/Black','Red/Black','Yellow/Black','White/Black','Green/Black','Purple/Black'),
                                                  'defaultval' => '9',
                                                  'currentval' => '');

Options are automatically sorted by 'group' before being displayed, so the order in which you enter them in your plugin doesn't matter. It is recommended to create a new group for your own additions unless they are directly related to any of the existing groups. Inside a group, entries are first sorted by displaypri (from lowest to highest value), then by alphabetical order.

Note that you can also replace an existing WDLXTV entry by redefining it in a WEC plugin. This can be useful for example if you are adding more options to an existing configuration entry.

Look at the /var/www/addons/config/wdlxtv_options.php file for examples on how this works.

Device-specific entries

Starting with WECVERSION 3 or higher, you can see on which device you are running. If you want to show an option only whenever a specific WDTV model is used, look for the content of the WECDEVICETYPE global variable. It will contain one of the following values:

• "Live"
• "Plus"
• "G2"
• "Unknown"

Custom hooks

Starting with WECVERSION 3 you can provide your own functions for reading/writing a setting.

If your config entries are either located in a different file than /conf/config, or require some special pre/post processing before storing, you can specify the name of a function that will take care of it.

WEC plugins have access to three different hooks:

readhook($wec_option_arr)

This function will be called while trying to read the saved value of a specific entry. $wec_option_arr is a *copy* of the $wec_options entry being read - write your data to the appropriate $wec_options entry!

writehook($wec_option_array, $value)

This function will be called when trying to save the value of a specific entry. $wec_option_array will contain a copy of the current $wec_option entry, and $value will contain the new value to be written.

postsavehook($wec_option_array, $value) (WECVERSION >= 4)

This function gets called whenever a setting gets written to the configuration. $wec_option_arr is a *copy* of the $wec_options entry being read, and $value will contain the new value that was just written. This hook *only* gets called when not using a writehook (since you can duplicate its behaviour through writehook anyway).

Note that both restorehook() and backuphook() are now deprecated, and no longer do anything.

Here is a basic example of a WEC plugin, with its hooks:

$wec_options['TESTCHAPI'] = array('configname' => 'TESTCHAPI',
                    'configdesc' => "Custom hook test",
                    'longdesc' => "",
                    'group' => 'Custom Hooks',
                    'type' => WECT_TEXT,
                    'page' => WECP_APPS,
                    'availval' => array(),
                    'availvalname' => array(),
                    'defaultval' => 'Default Value',
                    'currentval' => '',
                    'readhook' => 'wec_tp_read',
                    'writehook' => 'wec_tp_write');
 
 function wec_tp_write($wec_option_arr,$value) {
    // Do some file writing
    // Option is $wec_option_arr['configname']
    // which is set to $value.
 }

 function wec_tp_read($wec_option_arr) {
 global $wec_options
   // Read our config file into a global
   // Retrieve the option name from $wec_option_arr['configname']
   // And store it to $wec_options[option_name]['currentval']   
 }

A few important points when defining your hook functions:

• Give them unique names, so they won't collide with any other plugin. I recommend calling them wec_yourappname_read(), wec_yourappname_write(), etc...
• Same thing applies if you define any global variable: name it $wec_yourappname_varname.
• Keep in mind that WEC runs on the www-data user. Therefore, your config file must be accessible by that user, or else you will have to use 'sudo' with system calls for all file I/O.
• If you are going to have only one hook to fill multiple entries residing inside a group, don't forget that options within a group are processed by displaypri order, followed by alphabetical order. Therefore, give the highest displaypri value to any WECT_HIDDEN entry that contains your hooks.

Utility functions

Some built-in functions are available for use inside your WEC plugins.

wec_getConfigValue(name)

Returns the saved value of option "name" from /conf/config.

wec_umspwrap_write(wec_option_arr,value)

Function hook that acts as a wrapper around the UMSP plugin function that lets you write the enabled/disabled state of a plugin.

wec_umspwrap_read(wec_option_arr)

Function hook that acts as a wrapper around the UMSP function that lets you read wether a plugin is enabled or disabled.

wec_hook_donothing($wec_option_arr,$value)

This is an empty function hook that you can use when you don't want a given $wec_options entry to handle reading or writing itself (for example, if this option is handled by another function hook defined on another entry).

Other useful notes

You can directly link to a page on WEC by passing the wecpage=<page_number> parameter in your URL. For example:<a href="/addons/config/index.php?wecpage=7">Configure UMSP</a> will open WEC on the UMSP page.