Custom fields

lam/HISTORY

@@ -1,5 +1,7 @@
 June 2012
   - quick (un)lock for users
+  - LAM Pro:
+   -> Custom fields module allows to manage custom LDAP attributes in Self Service
 
 
 25.03.2012 3.7

lam/docs/manual-sources/howto.xml

@@ -3083,6 +3083,245 @@ Run slapindex to rebuild the index.
       module in slapd.conf to use this feature.</para>
     </section>
 
+    <section>
+      <title>Custom fields (LAM Pro)</title>
+
+      <para>This module allows you to manage LDAP attributes that are not
+      covered by the other LAM modules (e.g. if you use custom LDAP schemas).
+      You can fully define how your input fields look like:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>Label</para>
+        </listitem>
+
+        <listitem>
+          <para>LDAP attribute name</para>
+        </listitem>
+
+        <listitem>
+          <para>Unique name for field</para>
+        </listitem>
+
+        <listitem>
+          <para>Read-only display</para>
+        </listitem>
+
+        <listitem>
+          <para>Field type: text, password, text area, checkbox, radio
+          buttons, select list</para>
+        </listitem>
+
+        <listitem>
+          <para>Validation via regular expression</para>
+        </listitem>
+
+        <listitem>
+          <para>Error message if validation fails</para>
+        </listitem>
+      </itemizedlist>
+
+      <para><emphasis role="bold">Attention:</emphasis> This module is only
+      available for LAM Pro Self Service.</para>
+
+      <para>To create custom fields for the Self Service please edit your Self
+      Service profile and switch to tab "Module settings". Here you can add a
+      new field. Simply fill the fields and press on "Add".</para>
+
+      <para>Please note that the field name cannot be changed later. It is the
+      unique ID for this field.</para>
+
+      <para>After you created your fields please press on "Sync fields with
+      page layout". Now you can switch to tab "Page layout" and add your new
+      fields like any other standard field.</para>
+
+      <screenshot>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="images/customFields1.png" />
+          </imageobject>
+        </mediaobject>
+      </screenshot>
+
+      <para>Examples for fields and their representation in Self
+      Service:</para>
+
+      <para><emphasis role="bold">Text field:</emphasis></para>
+
+      <para>Text fields can be set read-only. They allow to specify a <link
+      linkend="customFields_validation_expressions">validation
+      expression</link> and error message.</para>
+
+      <screenshot>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="images/customFields2.png" />
+          </imageobject>
+        </mediaobject>
+      </screenshot>
+
+      <para>Presentation in Self Service:</para>
+
+      <screenshot>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="images/customFields3.png" />
+          </imageobject>
+        </mediaobject>
+      </screenshot>
+
+      <para><emphasis role="bold">Password field:</emphasis></para>
+
+      <para>You can also manage custom password fields. LAM Pro will display
+      two fields where the user must enter the same password. You can hash the
+      password if needed.</para>
+
+      <screenshot>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="images/customFields4.png" />
+          </imageobject>
+        </mediaobject>
+      </screenshot>
+
+      <para>Presentation in Self Service:</para>
+
+      <screenshot>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="images/customFields5.png" />
+          </imageobject>
+        </mediaobject>
+      </screenshot>
+
+      <para><emphasis role="bold">Text area:</emphasis></para>
+
+      <para>This adds a multi-line field. The options are similar to text
+      fields. Additionally, you can set the size with the number of columns
+      and rows.</para>
+
+      <para>Please note that the <link
+      linkend="customFields_validation_expressions">validation
+      expression</link> should be set to multi-line. This is done by adding
+      "m" at the end.</para>
+
+      <screenshot>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="images/customFields6.png" />
+          </imageobject>
+        </mediaobject>
+      </screenshot>
+
+      <para>Presentation in Self Service:</para>
+
+      <screenshot>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="images/customFields7.png" />
+          </imageobject>
+        </mediaobject>
+      </screenshot>
+
+      <para><emphasis role="bold">Checkbox:</emphasis></para>
+
+      <para>Sometimes you may want to allow only yes/no values for your LDAP
+      attributes. This can be represented by a checkbox. You can specify the
+      values for checked and unchecked. The default value is set if the LDAP
+      attribute has no value.</para>
+
+      <screenshot>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="images/customFields8.png" />
+          </imageobject>
+        </mediaobject>
+      </screenshot>
+
+      <para>Presentation in Self Service:</para>
+
+      <screenshot>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="images/customFields9.png" />
+          </imageobject>
+        </mediaobject>
+      </screenshot>
+
+      <para><emphasis role="bold">Radio buttons:</emphasis></para>
+
+      <para>This displays a list of radio buttons where the user can select
+      one value.</para>
+
+      <para>You can specify a mapping of LDAP attribute values and their
+      display (label) on the Self Service page. To add more mapping fields
+      please press "Add more mapping fields".</para>
+
+      <screenshot>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="images/customFields10.png" />
+          </imageobject>
+        </mediaobject>
+      </screenshot>
+
+      <para>Presentation in Self Service:</para>
+
+      <screenshot>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="images/customFields11.png" />
+          </imageobject>
+        </mediaobject>
+      </screenshot>
+
+      <para><emphasis role="bold">Select list:</emphasis></para>
+
+      <para>Select lists allow the user to select a value in a large list of
+      options. The definition of the possible values and their display is
+      equal to radio buttons.</para>
+
+      <screenshot>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="images/customFields12.png" />
+          </imageobject>
+        </mediaobject>
+      </screenshot>
+
+      <para>Presentation in Self Service:</para>
+
+      <screenshot>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="images/customFields13.png" />
+          </imageobject>
+        </mediaobject>
+      </screenshot>
+
+      <para id="customFields_validation_expressions"><emphasis
+      role="bold">Validation expressions:</emphasis></para>
+
+      <para>The validation expressions follow the standard of <ulink
+      url="http://perldoc.perl.org/perlre.html">Perl regular
+      expressions</ulink>. They start and end with a "/". The beginning of a
+      line is specified by "^" and the end by "$".</para>
+
+      <para>Examples:</para>
+
+      <para>/^[a-z0-9]+$/ allows small letters and numbers. The value must not
+      be empty ("+").</para>
+
+      <para>/^[a-z0-9]+$/i allows small and capital letters ("i" at the end
+      means ignore case) and numbers. The value must not be empty
+      ("+").</para>
+
+      <para>Special characters that must be escaped with "\": "\", ".", "(",
+      ")"</para>
+
+      <para>E.g. /^[a-z0-9\.]$/i</para>
+    </section>
+
     <section>
       <title>Custom scripts (LAM Pro)</title>