Class ConfigAssistant

Description

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)


	
			
Variable Summary
 array $dialogdef
 array $fields
 string $keyfield
 $string $prefix
 array $records
 string $table
 mixed $where
Method Summary
 void ConfigAssistant (string $table, string $keyfield, [string $prefix = ''], [string $domain = ''], [mixed $where = ''], [array $dialogdef_hidden = ''])
 array get_dialogdef ()
 array get_extra (string $type, string $extras)
 void get_options_from_extra ( $extra,  $name)
 void save_data (object &$output)
 void show_dialog (object &$output, string $href)
Variables
array $dialogdef = NULL (line 282)
array $dialogdef_hidden (line 285)
  • var: $dialogdef_hidden array with additional fields that should be included in the dialog
array $fields = array('name','type','value','extra') (line 264)
  • var: $fields the list of essential fields to retrieve from the the table
string $keyfield (line 270)
  • var: $keyfield a string indicating the keyfield to uniquely identify the configuration parameter
$string $language_domain (line 279)
  • var: $domain the language domain where to look for translations (default: 'admin')
$string $prefix (line 276)
  • var: $prefix is prepended for every translation/language key and the dialog item name
array $records = NULL (line 273)
  • var: $records the cached list of configuration values straight from the database
string $table (line 261)
  • var: $table the table that contains the configuration
mixed $where (line 267)
  • var: $where a string with a whereclause (without 'WHERE') or an array with conditions
Methods
Constructor ConfigAssistant (line 300)

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.

  • return: object setup and data buffered in object
void ConfigAssistant (string $table, string $keyfield, [string $prefix = ''], [string $domain = ''], [mixed $where = ''], [array $dialogdef_hidden = ''])
  • string $table: the table where the configuration parameters are stored
  • string $keyfield: the field that uniquely identifies the configuration parameters
  • string $prefix: is prepended for every translation/language key and the also dialog item name
  • string $domain: the language domain where to look for translations (default: 'admin')
  • mixed $where: a whereclause (without 'WHERE') or an array with conditions
  • array $dialogdef_hidden: additional fields for inclusion in dialog definition
get_dialogdef (line 391)

construct an array with the dialog information

  • return: the dialog information
  • todo: implement checklist
array get_dialogdef ()
get_extra (line 505)

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.

  • return: string $extras parsed into an array (or an empty array if no name=value pairs found)
array get_extra (string $type, string $extras)
  • string $type: variable type (necessary for calculating minvalue/maxvalue)
  • string $extras: semicolon-delimited list of name=value pairs
get_options_from_extra (line 547)
void get_options_from_extra ( $extra,  $name)
  • $extra
  • $name
save_data (line 337)

save the modified configuration parameters to the database

void save_data (object &$output)
  • object &$output: the object that collects the output
show_dialog (line 324)

add a complete dialog to the content area of the output

void show_dialog (object &$output, string $href)
  • object &$output: the object that collects the output
  • string $href: the target for the form that will be created

Documentation generated on Tue, 28 Jun 2016 19:08:47 +0200 by phpDocumentor 1.4.0