<!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">
	<link rel="shortcut icon" type="image/x-icon" href="images/favicon.ico">
</head>

<body>
<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;">&nbsp;&nbsp;&nbsp; /**<br>
&nbsp;&nbsp;&nbsp; * Returns meta data that is interpreted by parent
class<br>
&nbsp;&nbsp;&nbsp; *<br>
&nbsp;&nbsp;&nbsp; * @return array array with meta data<br>
&nbsp;&nbsp;&nbsp; */<br>
&nbsp;&nbsp;&nbsp;<span style="font-weight: bold;"> function</span>
get_metaData() {<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; $return = array();<br>
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp; // configuration options<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;$return[<span style="color: rgb(255, 0, 0);">'config_options'</span>][<span style="color: rgb(255, 0, 0);">'group'</span>] = array(<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;array(<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp; array('kind' =&gt; 'text', 'text' =&gt;
'&lt;b&gt;' .
_('Minimum GID number') . " *: &lt;/b&gt;"),<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp; array('kind' =&gt; 'input', 'name' =&gt;
'posixGroup_minGID', 'type' =&gt; 'text', 'size' =&gt; '10',
'maxlength' =&gt; '255'),<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp; array('kind' =&gt; 'text', 'value' =&gt;
'&amp;nbsp;'),<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp; array('kind' =&gt; 'text', 'text' =&gt;
'&lt;b&gt;' .
_('Maximum GID number') . " *: &lt;/b&gt;"),<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp; array('kind' =&gt; 'input', 'name' =&gt;
'posixGroup_maxGID', 'type' =&gt; 'text', 'size' =&gt; '10',
'maxlength' =&gt; '255'),<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp; array('kind' =&gt; 'help', 'value' =&gt;
'minMaxGID')),<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;array(<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp; array('kind' =&gt; 'text', 'text' =&gt;
'&lt;b&gt;' .
_("Password hash type") . ': &amp;nbsp;&lt;/b&gt;'),<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp; array('kind' =&gt; 'select', 'name' =&gt;
'posixGroup_pwdHash', 'size' =&gt; '1', 'options' =&gt; array("CRYPT", "SHA", "SSHA", "MD5", "SMD5",
"PLAIN"), 'options_selected' =&gt; array('SSHA')),<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp; array('kind' =&gt; 'text', 'value' =&gt;
'&amp;nbsp;'),<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp; array('kind' =&gt; 'text', 'value' =&gt;
'&amp;nbsp;'),<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp; array('kind' =&gt; 'text', 'value' =&gt;
'&amp;nbsp;'),<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp; array('kind' =&gt; 'help', 'value' =&gt; 'pwdHash'))<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;);<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [...]<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;">&nbsp; &nbsp; /**<br>
&nbsp;&nbsp;&nbsp; * Returns meta data that is interpreted by parent
class<br>
&nbsp;&nbsp;&nbsp; *<br>
&nbsp;&nbsp;&nbsp; * @return array array with meta data<br>
&nbsp;&nbsp;&nbsp; */<br>
&nbsp;&nbsp;&nbsp;<span style="font-weight: bold;"> function</span>
get_metaData() {<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; $return = array();<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; // configuration checks<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;$return[<span style="color: rgb(255, 0, 0);">'config_checks'</span>][<span style="color: rgb(255, 0, 0);">'group'</span>]['posixGroup_minGID'] =
array (<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;'type' =&gt;
'ext_preg',<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;'regex' =&gt;
'digit',<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;'required'
=&gt; true,<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;'required_message' =&gt; $this-&gt;messages['gidNumber'][5],<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;'error_message' =&gt; $this-&gt;messages['gidNumber'][5]);<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;$return[<span style="color: rgb(255, 0, 0);">'config_checks'</span>][<span style="color: rgb(255, 0, 0);">'group'</span>]['posixGroup_maxGID'] =
array (<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;'type' =&gt;
'ext_preg',<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;'regex' =&gt;
'digit',<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;'required'
=&gt; true,<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;'required_message' =&gt; $this-&gt;messages['gidNumber'][6],<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;'error_message' =&gt; $this-&gt;messages['gidNumber'][6]);<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;$return[<span style="color: rgb(255, 0, 0);">'config_checks'</span>][<span style="color: rgb(255, 0, 0);">'group'</span>]['cmpGID'] = array (<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;'type' =&gt;
'int_greater',<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;'cmp_name1'
=&gt; 'posixGroup_maxGID',<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;'cmp_name2'
=&gt; 'posixGroup_minGID',<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;'error_message' =&gt; $this-&gt;messages['gidNumber'][7]);<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [...]<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>
</div>
</body></html>