WEC

From WikiDLXTV
Revision as of 23:07, 21 May 2011 by RMerlin (Talk | contribs)

Jump to: navigation, search

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
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.

Retrieved from "http://wiki.wdlxtv.com/index.php?title=WEC&oldid=975"