6.2 The Advanced Selection Widget

The Advanced Selection (AS) widget lets a user specify a set of advanced selection criteria for a specified object type (class.) The result (output) is a string representing the XML description of the criteria the user has entered. This criteria can be used by a namespace's getChildren process call to specify which objects in the directory to return to the developer's task.

The input to the Advanced Selection widget is a string representing with the name of a directory type (class). Optionally, a string representing a previous XML selection criteria can be supplied and the widget will be initialized accordingly. (Useful when editing selection criteria).

The widget displays attributes for the specified directory type (class). When the user selects an attribute, operators appropriate for the selected attribute are presented in a pull-down list. Further, a list of possible criteria values might be displayed. The user selects an attribute, chooses a comparison operation and supplies their desired criterion (or possibly selects the criterion from a list of allowed values). These criteria can be grouped together into a logic group and multiple logic groups can be defined.

You can supply a Java method to populate the widget's attribute list, operators/attribute, and possible values/attribute. If you don't supply a method, iManager assumes that eDirectory is being accessed and it uses a default method (NDSTypeInfoCallback.java) to retrieve this information.

This design implies that this widget is completely namespace independent. It can be used with eDirectory, any LDAP namespace, or any future namespace.

This section includes the following topics:

6.2.1 How to Call the AS Widget

The Advanced Selection widget is statically implemented using include files and several parameter variables. Static implementation means that the parameters cannot be changed at runtime because they are merged into the HTML. However, there is still significant flexibility since you can statically specify callback routines that execute at runtime to retrieve required input parameters and process the XML output.

6.2.2 Include Files

The following table describes the include files used to implement the AS widget:

Table 6-4 AS widget include files




Contains the JavaScript used for implementing the AS widget. With a browser, these scripts are stored in cached .js script files to minimize data transfer over the wire.


Inserts an image that can be clicked to display the AS widget.


Inserts an HTML button that can be clicked to display the AS widget.


Inserts an HTML hypertext link that can be clicked to display the AS widget.

To use these files, include them in your task JSPs using the jsp:include action.

6.2.3 Parameter Variables

Use either AS.jsp, ASBtn.jsp, or ASLink.jsp to insert a control that displays the Advanced Selection feature when clicked. Each of these controls use the following parameters to determine how the feature operates:

Table 6-5 Advanced Selection control parameters




(Required) The name of the directory type (class) that advanced selection criteria will be entered for. Specify either AS.Types or AS.TypesCallBack.


(Required) The name of a JavaScript routine that returns the name of the directory type (class) that advanced selection will be entered for. This routines has no parameters. Specify either AS.Types or AS.TypesCallBack.


(Required) The name of the HTML component where the selection criteria is returned. Specify either AS.Control or AS.ControlCallBack.


(Required) The name of a JavaScript routine that processes the returned XML criteria. The callback routine must have the following parameter list format: <callbackName>(<controlName>,<typeName>,<XMLCriteria>). The <controlName> can be used to know where to direct the process XML criteria. The typeName identifies which directory type (class) the criteria is for. The XML Criteria is a string representing the advanced selection criteria. Specify either AS.Control or AS.ControlCallBack.


An XML criteria string representing an set of initial selection criteria that is used to start the widget in a desired state. This is useful if you want to edit an existing criteria or help the user by pre-entering known selection information. Specify either AS.InitialCriteria or AS.InitialCriteriaCallBack.


The name of a JavaScript routine that locates and returns an XML criteria string representing an set of initial selection criteria that is used to start the widget in a desired state. This routine must have the following parameter list format: <callbackName>(<typeName>). The <typeName> is used to identify which XML criteria is requested.


A string representing the name of a Java implementation of the AdvSelTypeInfoCallBack abstract class that can used to retrieve the attribute/comparison operations/allowed values information in the form of a AdvSelTypeInfo class. If this parameter is undefined or the empty string, it is assumed that the eDirectory is being used and that all attributes of type string, integer or boolean are to be displayed to the user in the widget. The NDSTypeInfoCallBack.getInfo() method is called to retrieve this default information.


