Chapter 13   Customizing the User Interface


This chapter provides instructions for modifying the HTML pages that make up the Delegated Administrator user interface.

This chapter contains the following sections:

• HTML Templates

• Configuration Data

• NDAGetPage Servlet

• Customizing the Display of Search Results

• Customizing HTML Templates

HTML Templates

---

Delegated Administrator provides preconfigured templates from which its HTML user interface is generated. These templates are simply text files containing HTML with embedded directives. Each directive provides instructions about what HTML text or values to display, and how to display them.

The templates are stored in the following directory:

<delegatedadmin_root>/nda/nda/default/en/templates

You can modify these templates to make changes in the Administrator Pages and their related dialogs. These are examples of page elements you can modify:

• Colors, images, and banners

• Onscreen text including field and control labels

• Data generated as a result of LDAP lookups

How the Templates Work

Delegated Administrator includes a Page Generator, a component that dynamically generates the HTML user interface based upon user-entered data and corresponding data in the Directory Server database. Each time an administrator invokes an operation from an HTML page, Page Generator parses directives embedded in a corresponding HTML template. The directives, along with data from the Directory Server, then dynamically generate the next appropriate HTML page.

Figure 13-1    Page Generator parses HTML with embedded directives.

For example, when a Top-level Administrator logs in, he enters his user ID and password into the Login page, which invokes the postLogin operation. Page Generator parses the User ID and password together with directives embedded in the Login page, and maps the following:

[ postLogin + serviceadm ] -> templates/isp/index.html

Page Generator then displays the file index.html which is the Top-level Administrator page.

When an end user logs in, Page Generator maps the following:

[ postLogin + enduser ] -> templates/enduser/My-acct/index.html

In this case, Page Generator displays the file enduser/My-acct/index.html, which is the User Account page.

There is an HTML page associated with each Delegated Administrator operation. For each operation, there are mappings for each of the defined user types. You can customize Delegate Administrator by modifying its operations, directives, or HTML pages.

To change the user directory content, modify directives and organization configuration as explained in the rest of this chapter. To change the look and feel of the user interface, use standard HTML to modify the template files in the new organization directory. The new user interface will be displayed when a user logs in against the new organization.

Creating Templates for a New Organization

When you create a new organization, if you want to customize its templates (HTML pages), you must create a new directory for the templates. You must also create a new Start page and a new Login page for the organization.

By default, the Page Generator uses templates from the following directory:

<delegatedadmin_root >/nda/nda/default

Create a directory for the new organization under the Delegated Administrator root. You can give the directory any name. Page Generator will use the configuration and templates in this new organization directory.

To create a templates directory for a new organization:

1. Create a new directory at this location:

   <delegatedadmin_root >/nda/nda

2. Recursively copy the contents of the directory
   <delegatedadmin_root >/nda/nda/default to the new organization directory.

To create new Start and Login Pages

1. Copy these files to the directory where your organization files are stored:

   <delegatedadmin_root>/nda/nda/start.htm

   <delegatedadmin_root>/nda/nda/login.htm

2. In the file start.htm, set the value of the form element organization to the dn component for the new organization. For example:

   var domain = "o=Airius.com";

3. In the file login.htm, modify the following line, replacing o=Airius.com with the base DN for the new organization:

   var domain = "o=Airius.com";

4. 4. In the file <delegatedadmin_root>/nda/nda/domain.map, create a new entry for the organization. For example, if the new organization is CompanyABC.com, and the templates are stored under <delegatedadmin_root>/nda/nda/ComapnyABC, then add the following entry:
   
   

Configuration Data

---

The default configuration for a Delegated Administrator organization is stored in the Directory Server under the following DN:

cn=domainconfig, ou=configuration, o=<base suffix>

It includes information specific to the organization including: permissible users types; user type options; and search locations, filters, and scope.

The opconf area of the Directory Server stores information for mapping operations to template files. (For more information, see Determining the Appropriate Template.) The mainconf area of the Directory Server contains datatype identifiers and matchtype identifiers. The macrosconf area of the Directory Server contains Delegated Administrator macros.

Datatype Identifiers

The datatype identifier provides information about the supported types of data obtainable from the directory under the following DN:

cn=domainconfig, ou=configuration, o=<base suffix>

A datatype identifier is a category of one or more entries that are returned from the database as a result of a search that qualifies that datatype. For example, the datatype isp refers to the entry returned as a result of a search done on the directory tree with the basedn o=ISP, using a BASE scope with a filter objectclass=nsManagedISP.

dn: cn=isp, cn=datatypes, cn=mainconf, cn=en, cn=domainConfiguration, ou=config, o=ISP objectclass: top objectclass: extensibleObject cn: isp iDAhandle: isp iDAdisplayText: ISP iDAbaseDN: $ISPDN$ iDAscope: BASE iDAfilter: objectclass=nsManagedISP

