6.1 The Object Selector Widget

The Object Selector widget lets a user search or browse for an object in eDirectory, select the object, and return the name of the object to the form field of the task user interface. It supports single or multiple selections. Selected objects are returned as DN strings which are, by default, placed in the control specified using the OS.Control variable. However, the task developer can have the result strings returned to a JavaScript callback specified with the OS.CallBack variable, where they can be manipulated as desired.

Implement the Object Selector widget using include files and several parameter variables.

The following figure shows the iManager Object Selector in simple browse mode.

Figure 6-1 iManager Object Selector in simple browse mode.

This section describes the following topics:

6.1.1 Include Files

The following table describes the include files used to implement the Object Selector:

Table 6-1 Object selector include files




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


Contains hidden variables used for implementing the selector functionality. Must be included after the last </form> tag on the JSP page.


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


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


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

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

6.1.2 Parameter Variables

Use either OS_inc.jsp, OSBtn_inc.jsp, or OSLink_inc.jsp to insert a control that opens the Object Selector when clicked. Each of these controls use the following parameters to determine how the Object Selector operates:

Table 6-2 Object selector parameter variables




(Required) The name of the field where the selected objects are returned.


(Required) The name of a JavaScript routine where the returned values and control name are returned for processing. The callback routine must have the following parameter list format: <callbackName>(<controlName>,<resultsArray>). The names of the selected objects are returned in resultsArray.


Whether the Object Selector appears with the advanced search visible. False displays simple type-only filters. The default is false.


A string representing a comma-separated list of XML representations of advanced selection filter criteria for ds-classes. (See Section 6.1.3, Advanced Selection XML Syntax for the required syntax of the XML criteria). If this parameter is present, the OS.AdvancedSelection parameter is assumed to be true.


The name of a JavaScript routine that returns a string representing a comma-separated list of XML representations of advanced selection filter criteria for ds-classes. (See Section 6.1.3, Advanced Selection XML Syntax for the required syntax of the XML criteria). This routine must have the following parameter list format: <callbackName>(<controlName>). If this parameter is present, the OS.AdvancedSelection parameter is assumed to be true.


The hint or accessibility text displayed when the user moves the mouse over the Object Selector icon. If not supplied, “Object Selector” is displayed. Used with OS.inc.


The name of an icon to use for the selector button instead of the standard icon. Used with OS.inc.


The name of a container where the search or browse begins The default is the container from the last search, or [root].


The name of a JavaScript routine that returns a Boolean true if the object selector is to proceed or false if the object selector operation is to be prevented. This routine is called before the object selector widget is displayed and can be used to prevent its launch unless conditions (which are checked in the routine) are met. For more information, see Dynamically Enabling and Disabling the Object Selector.


The Object Selector mode. Set to Search to allow the user to search and find objects in the tree with a search query. Set to Browse to allow the user to walk the tree and manually select objects. The default is Browse.


Whether the user can select more than one object. The default is false (single select).


A string representing a search filter to be used to limit the number of items returned to those objects whose name matches the filter requirements. The * wildcard can be used in the name filter. The default is *.


The number of results to show per page. The default depends on the selection mode and device.


Whether to allow the search operation to search for objects starting in the specified container and all of its subcontainers. False limits the search to the specified container only. The default is true.


Whether to force an initial search operation to begin as soon as the Object Selector appears, if it appears in search mode. OS.Mode=”search” must also be set. This automatic search behavior occurs only when the object selector starts up, never while switching between the search and browse tabs. False prevents an automatic search, requiring the user to click the Search button to start the search. The default is false.


Whether the search returns objects of types derived from types that match the type filter in addition to objects that match the base types. False causes the search to not return objects derived from matching types. The default is true.


The text displayed on the HTML button or HTML link used to bring up the object selector. Used with OSBtn.inc and OSLink.inc.


A comma-separated list of object types to be returned. Specifying * returns all object types.


The name of a JavaScript routine that returns a string containing a comma-separated list of object types to be returned. Specifying * returns all object types. The callback routine must have the following parameter list format: <callbackName>(<controlName>)


Whether the simple Object Selector appears in a separate window. If false, the Object Selector appears in the same window as the task, which requires that the task state be saved before the Object Selector runs and be restored afterwards. This is problematic for complex tasks. Setting this to true might solve these problems. The default is false.

6.1.3 Advanced Selection XML Syntax

The XML syntax definition of an Advanced Selection criterion is:

         <id> ds-type1 </id>
         <id> ds-type2 </id>
         <id> ds-auxtype1 </id>
         <id> ds-auxtype2 </id>
          <attribute> name </attribute>
          <operation> op </operation>
          <value> string </value>
          <row-op> and/or </row-op>
       <group-op> and/or </group-op>

6.1.4 Dynamically Enabling and Disabling the Object Selector

The user activates the Object Selector by clicking on an icon, link, or button, depending on whether you have used the OS.inc, OSLink.inc or OSBtn.inc files in your task. However, at times you might want to disable the Object Selector until certain steps have been performed in the task. This is accomplished using the IsOSAllowed() function (see OS.IsOSAllowed). You provide a JavaScript function that determines, at runtime, when the Object Selector is allowed to run. Each time the user clicks the Object Selector button, this function is called. You provide the logic to determine whether the Object Selector operation is allowed at that time. If so, you return Boolean true, otherwise false.

6.1.5 Pre-Processing and Post-Processing Routines (preOS and postOS)

It is often desirable for a task to perform some processing before the Object Selector executes or after it returns the selected objects to the task. You can do this by implementing JavaScript routines, preOS(controlName) and postOS(controlName) for your tasks.

