Difference between revisions of "WEC"

Revision as of 19:43, 13 December 2010

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 settings. The WDLXTV built in options that are stored in /conf/config will then be backed up to /conf/config.bak.gz. Third party developers can also optionally implement their own backup functions. Restoring your backup will load any backed up settings, and allow you to edit/review them before saving them, which will apply them to the current configuration.

WEC aims at replacing the previous S00custom-options configuration mechanism, which often proved confusing and troublesome for non-expert users. S00custom-options can still be used, however when accessing WEC, any S00custom-options file found will be renamed, to avoid having S00custom-options overriding your WEC changes at your next reboot.

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.

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,
                                   'availval' => array(),
                                   'availvalname' => array(),
                                   'defaultval' => '',
                                   'currentval' => '',
                                   'fieldheight' => '',
                                   'fieldlength' => '',
			           'readhook' => NULL,
			           'writehook' => NULL,
			           'restorehook' => NULL,
                                   'backuphook' => 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. If you begin the group name with "@" then this group will be shown before any other group in its page.

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, WECT_INT, WECT_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)

restorehook

Name of a function that handles triggering "restore" mode for our readhook calls. Needed for when the user clicks on Restore. You only need one item with this hook. (Optional)

backuphook

Name of a function that handles backing up your configuration file. Needed for when the user clicks on Backup. You usually only need one of these. (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

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

restorehook()

This function is called when the user clicked on the Restore button. Typically, you only need one item with this hook defined. Provide WEC with a WECT_HIDDEN entry, with this hook defined. Have the function set a global variable (make sure to make it a unique name, i.e. $wec_yourplugin_restoremode). Then, when the readhook is called, check this flag to know if you need to read from your live config file, or from your backup one. Keep in mind that when the user clicks on the Restore button, all WEC does is read the data from the backup instead of the live config file. It's only after the user has reviewed his settings and clicks on Save that these get written to the live config file.

backuphook()

This function is called when the user clicked on the Backup button. Typically, you only need one item with this hook defined (use a WECT_HIDDEN entry). This function will have to take care of creating a backup of your config file(s).

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=5">Configure UMSP</a>

will open WEC on the UMSP page.