Similarly, the datatype domainlist refers to the list of entries returned as a result of a search done on the directory tree with the base dn of o=ISP, with a SUBTREE scope and a filter objectclass=nsManagedDomain.

dn: cn=alldomains, cn=datatypes, cn=mainconf, cn=en, cn=domainConfiguration, ou=config, o=ISP objectclass: top objectclass: extensibleObject cn: alldomains iDAhandle: alldomains iDAdisplayText: All Domains iDAbaseDN: $ISPDN$ iDAscope: SUBTREE iDAfilter: objectclass=nsManagedDomain

Defining New Datatypes

You can define new datatypes that the templates can refer to. You can also allow the backend to automatically obtain information for extracting data from the directory. To do this, you must completely define the new datatype by providing values for the basedn, scope, and filter. The attribute list may be left out if you don't need it. This allows you to define new types of searches that can be invoked from the templates without any change to the servlets.

Internal Datatypes

You need internal datatypes only when you write your own servlets and need to preserve or list one or more entries across form submissions. If data is not committed into your database, while you are doing some preprocessing or composite operation on it across form invocations, you may need to define internal datatypes. This involves creating a new datatype in the mainconf area of the Directory Server. You must also provide the data for the internal datatype by registering it with the datatype name in the hash table of the HttpSession object. The Page Generator extracts the data from the HttpSession object and populates it into the HTML being generated from the template.

Matchtype Identifiers

Identifiers of matchtype associate the list-box text that the user selects in the List interface with a specified pattern.

Syntax

matchtype "<text>" "(<pattern>))"

Examples

matchtype "is" "(%a=%v))"

matchtype "is not" "(!(%a=%v)))"

matchtype "sounds like" "(%a~=%v))"

matchtype "starts with" "(%a=%v*))"

matchtype "ends with" "(%a=*%v))"

matchtype "contains" "(%a=*%v*))"

Macros

Macros define generic datatypes whose definitions do not need to specify organization or department names.

Macros are strings that occur in datatype definitions as literals enclosed within $ characters. A macro has the format $<identifier>$. The following macros are defined in the file <delegatedadmin_root>/nda/nda/config/macro.ldif:

Table 13-1    Delegated Administrator macros.

Macro	Description
$AncestorDomainDNs$	Keeps track of all ancestor domain DN values.
$AncestorDeptDNs$	Keeps track of all ancestor department DN values.
$DomainDN$	Keeps track of the current domain DN value.
$DomainContainerDN$	Keeps track of the current domain container DN value.
$DeptDN$	Keeps track of the current department DN value.
$FamilyGroupDN$	Keeps track of the current family group DN value.
$MailListDN$	Keeps track of the current mail list DN value.
$AdmDeptDN$	Keeps track of the current administrator group DN value.
$UserDN$	Keeps track of the current user DN value.
$AuthDomainDN$	Keeps track of the authenticated user's domain DN value.
$SelfDN$	Keeps track of the authenticated user's DN value.
$SelfPasswd$	Keeps track of the authenticated user's password value.
$ISPDN$	Keeps track of the root node for the NDA installation.

Macros allow you to substitute context-related information into the generic datatype definitions. This makes the definition independent of the context. For example, if a user logs in as an organization administrator for AnyCompany.com, and the Delegated Administrator base suffix is o=ISP, the macro $ISPDN$ is set to o=ISP and $DOMAINDN$ to o=AnyCompany.com,o=ISP. For the Organization Administrator for AnyCompany.com, the datatype deptlist refers to the entries returned as a result of a search on the BaseDN $DOMAINDN$ which evaluates to a baseDN of o=AnyCompany.com,o=ISP.

Delegated Administrator sets the appropriate macros defined by each administrator role at login. Table 13-2 summarizes the macros that are defined when a user logs in.

Table 13-2    Macros used with each administrator role

Role	$ISPDN$	$DOMAINDN$	$DEPTDN$	$USERDN$	$SELFDN$
Top-level Administrator
Organization Administrator
Group Administrator
Top-level Help Desk Administrator
Organization Help Desk Administrator
End User

If the corresponding macro name-value pair is passed as a parameter when a form is submitted to the servlet, then after the initial login, the NDAGetPage servlet sets further macros. The out-of-the-box forms pass these name-value pairs to the servlet as the context gets defined further. For example, upon logging in, a Top-level Administrator sees a list of organizations she has access to. Navigating to the organization level, the Top-level Administrator's context is specifically defined to the selected organization. Therefore, the form passes the name-value pair DOMAINDN=o=AnyCompany.com,o=ISP to the NDAGetPage servlet. The servlet then sets the value of the DOMAINDN macro for future reference.

---