If the Object Selector is enabled (see OS.IsOSAllowed), an attempt is made to call a JavaScript routine called preOS(controlName), if it exists. This enables you to do any processing you need before the Object Selector runs.

When the Object Selector finishes, the selected results are returned to either the specified control or callback routine and then the postOS(controlName) function is called, if it exists. At this point, you can do anything you want to clean up after the Object Selector in your task.

contolName is a string representing the HTML control that is associated with the Object Selector using the OS.Control parameter.

6.1.6 Making the Root Selectable

It is often necessary to allow the user to select the root of the tree as a place to perform operations (like create, delete, move, and modify). However, the root of the tree is not an object in DS, so you cannot search or browse to it directly. If you want your users to be able to select the root of the tree as a location to perform operations, simply specify [root] as the value of the OS.TypeFilter parameter.

6.1.7 Making Public and This Selectable

eDirectory has two other pseudo-objects that can be made selectable: This and Public. To make these selectable, specify [this] or [public] as the value of the OS.TypeFilter parameter.

6.1.8 Filtering on All Container Types

Sometimes you need to allow the user to select any container-type object in the directory, but it is not always possible to know what all the container types in the directory are at the time you create the task. The system administrator can extend the directory schema and create new container objects.

To enable users to select any container object in the directory, specify [containers] as the value of the OS.TypeFilter parameter. The Object Selector queries the directory to get a list of all containers in the tree and dynamically populates the type filter with the available container types.

6.1.9 Filtering on Containers that Are Partitions

eDirectory represents partitions as an attribute of a container class and does not currently provide the ability to find only containers that are partitions. However, to enable users to select only partition container objects in the directory, specify [partitions] as the value of the OS.TypeFilter parameter. All container objects are displayed, but only those that are partitions are selectable. If you want all containers that are not partitions, specify [non-partitions].

6.1.10 Object Selector Support in the iManager Tag Library

iManager 2.7 provides a custom tag library to developers who prefer using tag libraries in their JSP templates. Use these tags along with, or in place of, the auto-conversion tools the Conduit object creates during the port from .http files to .jsp files.

IMPORTANT:An iManager Tag Library reference is available in iManager. To view it, open the iManager Developer view, then select Developer Reference > iMan Tag Library Reference.

The following tags support the Object Selector:

  • <iman:eMFrameScripts/>

  • <iman:osScripts/>

  • <iman:os attrib1 . . . attribn/>

  • <iman:osFooter/>

The <iman:eMFrameScripts/> and <iman:osScripts/> tags define general data and routines used by most iManager tasks and those required specifically for the Object Selector. They must be included in the <head> section of the HTML task document.

The <iman:os attrib1 . . . attribn/> tag displays an Object Selector button in the task. You can provide values for all of the defined Object Selector values through the attributes listed in the following table:

Table 6-3 Object selector attributes

Property Object Name

JSP Tag Attribute Name











































The <iman:osFooter/> tag creates the form through which all data is posted between the Object Selector and the task that is using it. It must be placed at the bottom of the HTML before the </body> tag.

6.1.11 A JSP Tag Library Example: Delete User

 <%@  page pageEncoding="utf 8" contentType="text/html;charset=utf 8" %>
 <%@ taglib uri="/WEB INF/iman.tld" prefix="iman" %>
   function capitalize(controlName, results)
     var strResults = "";
     for (i=0; i<results.length(); i++)
       if (i>0) { strResults += "+" }
       strResults += results[i].toUpperCase();
   function readyToSearch()  { return true }
 <BODY TEXT="#000000" bgcolor="#FFFFFF" onLoad="returnFromOS()">
 <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="nextState" value="doDeleteUser">
    <BR><FONT size=+1 color=#000080><B>Delete User</B></FONT><BR><BR>
    <FONT face="Helvetica,Arial" size= 1><NOBR>User name:</NOBR></FONT><BR>
    <input type=text name="DeleteUserName" value="" size=35>
    <iman:os control="DeleteUserName"
              altText="User to delete"
              isOSAllowed="readyToSearch" />
    <br><br><input type=image name="Delete" alt="Delete" src="<path>/delete.gif" border=0

6.1.12 Troubleshooting

  • I select an object, but it is not returned to the edit box. What is wrong?

    • Make sure you have included the OSFooter_inc.jsp as the last line of the template before the </body> tag. You can put it anywhere in the template where a form can be defined, but it is easy to simply put it before the </body> tag. Never put it inside of <form></form> tags.

    • Make sure you entered the name of the OS.Control correctly. The value of this attribute must match the corresponding HTML control name exactly. This check is case sensitive.

    • If you are using a callback routine, debug to see if the callback is being called and if the two required parameters, controlName and resultArray, are being returned correctly.

  • I get a developer alert when running my task. Why?

    You are probably using the obsolete OSHeader_inc.jsp file in your template. Remove it and use the OSFooter_inc.jsp file as the last line in your template before the </body> tag.

  • My password and file <input> fields are not being saved in single-window mode. Why?

    These fields are intentionally not saved for security reasons.

  • Returning a selected object on Simple pages causes unexpected errors or processing. Why?

    The Simple implementation of the Object Selector assumes it can restore the state of your task by reissuing the URL that brought up the page in the first place. This is almost always a safe assumption. However, if the URL causes some preprocessing to occur that cannot safely be repeated when the Object Selector is returning to your task, there is a problem.

    There is nothing the Object Selector can do to prevent this problem. You must know that this problem can occur and prevent it. When a result is being returned from Object Selector, the following parameter is added to the original URL: OS.ReturningToAnchor="true". Your code must detect this condition and prevent preprocessing that might cause an error to occur.