The name of a JavaScript routine that returns a Boolean true if the advanced selection widget is to proceed, or false if its execution is to be prevented (disabled). This routine is called before the advanced selection widget is displayed and can be used to prevent its launch until desired conditions (which are checked in the routine) have been met.


The name of an icon to use for the Advanced Selection widget button instead of the standard one. Used with AS.inc.


The hint or accessibility text to be displayed when the user moves the mouse over the advanced selection icon/link/button. If the text is not defined, “Advanced Selection” is displayed. Used with AS.inc, ASBtn.inc and ASLink.inc.


The text to be displayed on the HTML button or HTML link, which is used to bring up the Advanced Selection widget. Used with ASBtn.inc and ASLink.inc.

6.2.4 A JSP Example: Delete Users

 <%@  page pageEncoding="utf-8" contentType="text/html;charset=utf-8" %>
 <%      <%@ taglib uri="/WEB-INF/iman.tld" prefix="iman" %>
 <HEAD><TITLE>Delete Users</TITLE>
   var deleteCriteria=null;
   function saveXML(controlName, type, xmlCriteria)
     deleteCriteria[type] = xmlCriteria;
     document.DeleteUserForm.DeleteUsersCriteria.value = xmlCriteria;
   function getXML(type)
     var xml = deleteCriteria[type];
     if (xml!=null)   return xml;
     else return "";
   function readToSearch()
     if (something) return true;
     else return false;
 <BODY TEXT="#000000" bgcolor="#FFFFFF">
 <FORM name="DeleteUserForm" method=post action="webacc">
   <input type=hidden name="taskId" value="{VAR taskId}">
   <input type=hidden name="merge" value="dev,GenConf">
   <input type=hidden name="error" value="dev.GenErr">
   <input type=hidden name="User.context" value="{VAR User.context}">
   <input type=hidden name="nextState" value="doDeleteUsers">
   <BR><FONT size=+1 color=#000080><B>Delete Users</B></FONT><BR><BR>
   <NOBR>Users to be deleted:</NOBR><BR>
   <input type=text name="DeleteUsersCriteria" value="" size=35>
 <iman:as control="DeleteUsersCriteria"
          altText="Describe users to be deleted"
   <input type=image name="Delete" alt="Delete" src="<path>/delete.gif" border=0

The preceding example assumes:

  • saveXML is a JavaScript routine that processes the XML criteria.

  • getXML is a JavaScript routine that retrieves initial XML criteria.

  • ZenDeleteUsersTypeInfo is a Java class that implements the AdvSelTypeInfoCallback abstract class and returns an AdvSelTypeInfo object containing the attribute/comparison operations/selection values to be displayed.

6.2.5 Setting the Options at Runtime Using JavaScript

You can call the doDynamicAS function from JavaScript to set the Advanced Selection widget parameters at runtime. However, we recommend that you use the static include files when possible to standardize the user experience. The following example shows how to use the doDynamicAS function:

 function doDynamicAS(userContext, AS)
    //make sure we have an entry for the required parameters
    if ( (AS.types!=null || AS.typesCallBack) &&   //do we have a valid type or type callback
         (AS.control!=null || AS.controlCallBack)) /  /do we have a control or control callback
       //make sure we at least have default values for all parameters
       if (AS.types==null)                    AS.types="";
       if (AS.typesCallBack==null)            AS.typesCallBack="";
       if (AS.control==null)                  AS.control="";
       if (AS.controlCallBack==null)          AS.controlCallBack="";
       if (AS.initialCriteria==null)          AS.initialCriteria="";
       if (AS.initialCriteriaCallBack==null)  AS.initialCriteriaCallBack="";
       if (AS.isASAllowed==null)              AS.isASAllowed="";
       if (AS.typeInfoCallBack==null)         AS.typeInfoCallBack="";
       if (AS.validateSyntax==null)           AS.validateSyntax="";
       //is window being sized dynamically?
       if (AS.windowWidth!=null)     window.asWidth=AS.windowWidth;
       if (AS.windowHeight!=null)    window.asHeight=AS.windowHeight;
       //are the widths of the input well being sized dynamically?
       if (AS.attributeWidth!=null)  window.asAPercent=AS.attributeWidth;
       if (AS.operationWidth!=null)  window.asOPercent=AS.operationWidth;
       if (AS.valueWidth!=null)      window.asVPercent=AS.valueWidth;
       //call the private doAS routine