Note	The form should never pass a new value for a macro that had been defined at login. This would overwrite the original value and may lead to an inconsistent state.

---

Supported Directives

Directives are instructions written as Server Side Include commands that are interpreted by the Page Generator. Each directive begins on a new line and exists as a single independent line of HTML in the template file. A directive may have zero or more arguments.

Delegated Administrator 4.5 supports the following directives:

• S_ENTRYBEGIN

• S_ENTRYEND

• S_ATTRBEGIN

• S_ATTREND

• S_ATTRIBUTE

• S_ATTRIBUTE_MULTIVALUED

• S_SEARCH_PARAMS

• S_PROGRAM

• S_SESSION

Syntax

Each directive instructs the Page Generator about what replacement HTML text and values to display and how to display them. Each directive begins on a new line and exists as a single independent line of HTML in the template file. The directives have syntax similar to Server Side Includes, and they may have zero or more quoted arguments:

<!-- <directive> "<arg1>=<value1>" "<arg2>=<value2>" ... -->

S_ENTRYBEGIN

This directive marks the start of a data group. A data group refers to the set of data (defined by a datatype) from which values will be retrieved and displayed. A data group can be a single LDAP entry or multiple LDAP entries in a search result. A data group is defined as a data type in Directory Server. For example, for the default configuration, you can find the datatype definitions for the Top-level suffix under the following entry:

dn: cn=isp, cn=datatypes, cn=mainconf, cn=en,  cn=domainConfiguration, ou=config, o=ISP

The S_ENTRYBEGIN directive must always be paired with an S_ENTRYEND directive. There can be multiple S_ENTRYBEGIN and S_ENTRYEND blocks in a given HTML template. However, these S_ENTRYBEGIN and S_ENTRYEND blocks may not be nested.

In the case where this directive marks the start of a data group with multiple LDAP entries in a search result, the section within the S_ENTRYBEGIN and S_ENTRYEND block are iterated for each search result. This means that any text within the S_ENTRYBEGIN and S_ENTRYEND directives are repeatedly output, and all embedded directives are evaluated for each LDAP entry in the search result set.

Arguments

datatype=<dataType>	Specifies the data type as defined in main.conf
option=<value>[,<value2>]	Permitted values are listed in Table 13-3.

Table 13-3    S_ENTRYBEGIN arguments

Option	Description
serversidesort	Indicates that results should be sorted on the server (This could cause a decrease in server performance.)
sizelimit	A non-negative number specifying how many entries to return from the search. If not specified, the sizelimit defaults to the defaultsizelimit set in the main.conf file. If set to 0, all entries from the search are returned without being subject to any limit.

Example
<!-- S_ENTRYBEGIN "datatype=usersinadmdeptlist" -->

S_ENTRYEND

This directive marks the end of an data group. Always paired with S_ENTRYBEGIN to end the block.

Arguments
None

S_ATTRBEGIN

This directive marks the start of a section for handling multivalued attributes.

The S_ATTRBEGIN directive must always be paired with an S_ATTREND directive. There can be multiple S_ATTBEGIN and S_ATTREND blocks in a given HTML template. However, these blocks may not be nested. An S_ATTRBEGIN...S_ATTREND block cannot appear within an S_ENTRYBEGIN...S_ENTRYEND block. An S_ENTRYBEGIN...S_ENTRYEND block cannot appear within an S_ATTRBEGIN...S_ATTREND block.

The section within the S_ATTRBEGIN and S_ATTREND block is iterated for each value of the attribute. This means that any text within the S_ATTRBEGIN and S_ATTREND directives are repeatedly output. All embedded directive are evaluated for each attribute value for the attr specified in the attr argument of this directive.

Arguments
datatype=<dataType>: specifies the data type as defined in the mainconf area of Directory Server.

attr=<value>: This refers to the multivalued attribute.

Example:
<!--S_ATTRBEGIN "datatype=self" "attr=ou"-->

S_ATTREND

This directive marks the end of a data group. Always paired with the S_ATTRBEGIN to end the block.

Arguments
None

S_ATTRIBUTE

The S_ATTRIBUTE directive is used for displaying or editing the contents of an attribute. It must always appear between the S_ENTRYBEGIN S_ENTRYEND block.

Arguments

attr=<attribute name>	Causes the corresponding attribute to be displayed. The special attribute 'dn' is also recognized.
datatype=<type of entry or list of entries>	Specifies the data group that overrides the datatype value specified in the S_ENTRYBEGIN directive. If the attribute value is to be displayed from the same data type as specified in the S_ENTRYBEGIN directive, this argument is not required. However, in the case where an attribute value from a different data group needs to be displayed, this argument can be used to override the one specified in the S_ENTRYBEGIN directive.
type = <how-to-display>	Renders the attribute on-screen in a particular format. The allowed values are listed in Table 13-4
option=<value>[,<value2>]	Permitted values are listed in Table 13-5.
defaultvalue=<default value>	Specifies the given default value for the attribute if none is retrieved from the DS
size=<number>	Sets the width of the displayed attribute to number

