<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <title>Module HowTo - Configuration options</title> <link rel="stylesheet" type="text/css" href="style/layout.css"> </head> <body> <div style="text-align: center;"> <h1>Module HowTo - Configuration options<br> </h1> <div style="text-align: left;"><br> 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.<br> Therefore LAM allows the modules to define their own configuration options. E.g. the <span style="font-style: italic;">posixAccount</span> module uses this to define the ranges for the UIDs.<br> LAM will display your configuration options only if the user also selected your module.<br> </div> <div style="text-align: left;"><br> <h2>1. Defining configuration options<br> </h2> 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.<br> <br> The configuration options are specified with <span style="font-weight: bold;">get_configOptions()</span> or <span style="font-weight: bold;">meta['config_options']</span>.<br> <br> <span style="font-weight: bold; text-decoration: underline;">Example:</span><br style="font-weight: bold; text-decoration: underline;"> <br> The <span style="font-style: italic;">posixGroup</span> module offers three configuration options. The min/maximum values for GIDs and the password hash type.<br> <br> <table style="width: 100%; text-align: left;" class="mod-code" border="0" cellpadding="2" cellspacing="2"> <tbody> <tr> <td style="vertical-align: top;"> /**<br> * Returns meta data that is interpreted by parent class<br> *<br> * @return array array with meta data<br> */<br> <span style="font-weight: bold;"> function</span> get_metaData() {<br> $return = array();<br> // configuration options<br> $return[<span style="color: rgb(255, 0, 0);">'config_options'</span>][<span style="color: rgb(255, 0, 0);">'group'</span>] = array(<br> array(<br> 0 => array('kind' => 'text', 'text' => '<b>' . _('Minimum GID number') . " *: </b>"),<br> 1 => array('kind' => 'input', 'name' => 'posixGroup_minGID', 'type' => 'text', 'size' => '10', 'maxlength' => '255'),<br> 2 => array('kind' => 'text', 'value' => '&nbsp;'),<br> 3 => array('kind' => 'text', 'text' => '<b>' . _('Maximum GID number') . " *: </b>"),<br> 4 => array('kind' => 'input', 'name' => 'posixGroup_maxGID', 'type' => 'text', 'size' => '10', 'maxlength' => '255'),<br> 5 => array('kind' => 'help', 'value' => 'minMaxGID')),<br> array(<br> 0 => array('kind' => 'text', 'text' => '<b>' . _("Password hash type") . ': &nbsp;</b>'),<br> 1 => array('kind' => 'select', 'name' => 'posixGroup_pwdHash', 'size' => '1',<br> 'options' => array("CRYPT", "SHA", "SSHA", "MD5", "SMD5", "PLAIN"), 'options_selected' => array('SSHA')),<br> 2 => array('kind' => 'text', 'value' => '&nbsp;'),<br> 3 => array('kind' => 'text', 'value' => '&nbsp;'),<br> 4 => array('kind' => 'text', 'value' => '&nbsp;'),<br> 5 => array('kind' => 'help', 'value' => 'pwdHash'))<br> );<br> [...]<br> </td> </tr> </tbody> </table> <br> 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.<br> 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.<br> <br> <h2>2. Checking user input</h2> Probably you also want to check if the input data is syntactically correct.<br> The <span style="font-style: italic;">baseModule</span> already provides different checks which can be activated with <span style="font-style: italic;">meta data</span>. However you can also do the checking in the module.<br> Implementing the function <span style="font-weight: bold;">check_configOptions()</span> in your module will allow you to do the checks yourself. Basic checks can be defined with <span style="font-weight: bold;">meta['config_checks']</span>.<br> <br> <span style="font-weight: bold; text-decoration: underline;">Example:</span><br style="font-weight: bold; text-decoration: underline;"> <br> The <span style="font-style: italic;">posixGroup</span> 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.<br> <br> <table style="width: 100%; text-align: left;" class="mod-code" border="0" cellpadding="2" cellspacing="2"> <tbody> <tr> <td style="vertical-align: top;"> /**<br> * Returns meta data that is interpreted by parent class<br> *<br> * @return array array with meta data<br> */<br> <span style="font-weight: bold;"> function</span> get_metaData() {<br> $return = array();<br> // configuration checks<br> $return[<span style="color: rgb(255, 0, 0);">'config_checks'</span>][<span style="color: rgb(255, 0, 0);">'group'</span>]['posixGroup_minGID'] = array (<br> 'type' => 'ext_preg',<br> 'regex' => 'digit',<br> 'required' => true,<br> 'required_message' => $this->messages['gidNumber'][5],<br> 'error_message' => $this->messages['gidNumber'][5]);<br> $return[<span style="color: rgb(255, 0, 0);">'config_checks'</span>][<span style="color: rgb(255, 0, 0);">'group'</span>]['posixGroup_maxGID'] = array (<br> 'type' => 'ext_preg',<br> 'regex' => 'digit',<br> 'required' => true,<br> 'required_message' => $this->messages['gidNumber'][6],<br> 'error_message' => $this->messages['gidNumber'][6]);<br> $return[<span style="color: rgb(255, 0, 0);">'config_checks'</span>][<span style="color: rgb(255, 0, 0);">'group'</span>]['cmpGID'] = array (<br> 'type' => 'int_greater',<br> 'cmp_name1' => 'posixGroup_maxGID',<br> 'cmp_name2' => 'posixGroup_minGID',<br> 'error_message' => $this->messages['gidNumber'][7]);<br> [...]<br> </td> </tr> </tbody> </table> <br> The type <span style="font-weight: bold;">"ext_preg"</span> means that the <span style="font-style: italic;">baseModule</span> will use the <span style="font-style: italic;">get_preg()</span> function in <span style="font-style: italic;">lib/account.inc</span> for the syntax check. This function already contains regular expressions for the most common cases.<br> 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.<br> <br> <br> <h2>3. Descriptions</h2> 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.<br> <br> These descriptions are defined with <span style="font-weight: bold;">get_configDescriptions()</span> or <span style="font-weight: bold;">meta['config_descriptions']</span>.<br> <br> <span style="font-weight: bold; text-decoration: underline;">Example:</span><br style="font-weight: bold; text-decoration: underline;"> <br> The <span style="font-style: italic;">posixGroup</span> module will set a title for the fieldset and a description for the three configuration options.<br> <br> <table style="width: 100%; text-align: left;" class="mod-code" border="0" cellpadding="2" cellspacing="2"> <tbody> <tr> <td style="vertical-align: top;"> /**<br> * Returns meta data that is interpreted by parent class<br> *<br> * @return array array with meta data<br> */<br> <span style="font-weight: bold;"> function</span> get_metaData() {<br> $return = array();<br> // configuration descriptions<br> $return[<span style="color: rgb(255, 0, 0);">'config_descriptions'</span>] = array(<br> 'legend' => _("GID ranges for Unix groups"),<br> 'descriptions' => array(<br> 'posixGroup_minGID' => _("Minimum GID number for Unix groups"),<br> 'posixGroup_maxGID' => _("Maximum GID number for Unix groups"),<br> 'posixGroup_pwdHash' => _("Password hash type for Unix groups"),<br> )<br> );<br> [...]<br> </td> </tr> </tbody> </table> <br> This will set the fieldset title to "GID ranges for Unix groups" and the descriptions for the settings list.<br> <span style="font-weight: bold;"></span> <h2><span style="font-weight: bold;"></span></h2> </div> </div> </body> </html>