This document describes the module interface for LDAP Account Manager



1. Location and naming of modules

All LAM modules are placed in lib/modules/ and are named "<class name>.inc".
E.g. if you create a new module and its class name is "qmail" then the filename would be "qmail.inc".

The class name of a module must contain only a-z, A-Z, 0-9, -, and _.
All module classes should extend the baseModule class.

2. Class functions

2.1. Functions that have to work without superior accountContainer


2.1.1. can_manage*


function can_manage()

Returns true if this module can manage accounts of the current type, otherwise false.


2.1.2. get_alias*


function get_alias()

This function returns a more descriptive string than the class name. Alias names are used for the buttons of the account pages and the module selection of the configuration wizard.
Please take care that your alias name is not too long. It may contain any character but should not include parts that may be interpreted by the browser (e.g. '<' or '>').
If you use different aliases dependent on the account type please make sure that there is a general alias for unknown types.

2.1.3. is_base_module*


function is_base_module()

Returns true if your module is a base module and otherwise false.

Every account type needs at least one base module. A base module defines a full qualified account.
E.g. modules that use the object class posixAccount may be base modules as it makes sense to manage these Unix accounts. On the other hand the quota module is no base module as it needs posixAccount.

2.1.4. get_ldap_filter*


function get_ldap_filter()

Returns an array('or' => '...', 'and' => '...') that is used to build the LDAP filter. Usually used to filter object classes.

All "or" filter parts of the base modules are combined with OR and then combined with the "and" parts.
The resulting LDAP filter will look like this: (&(|(OR1)(OR2)(OR3))(AND1)(AND2)(AND3))

Example: return "('or' => '(objectClass=posixAccount)', 'and' => '(!(uid=*$))')"

This function is only used for base modules. Standard modules do not need to implement it.

2.1.5. get_dependencies*


function get_dependencies()

This function returns a list of modules it depends on.

The return value is an array with two sub arrays, "depends" and "conficts".
All values of the conflict array are string values with module names.
All values of the depends array are either string values with module names or arrays which include only string values with module names. If an element of the depends array is itself an array, this means that your module depends on one of these modules.

Example: return array("depends" => array("posixAccount", array("qmail", "sendmail")), "conflicts" => array("exim"));

2.1.6. get_metaData()


function get_metaData()

Returns an hash array including meta data for the baseModule.

Example: return array("is_base" => true);

2.1.7. get_configOptions()*


function get_configOptions($scopes)

Returns a list of configuration options.
$scopes is a list of account types (user, group, host) which are used.

The return value is an array that contains meta HTML code.

The type "fieldset" is not allowed here.
The name attributes are used as keywords to load and save settings. We recommend to use the module name as prefix for them (e.g. posixAccount_homeDirectory) to avoid naming confilcts.

2.1.8. get_configDescriptions()*


function get_configDescriptions()

Returns the description of every configuration option and the legend of the module fieldset on the configuration page.

The return value is a hash array with this format:
   
    array( 'legend' => 'Some general description for fieldset',
              'descriptions' => array('option1' => 'description1', ...))

2.1.9. check_configOptions*


function check_configOptions($scopes, $options)

This function checks the input for module configuration settings.

$scopes is a list of used account types (user, group, host).
$options is an hash array (option name => value) that contains the input. The option values are all arrays containing one or more elements.
If the input data is invalid the return value is an array that contains arrays to build StatusMessages (0 => message type, 1 => message head, 2 => message text, 3 => additional variables).
If no errors occured the function returns an empty array.

2.1.10. get_scope()


function get_scope()

Returns the account type (user/group/host) of this module object.

This function is provided by the baseModule and should not be overwritten.



2.2. Class functions

2.2.1. init


function init($base)

Every module needs a initializing function that has an account container as argument $base.
With this account container you can interact with other modules and use several helper functions.

2.2.2. module_ready


function module_ready()

Your module might depend on input of other modules. This function determines if the module button on the account page is active or not.
The return value is true if your module accepts input, otherwise false.

2.2.3. module_complete


function module_complete()

This function is called after your module has processed the POST input data.
If there was an input error and you want to display a page again then return false. If true is returned the next module page will be displayed.

2.2.4. get_help


function get_help($helpID)

This function is called when a page requests a help topic from this module.
$helpID is the help identifier; it must only contain a-z, A-Z, 0-9 -, . and _.
It must return the help entry as array for the submitted help identifier. The format of the array to be returned is described in section 4. "Help entry syntax".

2.2.5. get_profileOptions*


function get_profileOptions()

This function defines what attributes will be used in the account profiles and their appearance in the profile editor.

The return value is an array that contains meta HTML code.

The type "fieldset" is not allowed here.
The name attributes are used as keywords to load and save profiles. We recommend to use the module name as prefix for them (e.g. posixAccount_homeDirectory) to avoid naming confilcts.