Table 13-4    S_ATTRIBUTE type values

Type	Display
text	Display as text
textarea	Show as an HTML TEXTAREA
radio	Show as a radio button
checkbox	Show as a checkbox
password	Show as an HTML password textbox
hidden	Set values in hidden form fields

Table 13-5    S_ATTRIBUTE option values

Options	Permitted values
readonly	Indicates that this attribute should not be displayed as editable
quoted	Indicates that the attribute value should be quoted

S_ATTRIBUTE_MULTIVALUED

This directive is used to display multivalued attributes. it can also be used for single valued attributes. However, only text and textarea types are currently supported. This directive must appear between the S_ENTRY_BEGIN and S_ENTRY_END directives.

Arguments

attr=<attribute name>	This refers to the attribute whose values need to be displayed.
type=<text or textarea>	The type of form element to be output.
mode=<single or multiple>	If mode is single, the multiple values are returned as a single string. The string is obtained by concatenating the values using the string specified by the separator as a delimiter. If mode is multiple, multiple form elements are generated. These form elements have the same name, but different values.
separator=<separator string>	This string is used to separate multiple values if the mode is specified as single.

---

Note

There are two ways to submit multi-valued attributes to the backend. Use multiple form elements with the same name, but different values. Submit a single string, with the multiple values separated by a separator string. This separator string can be specified by defining a hidden form element called valueSeparator. Its value is the string used for separating multiple values. The back end will then parse the single string and obtain the multiple values for the attribute.

---

S_SEARCH_PARAMS

This directive is used in conjunction with the S_ENTRYBEGIN directive for listing search results. This directive specifies the number of search results displayed per page (page size), as well as the attribute(s) to use to sort the search results. This directive must appear before the S_ENTRYBEGIN directive that marks the start of the search results listing.

Arguments

sortattr=<attrlist>	Specifies the attribute(s) to use to sort the search results. The colon character (:) can be used to specify sorting on more than one attribute.
step=<page_size>	Specifies the number of search results to display per page.

Example
<!-- S_SEARCH_PARAMS "step=5" "sortattr=uid" -->

S_PROGRAM

Provides a way of plugging in a custom class for augmenting page generation. At the point in the template where this directive occurs, a class by the name specified in the class parameter, which implements the iPageGenCustomModule interface, is instantiated and its execute() method invoked.

This is a useful tool since the PageGenerator can only generate output for a simple search. When the data needs to be obtained through composite searches, separate logic must be added to handle it. This directive provides a means to do that.

Arguments:

lang=<language>	Specifies the programming language in which the module is implemented.
class=<class name>	Specifies the class name to instantiate.

S_SESSION

This directive provides a means to display values of (Http)Session parameters. This is useful to display values that are not part of a user entry. An example of such usage is the display of the time string when a password is about to expire.

Arguments

param

Specifies the session parameter whose value needs to be output.

NDAGetPage Servlet

---

The NDAGetPage servlet offers a generic means for displaying the parsed results of a template. Since this servlet extends NDAServlet, it is capable of processing form submissions for HTTP methods GET and POST. While submitting name-value pairs to this servlet, you can specify the operation to be performed (thereby indicating which template should be parsed) via the op parameter. The NDAGetPage servlet also accepts parameters to be passed to the Page Generator for processing the form.

Determining the Appropriate Template

The op identifier associates operations and usertypes (Administrators) to corresponding template files. The op configuration information is stored in the Directory Server. The default configuration for the English locale can be found under
cn=ops, cn=opconf, cn=en, cn=domainConfiguration, ou=config, <delgatedadmin_base_suffix>.

Configuration information is organized by user types:

• Top-level administrator

• Organization Administrator

• Top-level Help Desk Administrator

• Organization Help Desk Administrator

• Group Administrator

• Enduser

The corresponding template files for each user type are located at the following location:
<delegatedadmin_root>/nda/nda/default/en/templates

The following parameters determine the template to be parsed and the manner in which it is parsed:

op=<opname>	Specifies the value for the operation that will, along with the user type, be used to uniquely identify the template from which to generate the HTML output.
mode=edit | display	If mode=edit, the attribute values obtained from processing directives in the template will be displayed in a text field as editable. If mode=display, the value of the attribute will be displayed as is. The default, if this name-value pair is not specified, is to simply display the value.

For your convenience, Delegated Administrator ships with a file op.ldif that lists the default operation-to-template mappings. Use this file when you want to quickly determine which template is associated with a specific operation. For example, if you want to change a field name in the Items tab of the Group Administrator page, you can use the op.ldif file to determine which template you must modify.

