WMDE
/
LDAPAccountManager
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
LDAPAccountManager/lam/docs/modules-specification.htm

462 lines
18 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="content-type"
content="text/html; charset=ISO-8859-15">
<title>Module specification</title>
</head>
<body>
<h1 style="text-align: center;">This document describes the module
interface for LDAP Account Manager</h1>
<br>
<br>
<h2>1. Location and naming of modules</h2>
All LAM modules are placed in lib/modules/ and are named "&lt;class
name&gt;.inc".<br>
E.g. if you create a new module and its class name is "qmail" then the
filename would be "qmail.inc".<br>
<br>
The class name of a module must contain only a-z, A-Z, 0-9, -, and _.<br>
<br>
<br>
<h2>2. Class functions</h2>
<h3>2.1. Static functions</h3>
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.<br>
<h3><br>
</h3>
<h3>2.1.1. can_manage</h3>
<br>
<table style="text-align: left; width: 300px;" border="0"
cellspacing="2" cellpadding="2">
<tbody>
<tr>
<td
style="vertical-align: top; background-color: rgb(204, 204, 204); text-align: center;"><span
style="font-weight: bold;">function can_manage($scope)</span><br>
</td>
</tr>
</tbody>
</table>
<br>
Returns <span style="font-style: italic;">true</span> if this module
can manage accounts of type <span style="font-style: italic;">$scope</span>,
otherwise <span style="font-style: italic;">false</span>.<br>
The <span style="font-weight: bold;">$scope</span> parameter defines
the account type ("user", "group", "host" at this time).<br>
<br>
<br>
<h3>2.1.2. get_alias</h3>
<br>
<table cellpadding="2" cellspacing="2" border="0"
style="text-align: left; width: 300px;">
<tbody>
<tr>
<td
style="vertical-align: top; background-color: rgb(204, 204, 204); text-align: center;"><span
style="font-weight: bold;">function get_alias($scope)</span><br>
</td>
</tr>
</tbody>
</table>
<br>
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.<br>
Please take care that your alias name is not too long. It may contain
a-z, A-Z, 0-9, -, _ and spaces.<br>
The <span style="font-weight: bold;">$scope</span> parameter defines
the account type ("user", "group", "host" at this time).<br>
<br>
<h3>2.1.3. is_base_module</h3>
<br>
<table cellpadding="2" cellspacing="2" border="0"
style="text-align: left; width: 300px; height: 30px;">
<tbody>
<tr>
<td
style="vertical-align: top; background-color: rgb(204, 204, 204); text-align: center;"><span
style="font-weight: bold;">function is_base_module($scope)</span><br>
</td>
</tr>
</tbody>
</table>
<br>
Returns <span style="font-weight: bold;">true</span> if your module is
a base module and otherwise <span style="font-weight: bold;">false</span>.<br>
<span style="font-weight: bold;">$scope</span> is the account type
("user", "group", "host" at this time).<br>
<br>
Every account type needs at least one base module. A base module
defines a full qualified account.<br>
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.<br>
<br>
<h3>2.1.4. get_ldap_filter</h3>
<br>
<table cellpadding="2" cellspacing="2" border="0"
style="text-align: left; width: 300px; height: 30px;">
<tbody>
<tr>
<td
style="vertical-align: top; background-color: rgb(204, 204, 204); text-align: center;"><span
style="font-weight: bold;">function get_ldap_filter($scope)</span><br>
</td>
</tr>
</tbody>
</table>
<br>
Returns a string that can be used as part of a LDAP filter. Usually
used to filter object classes.<br>
<span style="font-weight: bold;">$scope</span> is the account type
("user", "group", "host" at this time).<br>
<br>
All filter parts of the base modules are combined with OR and used to
find the accounts for the lists.<br>
<br>
<span style="font-weight: bold;">Example: <span
style="font-style: italic;">return "(objectClass=posixAccount)"</span></span><br>
<br>
<span style="font-weight: bold; color: rgb(255, 0, 0);">This function
is only used for base modules. Standard modules do not need to
implement it.</span><br>
<br>
<h3>2.1.5. get_dependencies</h3>
<br>
<table style="text-align: left; width: 300px; font-weight: bold;"
border="0" cellspacing="2" cellpadding="2">
<tbody>
<tr>
<td
style="vertical-align: top; background-color: rgb(204, 204, 204); text-align: center;">function
get_dependencies($scope)<br>
</td>
</tr>
</tbody>
</table>
<br>
This function returns a list of modules it depends on.<br>
The <span style="font-weight: bold;">$scope</span> parameter defines
the account type ("user", "group", "host" at this time).<br>
<br>
The return value is an array with two sub arrays, <span
style="font-weight: bold;">"depends"</span> and <span
style="font-weight: bold;">"conficts"</span>.<br>
All values of the conflict array are string values with module names.<br>
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.<br>
<br>
<span style="font-weight: bold;">Example: </span><span
style="font-weight: bold; font-style: italic;">return array("depends"
=&gt; array("posixAccount", array("qmail", "sendmail")), "conflicts"
=&gt; array("exim"));</span><br
style="font-weight: bold; font-style: italic;">
<br>
<h3>2.1.6. get_profileOptions</h3>
<br>
<table cellpadding="2" cellspacing="2" border="0"
style="text-align: left; width: 300px; height: 30px;">
<tbody>
<tr>
<td
style="vertical-align: top; background-color: rgb(204, 204, 204); text-align: center;"><span
style="font-weight: bold;">function get_profileOptions($scope)</span><br>
</td>
</tr>
</tbody>
</table>
<br>
This function defines what attributes will be used in the account
profiles and their appearance in the profile editor.<br>
<br>
<span style="font-weight: bold;">$scope</span> is the account type
("user", "group", "host" at this time).<br>
The return value is an array that contains <span
style="font-weight: bold;">meta HTML code</span>.<br>
<br>
The type "fieldset" is not allowed here.<br>
The <span style="font-style: italic;">name</span> 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.<br>
<br>
<h3>2.1.7. check_profileOptions</h3>
<br>
<table style="text-align: left; width: 400px; height: 30px;" border="0"
cellspacing="2" cellpadding="2">
<tbody>
<tr>
<td
style="vertical-align: top; background-color: rgb(204, 204, 204); text-align: center;"><span
style="font-weight: bold;">function check_profileOptions($scope,
$options)</span><br>
</td>
</tr>
</tbody>
</table>
<br>
This function checks the input for a new or modified account profile.<br>
<br>
<span style="font-weight: bold;">$scope</span> is the account type
("user", "group", "host" at this time).<br>
<span style="font-weight: bold;">$options</span> is an hash array
(option name =&gt; value) that contains the input. The option values
are all arrays containing one or more elements.<br>
If the input data is invalid the return value is an array that contains
arrays to build StatusMessages (0 =&gt; message type, 1 =&gt; message
head, 2 =&gt; message text, 3 =&gt; additional variables).<br>
If no errors occured the function returns an empty array.<span
style="font-weight: bold;"></span><br>
<br>
<br>
<h3>2.2. Class functions</h3>
<h3>2.2.1. Constructor</h3>
<br>
<table style="text-align: left; width: 300px; height: 30px;" border="0"
cellspacing="2" cellpadding="2">
<tbody>
<tr>
<td
style="vertical-align: top; background-color: rgb(204, 204, 204); text-align: center;"><span
style="font-weight: bold;">function &lt;module name&gt; ($base)</span><br>
</td>
</tr>
</tbody>
</table>
<br>
Every module needs a constructor that has an<span
style="font-style: italic;"> <span style="font-weight: bold;">account
container</span></span> as argument $base.<br>
With this account container you can interact with other modules and use
several helper functions.<br>
<br>
<h3>2.2.2. module_ready</h3>
<br>
<table style="text-align: left; width: 300px; height: 30px;" border="0"
cellspacing="2" cellpadding="2">
<tbody>
<tr>
<td
style="vertical-align: top; background-color: rgb(204, 204, 204); text-align: center;"><span
style="font-weight: bold;">function module_ready()</span><br>
</td>
</tr>
</tbody>
</table>
<br>
Your module might depend on input of other modules. This function
determines if the module button on the account page is active or not.<br>
The return value is <span style="font-weight: bold;">true</span> if
your module accepts input, otherwise <span style="font-weight: bold;">false</span>.<br>
<br>
<h3>2.2.3. module_complete</h3>
<br>
<table cellpadding="2" cellspacing="2" border="0"
style="text-align: left; width: 300px; height: 30px;">
<tbody>
<tr>
<td
style="vertical-align: top; background-color: rgb(204, 204, 204); text-align: center;"><span
style="font-weight: bold;">function module_complete()</span><br>
</td>
</tr>
</tbody>
</table>
<br>
This function is called after your module has processed the POST input
data.<br>
If there was an input error and you want to display a page again then
return <span style="font-weight: bold;">false</span>. If <span
style="font-weight: bold;">true</span> is returned the next module
page will be displayed.<br>
<br>
<h3>2.2.4. get_help</h3>
<br>
<table cellpadding="2" cellspacing="2" border="0"
style="text-align: left; width: 300px; height: 30px;">
<tbody>
<tr>
<td
style="vertical-align: top; background-color: rgb(204, 204, 204); text-align: center;"><span
style="font-weight: bold;">function get_help($helpID)</span><br>
</td>
</tr>
</tbody>
</table>
<br>
This function is called when a page requests a help topic from this module.<br>
<span style="font-weight: bold;">$helpID</span> is the help identifier; it must only contain a-z, A-Z, 0-9
-, . and _.<br>
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".<br>
<br>
<h3><br>
</h3>
<h2>3. Meta HTML code</h2>
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.<br>
Meta HTML code is always returned as a three dimensional <span
style="font-weight: bold;">array[a][b][c]</span> where <span
style="font-weight: bold;">a</span> is the row number, <span
style="font-weight: bold;">b</span> is the coumn number and <span
style="font-weight: bold;">c</span> is is a <span
style="font-style: italic;">data elememt</span>.<br>
<br>
<span style="font-weight: bold;">Format for <span
style="font-style: italic;">data elements</span>:</span><br>
<br>
A <span style="font-style: italic;">data element</span> is an array
which contains the data to display.<br>
All <span style="font-style: italic;">data elements</span> must
contail a value <span style="font-weight: bold;">"kind"</span> which
defines what kind of element should be displayed.<br>
<br>
These are the possibilies for <span style="font-weight: bold;">kind</span>
and what other options are implicated:<br>
<br>
<ul>
<li><span style="font-weight: bold;">fieldset:</span> Inserts a
fieldset.</li>
<ul>
<li><span style="font-weight: bold;">legend:</span> The legend of
the fieldset.</li>
<li><span style="font-weight: bold;">value:</span> A <span
style="font-style: italic;">data element</span>. Can be used
recursively.</li>
</ul>
<li><span style="font-weight: bold;">help:</span> Adds a help link.</li>
<ul>
<li><span style="font-weight: bold;">value:</span> The help number
for the help entry.</li>
</ul>
<li><span style="font-weight: bold;">input:</span> Adds a HTML input
element.</li>
<ul>
<li><span style="font-weight: bold;">name:</span> The name of the
element, will be used later as variable name when user input is
returned.</li>
<li><span style="font-weight: bold;">type:</span> allowed values:
submit, reset, checkbox, text, password, file, hidden</li>
<li><span style="font-weight: bold;">checked:</span> Boolean value,
if true a checkbox will be checked. This value is only needed or
checkboxes.</li>
<li><span style="font-weight: bold;">disabled:</span> Boolean
value, if true the element will be disabled.</li>
<li><span style="font-weight: bold;">size:</span> The length of the
input element, only used for text, password and file.</li>
<li><span style="font-weight: bold;">maxlength:</span> The maximum
size of the input element, only used for text, password and file.</li>
<li><span style="font-weight: bold;">value:</span> The element will
have this value as default. Button elements will have this as caption.</li>
</ul>
<li><span style="font-weight: bold;">select:</span> This will add a
select field.</li>
<ul>
<li><span style="font-weight: bold;">name:</span> The name of the
element, will be used later as variable name when user input is
returned.</li>
<li><span style="font-weight: bold;">multiple:</span> Boolean
value, if set to true the user can select more than one entry.</li>
<li><span style="font-weight: bold;">options:</span> Array of
string. This is the list of option values the user can select.</li>
<li><span style="font-weight: bold;">options_selected:</span> Array
of string. This is the list of pre selected elements, must contain
values that are also in <span style="font-style: italic;">options</span>.</li>
<li><span style="font-weight: bold;">size:</span> The size of the
select field, if set to 1 a dropdown box will be displayed.</li>
</ul>
<li><span style="font-weight: bold;">table:</span> Adds a table. Can
be used recursively.</li>
<ul>
<li><span style="font-weight: bold;">value:</span> A <span
style="font-style: italic;">data element</span>. Can be used
recursively.</li>
</ul>
<li><span style="font-weight: bold;">text:</span> Inserts a text
element.</li>
<ul>
<li><span style="font-weight: bold;">text:</span> The text to
display.</li>
</ul>
</ul>
<br>
Beneath those values a <span style="font-weight: bold;">"td"</span>
value may be added. This has to be an array with one or more of these
options:<br>
<br>
<ul>
<li><span style="font-weight: bold;">colspan:</span> Like the HTML
colspan attribute for td elements.</li>
<li><span style="font-weight: bold;">rowspan:</span> Like the HTML
rowspan attribute for td elements.</li>
<li><span style="font-weight: bold;">align:</span>
left/center/right/justify Like the HTML align attribute.</li>
</ul>
<br>
<span style="font-weight: bold;">Example:</span><span
style="font-family: monospace;"><br>
<br>
</span><code>array(<br>
&nbsp; array(<br>
&nbsp;&nbsp;&nbsp; array("kind" =&gt; "text", "text" =&gt; "This is an
example", "td" =&gt; array("colspan" =&gt; 3))<br>
&nbsp; ), <br>
&nbsp; array(<br>
&nbsp;&nbsp;&nbsp; array("kind" =&gt; "text", "text" =&gt; "Input:"),<br>
&nbsp; &nbsp; array("kind" =&gt; "input", "name" =&gt; "myinput",
"type" =&gt; "text"),<br>
&nbsp; &nbsp; array("kind" =&gt; "help", "value" =&gt; "42")<br>
&nbsp; )<br>
)<br>
</code><br>
<br>
<h3><br>
</h3>
<h2>4. Help entry syntax</h2>
The array that is returned by the get_help function must follow the below described syntax.
Fields marked <b>REQUIRED</b> are neccessary under any circumstances. Fields marked
<b>OPTIONAL</b> may be left out when not needed.<br>
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.
<br>
<h3><br>4.1. Internal help entries</h3>
<span style="font-weight: bold;">ext</span> <span style="font-style: italic;">(REQUIRED)</span>
<br>Must be <b>FALSE</b> in this case.
<br><br>
<span style="font-weight: bold;">Headline</span> <span style="font-style: italic;">(REQUIRED)</span>
<br>The headline of this help entry. Can consist of any alpha-numeric characters. No HTML/CSS
elements are not allowed here.
<br><br>
<span style="font-weight: bold;">Text</span> <span style="font-style: italic;">(REQUIRED)</span>
<br>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 <b>printf</b> function. HTML/CSS elements are allowed here as long
as they follow the XHTML1.0 Strict specification.<br><br>
When placeholders are included you can submit the values that should be displayed there as arguments
when calling the <b>templates/help.php</b> file. There they are attached as <b>var1</b>, <b>var2</b>
and so on. The names must follow the following rules:<br>
<ul>
<li>1. They must be named <b>var$i</b> where $i is any positive number except the '0'.</li>
<li>2. This number ($i) must either be '1' or $i -1 must be present.</li>
</ul>
<br>
<span style="font-weight: bold;">SeeAlso</span> <span style="font-style: italic;">(OPTIONAL)</span>
<br>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 <a> tag when set.
<br>
<h3><br>4.2. External help entries</h3>
<span style="font-weight: bold;">ext</span> <span style="font-style: italic;">(REQUIRED)</span>
<br>Must be <b>TRUE</b> in this case.
<br><br>
<span style="font-weight: bold;">Link</span> <span style="font-style: italic;">(REQUIRED)</span>
<br>The complete filename of the file stored under the help/ directory which should be displayed
when this help entry is called.
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink