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

2. Class functions

2.1. Static functions

These functions are called without instanciating an object of the module class. They must not depend on class variables and are only allowed to call other static functions.

2.1.1. Constructor

function <module name> ($base)

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

2.1.2. get_alias

function get_alias($scope)

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 a-z, A-Z, 0-9, -, _ and spaces.
The $scope parameter defines the account type ("user", "group", "host" at this time).

2.1.3. get_dependencies

function get_dependencies($scope)

This function returns a list of modules it depends on.
The $scope parameter defines the account type ("user", "group", "host" at this time).

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.4. 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.1.5. 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.1.6. is_base_module

function is_base_module($scope)

Returns true if your module is a base module and otherwise false.
$scope is the account type ("user", "group", "host" at this time).

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

function get_ldap_filter($scope)

Returns a string that can be used as part of a LDAP filter. Usually used to filter object classes.
$scope is the account type ("user", "group", "host" at this time).

All filter parts of the base modules are combined with OR and used to find the accounts for the lists.

Example: return "(objectClass=posixAccount)"

This function is only used for base modules.

2.1.8. get_profileOptions

function get_profileOptions($scope)

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

$scope is the account type ("user", "group", "host" at this time).
The return value is an array that contains meta HTML code.

The type "fieldset" is not allowed here.

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:

fieldset: Inserts a fieldset.

legend: The legend of the fieldset.
value: A data element. Can be used recursively.

help: Adds a help link.

value: The help number for the help entry.

input: Adds a HTML input element.

name: The name of the element, will be used later as variable name when user input is returned.
type: allowed values: submit, reset, checkbox, text, password, file, hidden
checked: Boolean value, if true a checkbox will be checked. This value is only needed or checkboxes.
disabled: Boolean value, if true the element will be disabled.
size: The length of the input element, only used for text, password and file.
maxlength: The maximum size of the input element, only used for text, password and file.
value: The element will have this value as default. Button elements will have this as caption.

select: This will add a select field.

name: The name of the element, will be used later as variable name when user input is returned.
multiple: Boolean value, if set to true the user can select more than one entry.
options: Array of string. This is the list of option values the user can select.
options_selected: Array of string. This is the list of pre selected elements, must contain values that are also in options.
size: The size of the select field, if set to 1 a dropdown box will be displayed.

table: Adds a table. Can be used recursively.

value: A data element. Can be used recursively.

text: Inserts a text element.

text: The text to display.

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

colspan: Like the HTML colspan attribute for td elements.
rowspan: Like the HTML rowspan attribute for td elements.
align: left/center/right/justify Like the HTML align attribute.

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")

  )

)