To Determine Operation-to-Template Mapping

1. In the Administrator page or dialog box you want to modify, right-click and then choose View Frame Info from the browser menu. For example, to add a field under the Email Address field in the Basic Account Information page, place the cursor under the lable Email Address and right-click.
   
   

2. In the Page Info window, locate the op identifier. In the following example, the string op=ShowUserAcctInfo identifies the operation being performed..
   
   

3. Open the file op.ldif using the following path, where en is the English locale:

   <delegated_admin_root>/nda/nda/default/en/op.ldif

4. Search the op.ldif file for the operation you identified in Step 2. Both the operation and its associated template is included in the directory entry. In this example, the operation showUserAcctInfo is associated with the template HomePage.html.

   dn: cn=showUserAcctInfo, cn=serviceadm, cn=ops, cn=opconf, cn=en, cn=domainConfiguration, ou=config, o=Siroe

   objectclass: top

   objectclass: nsValueItem

   cn: showUserAcctInfo

   nsValueType: nsValueCIS

   nsValueCIS: ../templates/enduser/My-acct/HomePage.html

Setting Macro Values

The following parameters, if passed to the servlet, make it set corresponding macro values in the session object. As with macros (See "Macros" on page 294), these values are useful for constructing search parameters for looking up datatypes in the directory:

ispdn=<value of isp dn>	The base DN, corresponding to the macro $ISPDN$.
domaindn=<value of domain dn>	The DN for the organization, corresponding to the macro $DOMAINDN$.
deptdn=<value of department dn>	The DN for the group, corresponding to the macro $DEPTDN$.
admdeptdn=<value of the department of administrators>	Identifies the user whose DN will be used, corresponding to the macro $ADMDEPTDN$. This parameter is useful when you want to set the value of the dn for a particular administrators department/group for subsequent use.
userdn=<value of user dn>	The DN for the user account, corresponding to the macro $USERDN$.
selfdn=<value of self dn>	The Dn for the user who logged in, corresponding to the macro $SELFDN$.

Searching a Datatype

The following parameters help pass in information for performing a search on a particular datatype:

attrname

matchtype

matchstring

They can be used in a single search clause, and in muliple search clauses.

Using a Single Search Clause

The following code is from the template file <delegatedadmin_root>/nda/nda/default/en/templates/isp/DomDomSearchCriteria.html. This section of the file generates the Search form in Figure 13-2:

<form name="searchForm" method="post" action="/servlet/getPage" target="Right">

<input type=hidden name="op" value="showDomDSResults">

<input type=hidden name="attrname1" value="o">

<input type=hidden name="searchdatatype" value="subdomains">

<input type=hidden name="listrange" value="0-0">

<table width="100%" border="0" cellspacing="5" cellpadding="0">

<tr>

<td>

<table border="0" cellspacing="5" cellpadding="0">

<tr>

<td colspan="4"><font face="PrimaSans BT, Verdana, sans-serif" size="-1"><b>Search for

<select name="searchType" onChange='handleTypeChange()'>

<option selected>Organizations</option>

<option>Groups</option>

<option>Users</option>

<option>Mail Lists</option>

</select>

</b></font></td>

<tr>

<td colspan="4">&nbsp;</td>

</tr>

<tr>

<td align="left"><font face="PrimaSans BT, Verdana, sans-serif" size="-1">Name</font></td>

<td align="left"><font face="PrimaSans BT, Verdana, sans-serif" size="-1">

<select name="matchtype1">

<option selected>contains</option>

<option>begins with</option>

<option>ends with</option>

<option>is</option>

    <option>doesn't contain</option>

<option>is not</option>

<option>sounds like</option>

</select>

</font></td>

<td align="left"><font face="PrimaSans BT, Verdana, sans-serif" size="-1">

<input type="text" name="matchstring1" size="16" maxlength="32">

</font></td>

</tr>

<tr>

<td colspan="4"><font face="PrimaSans BT, Verdana, sans-serif" size="-1">

<input type="checkbox" name="nestedSearch" onClick='handleNestedSearch(this)'>

Include Nested Organizations</font></td>

</tr>

<tr>

<td colspan="4"><font face="PrimaSans BT, Verdana, sans-serif" size="-1">Number of Items to Find:

<input type="text" name="searchsizelimit" size="3" maxlength="3" value=

<!-- S_ENTRYBEGIN "datatype=defaultlistsizetype" -->

<!-- S_ATTRIBUTE "attr=nsvaluecis" "type=text" "option=quoted" -->

<!-- S_ENTRYEND -->

>

(Maximum

<!-- S_ENTRYBEGIN "datatype=maxlistsizetype" -->

<!-- S_ATTRIBUTE "attr=nsvaluecis" "type=text" "option=readonly" -->

<!-- S_ENTRYEND -->

)</font></td>

