Module HowTo - Configuration options

There might be situations where you want to give the user the possibility to make general settings which are not useful to place on the account detail pages or profile editor.
Therefore LAM allows the modules to define their own configuration options. E.g. the posixAccount module uses this to define the ranges for the UIDs.
LAM will display your configuration options only if the user also selected your module.

1. Defining configuration options

First you have to define what options you want to offer the user. LAM will display all options in one fieldset for each module. Please notice that there will be no separation on account types if you module is suitable for different account types.

The configuration options are specified with get_configOptions() or meta['config_options'].

Example:

The posixGroup module offers three configuration options. The min/maximum values for GIDs and the password hash type.

/**     * Returns meta data that is interpreted by parent class     *     * @return array array with meta data     */     function get_metaData() {         $return = array();         // configuration options         $return['config_options']['group'] = array(             array(                 0 => array('kind' => 'text', 'text' => '<b>' . _('Minimum GID number') . " *: </b>"),                 1 => array('kind' => 'input', 'name' => 'posixGroup_minGID', 'type' => 'text', 'size' => '10', 'maxlength' => '255'),                 2 => array('kind' => 'text', 'value' => '&nbsp;'),                 3 => array('kind' => 'text', 'text' => '<b>' . _('Maximum GID number') . " *: </b>"),                 4 => array('kind' => 'input', 'name' => 'posixGroup_maxGID', 'type' => 'text', 'size' => '10', 'maxlength' => '255'),                 5 => array('kind' => 'help', 'value' => 'minMaxGID')),             array(                 0 => array('kind' => 'text', 'text' => '<b>' . _("Password hash type") . ': &nbsp;</b>'),                 1 => array('kind' => 'select', 'name' => 'posixGroup_pwdHash', 'size' => '1',                 'options' => array("CRYPT", "SHA", "SSHA", "MD5", "SMD5", "PLAIN"), 'options_selected' => array('SSHA')),                 2 => array('kind' => 'text', 'value' => '&nbsp;'),                 3 => array('kind' => 'text', 'value' => '&nbsp;'),                 4 => array('kind' => 'text', 'value' => '&nbsp;'),                 5 => array('kind' => 'help', 'value' => 'pwdHash'))         );         [...]

The min/maximum GID numbers are defined with simple text boxes. The password hash is selected with a drop down box and SSHA as default value.
You should make sure that the column count (here: 6) is the same for each row. Otherwise the configuration page might be badly rendered by the browser.

2. Checking user input

Probably you also want to check if the input data is syntactically correct.
The baseModule already provides different checks which can be activated with meta data. However you can also do the checking in the module.
Implementing the function check_configOptions() in your module will allow you to do the checks yourself. Basic checks can be defined with meta['config_checks'].

Example:

The posixGroup module only needs to check if the GID numbers are correct. The password hash type needs not to be checked as it is a selection.

/**     * Returns meta data that is interpreted by parent class     *     * @return array array with meta data     */     function get_metaData() {         $return = array();         // configuration checks         $return['config_checks']['group']['posixGroup_minGID'] = array (             'type' => 'ext_preg',             'regex' => 'digit',             'required' => true,             'required_message' => $this->messages['gidNumber'][5],             'error_message' => $this->messages['gidNumber'][5]);         $return['config_checks']['group']['posixGroup_maxGID'] = array (             'type' => 'ext_preg',             'regex' => 'digit',             'required' => true,             'required_message' => $this->messages['gidNumber'][6],             'error_message' => $this->messages['gidNumber'][6]);         $return['config_checks']['group']['cmpGID'] = array (             'type' => 'int_greater',             'cmp_name1' => 'posixGroup_maxGID',             'cmp_name2' => 'posixGroup_minGID',             'error_message' => $this->messages['gidNumber'][7]);         [...]

The type "ext_preg" means that the baseModule will use the get_preg() function in lib/account.inc for the syntax check. This function already contains regular expressions for the most common cases.
To check if the minimum GID is smaller than the maximum GID we define a check for the nonexistant option "cmpGID" and define it as optional. This will do the comparison check.

3. Descriptions

What is still missing is a descriptive title for the fieldset in the configuration editor and a description for each configuration option which is displayed when the user saves the settings.

These descriptions are defined with get_configDescriptions() or meta['config_descriptions'].

Example:

The posixGroup module will set a title for the fieldset and a description for the three configuration options.

/**     * Returns meta data that is interpreted by parent class     *     * @return array array with meta data     */     function get_metaData() {         $return = array();         // configuration descriptions         $return['config_descriptions'] = array(             'legend' => _("GID ranges for Unix groups"),             'descriptions' => array(                 'posixGroup_minGID' => _("Minimum GID number for Unix groups"),                 'posixGroup_maxGID' => _("Maximum GID number for Unix groups"),                 'posixGroup_pwdHash' => _("Password hash type for Unix groups"),             )         );         [...]

This will set the fieldset title to "GID ranges for Unix groups" and the descriptions for the settings list.