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:
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.
The following table describes the include files used to implement the AS widget:
Table 6-4 AS widget include files
To use these files, include them in your task JSPs using the jsp:include action.
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
<%@ page pageEncoding="utf-8" contentType="text/html;charset=utf-8" %>
<% <%@ taglib uri="/WEB-INF/iman.tld" prefix="iman" %>
<HEAD><TITLE>Delete Users</TITLE>
<iman:eMFrameScripts/>
<iman:asScripts/>
<script>
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;
}
</script>
</HEAD>
<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"
controlCallBack="saveXML"
types="User"
initialCriteriaCallBack="getXML('User')"
typeInfoCallBack="com.novell.emframe.zen.ZenDeleteUsersTypeInfo"
altText="Describe users to be deleted"
iconName="dev/delete.gif"
isASAllowed="readyToSearch"/>
<BR><BR>
<input type=image name="Delete" alt="Delete" src="<path>/delete.gif" border=0
</FORM>
</BODY>
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.
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
doAS(userContext,
AS.types,
AS.typesCallBack,
AS.control,
AS.controlCallBack,
AS.initialCriteria,
AS.initialCriteriaCallBack,
AS.isASAllowed,
AS.typeInfoCallBack,
AS.validateSyntax);
}
}
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.
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.
The Advanced Selection widget returns the selection criteria that the user enters in the following XML format:
<selection-criteria>
<types> ds-type </types>
<group>
<row>
<attribute> name </attribute>
<operation> op </operation>
<value> string </value>
<row-op> and/or </row-op>
</row>
. . .
<group-op> and/or </group-op>
</group>
. . .
</selection-criteria>
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.