diff --git a/lam/docs/devel/mod_config.htm b/lam/docs/devel/mod_config.htm new file mode 100644 index 00000000..9aae47e0 --- /dev/null +++ b/lam/docs/devel/mod_config.htm @@ -0,0 +1,253 @@ + + + + Module HowTo - Configuration options + + + +
+

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.
+ +

+
+
+ + diff --git a/lam/docs/devel/mod_index.htm b/lam/docs/devel/mod_index.htm index c3565a01..84b9c84f 100644 --- a/lam/docs/devel/mod_index.htm +++ b/lam/docs/devel/mod_index.htm @@ -43,11 +43,11 @@ This part covers additional functionality of the modules which are only needed by a minority of modules. The examples are taken from different existing modules.

-

1. Account profiles

-
-

2. Configuration options

+

1. Account profiles


+

2. Configuration options


+

3. Advanced upload options


diff --git a/lam/docs/devel/mod_pdf.htm b/lam/docs/devel/mod_pdf.htm index 6b045504..5f2e5d0a 100644 --- a/lam/docs/devel/mod_pdf.htm +++ b/lam/docs/devel/mod_pdf.htm @@ -31,8 +31,7 @@ address.
border="0" cellpadding="2" cellspacing="2"> -        -/**
+     /**
    * Returns meta data that is interpreted by parent class
    *
diff --git a/lam/docs/devel/mod_profiles.htm b/lam/docs/devel/mod_profiles.htm new file mode 100644 index 00000000..7c1643fb --- /dev/null +++ b/lam/docs/devel/mod_profiles.htm @@ -0,0 +1,162 @@ + + + + Module HowTo - Account profiles + + + +
+

Module HowTo - Account profiles
+

+

+Account profiles make it easy to set default values for new accounts +and even to reset an existing account to default values.
+Your module should provide the possibility to define default values for +all attributes which do not differ for each account.
+
+

+

1. Defining possible profile options
+

+The first step to account profiles is defining the attributes for which +the user can set default values. You will also have to define the type +(text, checkbox, ...) of the profile options.
+The profile editor then will display a fieldset for each module +containing its profile options.
+
+The profile options are specified with get_profileOptions() +or meta['profile_options'].
+
+Example:
+
+The inetOrgPerson +module has only two attributes which may be set to a default value: job +title and employee type.
+The other attributes are account specific and not useful as profile +options.
+
+ + + + + + +
    /**
+    * Returns meta data that is interpreted by parent +class
+    *
+    * @return array array with meta data
+    */
+    function +get_metaData() {
+        $return = array();
+        // profile elements
+        $return['profile_options'] = array(
+            array(
+            +    0 => array('kind' => 'text', 'text' => +_('Job title') . ":"),
+            +    1 => array('kind' => 'input', 'name' => +'inetOrgPerson_title', 'type' => 'text', 'size' => '30', +'maxlength' => '255'),
+            +    2 => array('kind' => 'help', 'value' => +'title')),
+            array(
+            +    0 => array('kind' => 'text', 'text' => +_('Employee type') . ":"),
+            +    1 => array('kind' => 'input', 'name' => +'inetOrgPerson_employeeType', 'type' => 'text', 'size' => '30', +'maxlength' => '255'),
+            +    2 => array('kind' => 'help', 'value' => +'employeeType'))
+        );
+        [...]
+
+
+This defines two text boxes in the profile editor, one for the job +title and one for the employee type.
+Your profile options should also provide a help link if the description +of the input element might be not enough.
+
+
+

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_profileOptions() +in your module will allow you to do the checks yourself. Basic checks +can be defined with meta['profile_checks'].
+
+Example:
+
+The inetOrgPerson module only +needs some regular expression checks on the input. This can be done by +the baseModule.
+
+ + + + + + +
    /**
+    * Returns meta data that is interpreted by parent +class
+    *
+    * @return array array with meta data
+    */
+    function +get_metaData() {
+        $return = array();
+        // profile checks
+        $return['profile_checks']['inetOrgPerson_title'] = array(
+            'type' => +'ext_preg',
+            'regex' => +'title',
+           + 'error_message' => $this->messages['title'][0]);
+        $return['profile_checks']['inetOrgPerson_employeeType'] = +array(
+            'type' => +'ext_preg',
+            'regex' => +'employeeType',
+           + 'error_message' => $this->messages['employeeType'][0]);
+        [...]
+
+
+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.
+
+
+

3. Loading an account profile

+
+TODO
+ +

+
+
+ +