</tr>

<tr>

<td colspan="4">&nbsp;</td>

</tr>

<tr>

<td colspan="4"><font face="PrimaSans BT, Verdana, sans-serif" size="-1">

<input type="button" name="actionButton" width="90" value="Search" onClick='handleSubmit()'>

</font></td>

</tr>

</table>

</td>

</tr>

</table>

</form>

</body>

</html>

Arguments. The action field for the form is specified as action="/servlet/getPage'

searchdatatype=<the datatype you are searching on>	This parameter corresponds to one of the types listed in the mainconf area of the Directory Server against the identifier datatype. It helps retrieve the search parameters like base suffix and filter for the specified datatype.
attrname=<attribute name from directory>	Specifies the attribute name that will be used to construct the filter for the search. It is the top-level administrator's responsibility to ensure that the attribute specified here exists in one of the objectclasses that the returned entries belong to.
matchtype=<a match type>	Indicates the type of match to be made. In the above example it was 'contains'. Any of the match types from the list of matchtypes specified in mainconf area of the Directory Server against the identifier matchtype can be substituted here. The string must match precisely that specified in mainconf.
matchstring=<search string entered by the user>	This is the value entered by the user in the form to specify the substring to search for. In the previous example in this section, you would enter net in this text field.

Although the servlet name is NDAGetPage, the name getPage is resolved by the servlet engine to NDAGetPage through the servlets.properties and rule.properties files in the Web Server.These are located in the following directory:

<webserver_root>/config

In these files, the class name corresponding to the alias is specified. The file may also contain other such aliases

Figure 13-2    Single search clause

Once the user submits the information in the Search form, the following information is passed to the back end:

attrname: o

matchtype: contains

matchstring: Airius.

Using a Multiple Search Clause

The following is a section of the template file <delegatedadmin_root>/nda/nda/default/en/templates/my-depts/DeptUserSearchSearchCriteria.html. The file generates the form in Figure 13-3:

<form name="searchForm" method="post" action="/servlet/getPage" target="Right">

<input type=hidden name="op" value="showDeptUSResults">

<input type=hidden name="attrname1" value="uid">

<input type=hidden name="attrname2" value="givenname">

<input type=hidden name="attrname3" value="sn">

<input type=hidden name="searchdatatype" value="deptusers">

<table width="100%" border="0" cellspacing="5" cellpadding="0">

<tr>

<td>

<table border="0" cellspacing="5" cellpadding="0">

<tr>

<td colspan="4"><font face="PrimaSans BT, Verdana, sans-serif" size="-1"><b>Search for

<select name="searchType" onChange='handleTypeChange()'>

<option>Groups</option>

<option selected>Users</option>

</select>

</b></font></td>

<tr>

<td colspan="4">&nbsp;</td>

</tr>

<tr>

<td align="left"><font face="PrimaSans BT, Verdana, sans-serif" size="-1">User ID</font></td>

<td align="left"><font face="PrimaSans BT, Verdana, sans-serif" size="-1">

<select name="matchtype1">

<option selected>contains</option>

<option>begins with</option>

<option>ends with</option>

<option>is</option>

    <option>doesn't contain</option>

<option>is not</option>

<option>sounds like</option>

</select>

</font></td>

<td align="left"><font face="PrimaSans BT, Verdana, sans-serif" size="-1">

<input type="text" name="matchstring1" size="16" maxlength="32">

</font></td>

</tr>

<tr>

<td align="left"><font face="PrimaSans BT, Verdana, sans-serif" size="-1">First Name</font></td>

<td align="left"><font face="PrimaSans BT, Verdana, sans-serif" size="-1">

<select name="matchtype2">

<option selected>contains</option>

<option>begins with</option>

<option>ends with</option>

<option>is</option>

    <option>doesn't contain</option>

<option>is not</option>

<option>sounds like</option>

</select>

</font></td>

<td align="left"><font face="PrimaSans BT, Verdana, sans-serif" size="-1">

<input type="text" name="matchstring2" size="16" maxlength="32">

</font></td>

</tr>

<tr>

<td align="left"><font face="PrimaSans BT, Verdana, sans-serif" size="-1">Last Name</font></td>

<td align="left"><font face="PrimaSans BT, Verdana, sans-serif" size="-1">

<select name="matchtype3">

<option selected>contains</option>

<option>begins with</option>

<option>ends with</option>

<option>is</option>

    <option>doesn't contain</option>

<option>is not</option>

<option>sounds like</option>

</select>

</font></td>

<td align="left"><font face="PrimaSans BT, Verdana, sans-serif" size="-1">

<input type="text" name="matchstring3" size="16" maxlength="32">

</font></td>

</tr>