NOTE:AS.validateSyntax is reserved for future use.

As you can see from this code, the following parameters can be changed dynamically at runtime using this function. You must create a JavaScript object with these values. Note that the first character following the “AS.” is lowercase to distinguish it from the corresponding static {SET} variables.

  • AS.types

  • AS.typesCallBack

  • AS.control

  • AS.controlCallBack

  • AS.initialCriteria

  • AS.initialCriteriaCallBack

  • AS.isASAllowed

  • AS.typeInfoCallBack

You can change the window size dynamically by setting the following variables:

  • AS.windowWidth

  • AS.windowHeight

You can change the relative size percentages of the three primary entry wells as follows:

  • AS.attributeWidth

  • AS.operationWidth

  • AS.valueWidth

Implementing the user interface to bring up the widget is up to the task developer. We recommend that you preserve the look and feel provided with the static include files to standardize the user's GUI experience.

6.2.6 Implementing AdvSelTypeInfoCallback

The Advanced Selection widget is independent of namespace (eDirectory, ActiveDirectory, iPlanet, LDAP, etc). It simply displays a list of strings representing attributes for a given type, a list of strings representing comparison operators, and possibly a list of strings representing allowed values for a particular attribute. It understands no syntax or semantics pertaining to these values.

Because the Advanced Selection widget knows nothing about any directory (their types, operations, values, etc), this information must come from somewhere. You provide the information through the AdvSelTypeInfoCallback Java class. If you are either not using eDirectory or do not want all the eDirectory attributes for a particular type displayed, you must create a new class that extends the AdvSelTypeInfoCallback abstract class and implement its getInfo() method. When called, this method must return an AdvSelTypeInfo object containing this information. The AdvSelTypeInfo class has the following two constructors. The first takes an array of strings representing the comparison operations that are assumed if none are specified for a particular type (class). The second is used if comparison operations are specifically defined for each type:

  • public AdvSelTypeInfo(String[] defaultOps)

  • public AdvSelTypeInfo()

After you have created an AdvSelTypeInfo object, you must call one of the following two addAtrribute() methods for each type that you want to appear in the widget's [attribute] list. The first is used to create an attribute with allowed values; the second is used if you want the user to be able to type anything into the [value] entry well. If the ops parameter is null, the default operations are assumed, if defined:

  • public void addAttribute(String name, String[] ops, String[] values)

  • public void addAttribute(String name, String[] ops)

After writing the AdvSelTypeInfoCallback class, compile it and placed it in a JAR that appears on the Java classpath. Then by setting the AS.TypeInfoCallBack {SET} parameter (or the AS.typeInfoCallBack dynamic parameter), it will be used to supply the necessary information at runtime.

HINT:See the default eDirectory (NDS®) implementation in NDSTypeInfoCallBack.java for an example of how to write an AdvSetTypeInfoCallback class. This class is assumed if no callback class is specified or if the specified class cannot be found.

6.2.7 The Resulting XML Selection Criteria

The Advanced Selection widget returns the selection criteria that the user enters in the following XML format:

   <types> ds-type </types>
       <attribute> name </attribute>
       <operation> op </operation>
       <value> string </value>
       <row-op> and/or </row-op>
     . . .
     <group-op> and/or </group-op>
   . . .

The string contains no whitespace (spaces, tabs, newlines, etc.) unless they are part of the attribute names, comparison operations, or match criterion that the user enters.