From b3192badd5b1c7b09ecd7cbc97898ee1ae300bb2 Mon Sep 17 00:00:00 2001
From: Roland Gruber <post@rolandgruber.de>
Date: Thu, 26 Aug 2004 18:16:02 +0000
Subject: [PATCH] finished list documentation

---
 lam/docs/devel/lists.htm | 84 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)

diff --git a/lam/docs/devel/lists.htm b/lam/docs/devel/lists.htm
index 42fa3edf..348b51f0 100644
--- a/lam/docs/devel/lists.htm
+++ b/lam/docs/devel/lists.htm
@@ -15,5 +15,89 @@
 </div>
 <br>
 <br>
+<br>
+The account lists are all built after the same schema. They provide a
+list of found accounts which can be restricted by LDAP filters and the
+LDAP OU (Organizational Unit).<br>
+<br>
+The list of LDAP attributes and thus table columns is taken from the
+configuration profile (<span
+ style="font-weight: bold; font-style: italic;">get_...listAttributes()</span>
+in config.inc). Each account list has a separate list of attributes.<br>
+Only these attributes are given the LDAP search as attribute parameter.<br>
+There is also a predefined description list for the attributes in
+lists.inc. The user may use other values by setting them in the
+configuration profile.<br>
+<br>
+The number of accounts per page is limited in the configuration profile
+(<span style="font-weight: bold; font-style: italic;">get_MaxListEntries()</span>
+in config.inc). There will be links at the beginning and end of the
+list if more accounts were found.<br>
+<br>
+Several common helper functions for sorting and some page elements
+reside in lists.inc.<br>
+<br>
+<h2>1. Getting accounts from LDAP</h2>
+Each account list has its own LDAP suffix which is saved in the
+configuration profile. This is used as search base.<br>
+The account modules provide an LDAP filter (<span
+ style="font-weight: bold; font-style: italic;">get_ldap_filter()</span>
+in modules.inc) to get only accounts of a special type.<br>
+<br>
+This list can be further reduced if the user provides an additional
+LDAP filter with the filter boxes or selects another LDAP OU with the
+drop-down-box.<br>
+<br>
+<h2>2. Caching LDAP accounts</h2>
+The lists usually do not ask the LDAP server for an account list every
+time the user changes the page. The accounts are cached in the session.<br>
+<br>
+A new LDAP search is done if the user:<br>
+<ul>
+  <li>changes to another account list or tool</li>
+  <li>adds/modifies an account</li>
+  <li>selects the "refresh" button</li>
+  <li>adds additional LDAP filters or changes the LDAP OU<br>
+  </li>
+</ul>
+<br>
+It is <span style="font-style: italic;">not</span> done if the user:<br>
+<ul>
+  <li>changes the list pages if there are more accounts than what can
+be shown</li>
+  <li>sorts the list</li>
+</ul>
+<br>
+<h2>3. Adding/Editing accounts</h2>
+There are buttons at the end of the page to add/delete accounts. Adding
+accounts is done by account/edit.php and deleting by delete.php.<br>
+<br>
+The user can use the link in each account row to modify (in
+accounts/edit.php) the account. This can also be done by double
+clicking the row if Java Script is enabled.<br>
+<br>
+<br>
+<h2>4. Export to PDF</h2>
+The user can generate PDF files for the accounts. This is done by the <span
+ style="font-style: italic; font-weight: bold;">createModulePDF()</span>
+function from pdf.inc.<br>
+<br>
+<br>
+<h2>5. Special abilities of some lists</h2>
+<h3>5.1. The user list</h3>
+If the attribute <span style="font-style: italic;">gidNumber</span> is
+shown as table column then there will be an additional checkbox to
+translate the GID to the group name.<br>
+This checkbox is hidden if <span style="font-style: italic;">gidNumber</span>
+is not part of the attribute list.<br>
+<br>
+<h3>5.2. The group list</h3>
+If the attribute memberUID is shown as table column then all values of
+this attribute are shown as links.<br>
+These links redirect to userlink.php which tries to find the given user
+and redirects to account/edit.php for account modifying.<br>
+<br>
+<br>
+<br>
 </body>
 </html>