<tr>

<td colspan="4"><font face="PrimaSans BT, Verdana, sans-serif" size="-1">Number of Items to Find:

<input type="text" name="searchsizelimit" size="3" maxlength="3" value=

<!-- S_ENTRYBEGIN "datatype=defaultlistsizetype" -->

<!-- S_ATTRIBUTE "attr=nsvaluecis" "type=text" "option=quoted" -->

<!-- S_ENTRYEND -->

>

(Maximum

<!-- S_ENTRYBEGIN "datatype=maxlistsizetype" -->

<!-- S_ATTRIBUTE "attr=nsvaluecis" "type=text" "option=readonly" -->

<!-- S_ENTRYEND -->

)</font></td>

</tr>

<tr>

<td colspan="4">&nbsp;</td>

</tr>

<tr>

<td colspan="4"><font face="PrimaSans BT, Verdana, sans-serif" size="-1">

<input type="button" name="actionButton" width="90" value="Search" onClick='handleSubmit()'>

</font></td>

</tr>

</table>

</td>

</tr>

</table>

</form>

Figure 13-3    Multiple search clauses

Three sets of attrname, matchtype and matchstring are submitted. The following information is passed on to the back end as a result of the user's search:

attrname1: uid

matchtype1: begins with

matchstring1: A

attrname2: givenname

matchtype2: begins with

matchstring2: A

attrname3: sn

matchtype3: begins with

matchstring3: Bar

Customizing the Display of Search Results

---

You can customize the way in which search results are displayed. You can change the number of results displayed at a time, as well as specify the attribute upon which to sort the results.

Sorting on Multiple Attributes

The directive S_SEARCH_PARAMS is used to specify the attributes to sort on. You can specify multiple attributes to sort on by separating them with a colon. For example:

<!-- S_SEARCH_PARAMS "step=5" "sortattr=o:cn" -->

Results are listed in pages with five entries each, and sorted first on o and then on cn. You need to specify this directive before the S_ENTRYBEGIN....S_ENTRYEND block for this datatype in the template.

Customizing HTML Templates

---

The following are examples of the types of changes you can make to Delegated Administrator's HTML Templates.

To Change the Banner or Logo on the Login Page

In the file <ndaroot>/nda/nda/login.htm , replace the links to TopBannerLogo_trans.gif and iDAbanner_blueback.gif with a link to a file containing your logo/banner.

In the following example, the graphic iplanet.gif was replaced with sunnet.gif.

<tr><td><a href="http://www.iplanet.com/" target="_top"><img src="/nda/default/en/images/sunnet.gif" width="62" height="26" border="0"><img src="/nda/default/en/images/iDAbanner_blueback.gif" width="82" height="26" border="0"></a></td></tr>

Figure 13-4    The iPlanet logo is replaced with the Sun-Netscape Alliance logo.

Adding a Field to an HTML Template

While the default Delegated Administrator templates may work well for many companies, you may want to add fields to your templates to expose additional types of information already stored in your user directory. For example, many companies assign an Employee Number when an individual is hired. For such companies, it's useful to include this number along with the user's name and userID in the Basic Information template. You can add a field to the New User and Edit User pages for entering this Employee Number.

Figure 13-5    The Employee Number field is added to the Basic Information window.

To add a field to the New User and Edit User pages, use the attribute employeeNumber from inetOrgPerson. In this example, a field for Employee Number is added to the Basic Information window for a user account. The following files are modified:

• <delegatedadmin_root>/nda/nda/default/en/templates/dialogs/CreateUserNavBar.html

• <delegatedadmin_root>/nda/nda/default/en/templates/dialogs/CreateUserBasic.html

• <delegatedadmin_root>/nda/nda/default/en/templates/dialogs/EditUserNavBar.html

• <delegatedadmin_root>/nda/nda/default/en/templates/dialogs/EditUserBasic.html

When a new user entry is created, the administrator enters the user's Employee Number. Delegated Administrator saves the user entry with this information.

To Add a Field for an Existing Attribute

1. In the file CreateUserNavBar.html, find the line containing telephonenumber.

2. Add a line just before this line and use employeenumber as the attribute name.

   <!-- CreateUserBasic --> var createUserBasic = new Object(); createUserBasic["uid"]=""; createUserBasic["givenname"]=""; createUserBasic["middleinitials"]=""; createUserBasic["sn"]=""; createUserBasic["cn"]=""; createUserBasic["userpassword"]=""; createUserBasic["confirm_userpassword"]=""; createUserBasic["mail"]=""; createUserBasic["employeenumber"]=""; createUserBasic["telephonenumber"]=""; createUserBasic["facsimiletelephonenumber"]=""; createUserBasic["mobile"]=""; createUserBasic["pager"]=""; createUserBasic["o"]=""; createUserBasic["title"]=""; createUserBasic["manager"]=""; createUserBasic["postaladdress"]=""; createUserBasic["labeleduri"]=""; createUserBasic["description"]=""; createUserBasic["preferredlanguage"]="";

