class for editing standard configuration tables
Overview
--------
A configuration table works like this: every parameter (property, configuration item) is stored in a record in the configuration table. The core of a configuration table consists of these fields:
- name varchar(240): this is the name of the configuration parameter - type varchar(2): parameter type: b=bool, c=checklist, d=date, dt=date/time, f=float(double), i=int, l=list, r=radio, s=string, t=time (see below for more information) - value text: string representation of parameter value OR a comma-delimited list of values in case of a checklist - extra text: a semicolon-delimited list of name=value pairs with additional dialog/validation information, e.g. maxlength=80 or options=true,false,filenotfound (see below for more information) - sort_order integer: this determines the order in which parameters are presented when editing the configuration - description text: an optional short explanation of the purpose of this parameter (in English, for internal use only)
There can be additional fields, e.g. links to parent tables in a 1-on-N relation, e.g. themes and themes_properties via theme_id. Also, the configuration table can have a separate primary key to uniquely identify a record but this is not necessary. In the config table the primary key is the name of the parameter.
Parameter types
---------------
Here is an overview of the various parameter types.
- b=bool: This type is used to store yes/no type of parameters. The parameter is considered 'TRUE' whenever the integer value of the value field is non-zero. If the integer value of the value field is zero, the parameter is considered to be 'FALSE'. Note that the NULL value also yields a zero integer value and hence 'FALSE'. - c=checklist: This type is an array of boolean parameters. The value of a parameter of this type is stored as a comma-delimited list of values which are to be considered 'TRUE'. If none of the elements of this array are 'TRUE', the comma-delimited list is empty. The list of possible values MUST be specified in the 'extra' field in the 'options=' item. (see below for more information about the 'extra' field). - d=date: This type is used to store (valid) dates, in the standard format 'yyyy-mm-dd'. (Validated in valid_datetime(), values from '0000-01-01' - '9999-12-31'). - dt=date/time: This type is used to store (valid) date/time combinations, in the standard format 'yyyy-mm-dd hh:mm:ss'. (Validated in valid_datetime(), values from '0000-01-01 00:00:00' - '9999-12-31 23:59:59'). - f=float(double): This type is used to store real (floating point) numbers with double precision. - i=int: This type is used to store integer numbers. - l=list: This type is used to store a single value from a list of available options (a 'picklist'). The current value is stored in the value field, and a list of possible values MUST be specified in the 'extra' field in the 'options=' item. (see below for more information about the 'extra' field). - r=radio: This type is also used to store a single value from a list of available options, much like the list-type (a 'picklist'). The difference is the representation in a dialog: a list parameter uses only a single line, whereas a group of radio buttons usually uses as many lines as there are available options. The current value is stored in the value field, and a list of possible values MUST be specified in the 'extra' field in the 'options=' item. (see below for more information about the 'extra' field). - s=string: This type is used to store generic text information. The maximum length of the string is the maximum length of the text field in the database (in MySQL this is 65535 bytes). - t=time: This type is used to store a (valid) time, in the format 'hh:mm:ss'. (Validated in valid_datetime(), values from '00:00:00' - '23:59:59').
The Extra field
---------------
This field can contain additional information about the parameter, either for validation or for display purposes. The contents of this field is a list of semicolon-delimited name=value-pairs. The following items are recognised (see also dialoglib.php.
- rows=<int> This is the number of rows to display in a dialog. It can apply to string-type variables and yield a textarea-tag (as opposed to an input-tag of type 'text'). It can also apply to a set of radio buttons in a very specific way: if the number of rows is 1, the radio buttons are displayed on a single line in the dialog. - columns=<int> This is number of columns to use for input (but not the necessry the maximum length of the input). If this item is omitted, default values apply, e.g. 30 for date, time. datetime; 20 for float (double) and 10 for integer, etc. - minlenght=<int> This is the minimum number of characters that must be input. When this item is set to 1, an empty string is not allowed. - maxlength=<int> This is the maximum number of characters that can be input. - minvalue=<mixed> This is the minimum value for the field. The type of the minumum value is the same as the type of the variable itself. It applies to integers, floats, dates, datetimes and times. - maxvalue=<mixed> This is the maximum value for the field. The type of the maxumum value is the same as the type of the variable itself. It applies to integers, floats, dates, datetimes and times. - decimals=<int> This is the number of decimals that should be displayed in dialogs. It applies to floats. - options=option1,option2,option3,(...) This is a comma-delimited list of valid values for a list, radio or checklist parameter. The value of the parameter is one of the options in this list (for parameter types list and radio) OR a comma-delimited list of zero or more items (for checklists). - viewonly=<int> If the integer value of this item is non-zero, the user is not allowed to edit the value of the parameter. However, it is supposed to be displayed in the dialog nevertheless.
Generating dialogs for editing
------------------------------
The ConfigAssistant is clever enough to read and write the configuration parameters from the specified table, using a where-clause when necessary. Also, the ConfigAssistant automatically constructs translations of screen prompts in a very specific way when constructing dialogs.
The translation keys are constructed as follows.
- simple string-like parameters (string, date, time, etc.) name = <prefix><name> label = <prefix><name>_label title = <prefix><name>_title - bool parameter name = <prefix><name> label = <prefix><name>_label title = <prefix><name>_title option = <prefix><name>_option - list or radio parameter name = <prefix><name> label = <prefix><name>_label, title = <prefix><name>_title options: label = <prefix><name>_<option1>_label title = <prefix><name>_<option1>_title ... label = <prefix><name>_<optionN>_label title = <prefix><name>_<optionN>_title - checlist parameter name = <prefix><name> label = <prefix><name>_label title = <prefix><name>_title options: title = <prefix><name>_<option1>_title option = <prefix><name>_<option1>_option ... title = <prefix><name>_<optionN>_title option = <prefix><name>_<optionN>_option
The string <prefix> can be used to avoid name clashes in the 'admin' (or other) language file. The translations are then looked up in the specified language domain (default: admin).
Examples
--------
Example 1: sending a dialog to the user for editing all the parameters in the the main config table:
$table = 'config'; $keyfield = 'name'; $assistant = new ConfigAssistant($table,$keyfield); $href = 'index.php?job=(...)&task=editconfig'; $assistant->show_dialog($output,$href);
Example 2: saving the modified data to the table
$table = 'config'; $keyfield = 'name'; $assistant = new ConfigAssistant($table,$keyfield); if (!$assistant->save_data($output)) { echo "FAILED"; } else { echo "SUCCESS saving configuration"; }
Sounds easy to use, doesn't it?
Located in /program/lib/configassistant.class.php (line 259)
constructor for the configuration assistant
This stores the parameters, sets defaults when applicable and subsequently reads selected config parameters into the $this->records for future reference.
construct an array with the dialog information
construct an array based on name=value pairs in an 'extra' field
This constructs an array based on the name=value pairs in the extras string. Most recognised parameters yield an integer value. Exceptions are: minvalue and maxvalue: these yield a variable of the same type as the config parameter itself options yields an array with all options from the comma delimited list Unknown name=value pairs are logged with WLOG_DEBUG.
save the modified configuration parameters to the database
add a complete dialog to the content area of the output
Documentation generated on Tue, 28 Jun 2016 19:08:47 +0200 by phpDocumentor 1.4.0