2.2.6. check_profileOptions*


function check_profileOptions($options)

This function checks the input for a new or modified account profile.

$options is an hash array (option name => value) that contains the input. The option values are all arrays containing one or more elements.
If the input data is invalid the return value is an array that contains arrays to build StatusMessages (0 => message type, 1 => message head, 2 => message text, 3 => additional variables).
If no errors occured the function returns an empty array.

2.2.7. get_pdfEntries


function get_PDF_Entries($scope)

This function is called when a PDF is to be created.
$scope is the account type ("user", "group", "host" at this time).
It returns the fields which are printed in the PDF file for the specified account type. At the monent there is no (easy) possibility for the user to decide which fields are to be displayed. Perhaps there will be a PDF config tool in future releases where you can offer the user to decide which fields are to be displayed on the PDF file. The format of the array to be returned is described in section 5. "PDF syntax".

2.2.8. get_uploadColumns


function get_uploadColumns()

Returns a list of column entries for the upload .csv-file.
Each column entry is an array containing these values:


*: These functions do not need to be implemented if meta data is supplied. See 6 for a list of meta data formats.


3. Meta HTML code

The modules are not allowed to display HTML code directly but return meta HTML code. This allows to have a common design for all module pages.
Meta HTML code is always returned as a three dimensional array[a][b][c] where a is the row number, b is the coumn number and c is is a data elememt.

Format for data elements:

A data element is an array which contains the data to display.
All data elements must contail a value "kind" which defines what kind of element should be displayed.

These are the possibilies for kind and what other options are implicated:


Beneath those values a "td" value may be added. This has to be an array with one or more of these options:


Example:

array(
  array(
    array("kind" => "text", "text" => "This is an example", "td" => array("colspan" => 3))
  ),
  array(
    array("kind" => "text", "text" => "Input:"),
    array("kind" => "input", "name" => "myinput", "type" => "text"),
    array("kind" => "help", "value" => "42")
  )
)



4. Help entry syntax

The array that is returned by the get_help function must follow the below described syntax. Fields marked REQUIRED are neccessary under any circumstances. Fields marked OPTIONAL may be left out when not needed.
There are basically two different types of help entries that can be used. Internal help entries, that means the headline, text, etc is included in the help entry or external help entries, that means the help entry has only a reference pointing to a HTML/PHP page that offers the help entry.


4.1. Internal help entries

ext (REQUIRED)
Must be FALSE in this case.

Headline (REQUIRED)
The headline of this help entry. Can consist of any alpha-numeric characters. No HTML/CSS elements are not allowed here.

Text (REQUIRED)
The text of this help entry. Can constist if any alpha-numeric characters and can contain placeholder for variables passed to this help entry. The placeholder must follow the syntax for placeholder defined by the PHP printf function. HTML/CSS elements are allowed here as long as they follow the XHTML1.0 Strict specification.

When placeholders are included you can submit the values that should be displayed there as arguments when calling the templates/help.php file. There they are attached as var1, var2 and so on. The names must follow the following rules:

SeeAlso (OPTIONAL)
An array of references to anonther related subjects. Each row of the array must contain a field called "text" with the text that should be displayed and may contain a field called "link" which is used as value for the href attribute of a HTML tag when set.


4.2. External help entries

ext (REQUIRED)
Must be TRUE in this case.

Link (REQUIRED)
The complete filename of the file stored under the help/ directory which should be displayed when this help entry is called.



5. PDF syntax



6. Module meta data

6.1 can_manage()

    "account_types" => array

    Example: array("user", "host")

6.2 is_base_module()

    "is_base" => boolean

6.3 get_ldap_filter()

    "ldap_filter" => array

   Example: array('or' => 'objectClass=posixAccount', 'and' => '(!(uid=*$))')

6.4 get_dependencies()

    "dependencies" => array

   Example: array("depends" => array("posixAccount", array("qmail", "sendmail")), "conflicts" => array("exim"))

6.5 get_profileOptions()

    "profile_options" => array

   Syntax for array is the same as for the return value of get_profileOptions().

6.6 check_profileOptions()

    "profile_checks" => array

   The keys of the array are the names of the option identifiers.
   Each array element is an array containing these values:


6.7 get_configOptions()

    "config_options" => array('user' => array, 'host' => array, 'all' => array)

    The values from 'all' are always returned, the other values only if they are inside the $scopes array.

   Syntax for sub arrays is the same as for the return value of get_configOptions().

6.8 get_configDescriptions()

    "config_descriptions" => array

   Syntax for array is the same as for the return value of get_configDescriptions().

6.9 check_configOptions()

    "config_checks" => array('user' => array, 'host' => 'array', 'all' => array)

    The values from 'all' are always used for checking, the other values only if they are inside the $scopes array.

   Syntax for sub arrays is the same as for check_profileOptions().