3. In the file CreateUserBasic.html, find the HTML code that outputs the telephonenumber. This is a table row and is delimited by the <tr>and </tr> HTML tags.

4. Insert a new table row, copying the one for telephonenumber, and replacing all occurrences of telephonenumber with employeenumber.

5. Insert a new table row, similar to the one for the telephonenumber, replacing all occurrences of telephonenumber with employeenumber"

   <tr> <td><b><font face="PrimaSans BT, Verdana, sans-serif" size="-1">Employee number</font></b></td> <td> <input type="text" name="add_employeenumber" size="20" onChange="handleValueChange('employeenumber');" value=""> </td> </tr> <tr> <td><b><font face="PrimaSans BT, Verdana, sans-serif" size="-1">Telephone number</font></b></td> <td> <input type="text" name="add_telephonenumber" size="20" onChange="handleValueChange('telephonenumber');" value=""> </td> </tr> <tr

6. In the file EditUserNavBar.html, locate two lines that contain the attribute telephonenumber. Insert two similar lines for the attribute employeenumber.

   The <!-- S_ATTRIBUTE --> directive is processed by the Page Generator, and will result in the substitution of the attribute value from the user entry

   <!-- S_ATTRIBUTE "attr=o" "type=text" "option=readonly,quoted" -->

   editUserBasicOrig["employeenumber"]=

   <!-- S_ATTRIBUTE "attr=employeenumber" "type=text" "option=readonly,quoted" -->

   editUserBasicOrig["title"]=

   editUserBasicOrig["telephonenumber"]=

   <!-- S_ATTRIBUTE "attr=telephonenumber" "type=text" "option=readonly,quoted" -->

   editUserBasicOrig["title"]=

7. In the file EditUserBasic.html, insert a row for employeenumber.

Adding a JPEG Image to a Template

Companies sometimes include a digital image of each employee with the individual's basic account information. The image might captured for the employee's badge, and simply stored in the directory. Or it might be made available through a company phonebook for identification purposes.

Before you can add a JPEG image to a template, you must enable JPEG support in Diretory Server, and add the image to the user's entry.

To Enable JPEG Image Support in the Directory Server

1. In the Directory Server Console, click Directory, then click the Delegated Administrator base suffix.

2. Click Domain, and then click Users.

3. Select a user, and then right click on the user's name.

4. Open the properties Editor. Editor Entry dialog is displayed

5. In the Editor Entry dialog, click Advanced. Property Editor dialog is displayed

6. In the Property Editor dialog box, from the Edit menu, choose Add Attribute.

7. From Add Attribute Window select JPEG photo. Make sure Property JPEG image is added.

8. Click Replace in Property jpeg image. Choose the JPEG file you want to add.

9. Click OK and save it.

Changing an Error Message

In this example, the standard "Invalid Credentials" error message—usually displayed when a user enters the wrong password in the Login page—is changed to "Invalid Password."

1. In the file <delegatedadmin_root>/nda/classes/netscape/nda/servlet/resource.properties, find the resource strings that begin with Page-invalidCredentialsMsg.

2. Change the error message by making the appropriate changes to the HTML code that is output.

3. Be sure to set the MsgLength to the correct value. The Page Generator will use this length to read the lines of HTML code to output.

   Page-invalidCredentialsMsgContentType=text/html Page-invalidCredentialsMsgLength=6 Page-invalidCredentialsMsg0=<html><head><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> Page-invalidCredentialsMsg1=<title>Invalid Password</title></head> Page-invalidCredentialsMsg2=<body bgcolor="#FFFFFF" link="#666699" vlink="#666699" alink="#333399"> Page-invalidCredentialsMsg3=<h1>Invalid Password</h1> Page-invalidCredentialsMsg4=<br>Click <a href="javascript:window.history.back()">here</a> to go back to the login page. Page-invalidCredentialsMsg5=</body></html>

Figure 13-6    "Invalid Credentials" messages is changed to "Invalid Password."

Changing Search Criteria

You can modify the search criteria used when searching users in the directory. In this example, the Employee Number is substituted for Organization in the types of search criteria displayed in the Top-level Administrator page.

1. In the file <delegatedadmin_root>/nda/nda/default/en/templates/isp/DomUserSearchCriteria.html, find the form element named attrname4.

2. Change the value of this form element from nsdadomain to employeenumber.

3. Find the section of the HTML code that outputs the table row for the Last Name. The next row outputs the criteria for Organization. Change this to output Employee Number.

Figure 13-7    In the Search interface, the Employee Number field takes the place of the Organization field.