Sun Identity Manager Deployment Reference

Chapter 7 HTML Display Components

This chapter describes the Identity Manager HTML display component library. HTML display components are used when customizing forms. See Chapter 2, Identity Manager Forms for a discussion of the larger topic of customizing forms.

This chapter covers the following topics:

HTML Display Components

If you are designing forms, you will use the HTML components described in this section. To create a form, you can use the Identity Manager Form XML language (also called forms), to describe HTML display components. This language is then interpreted at runtime to build the necessary components. It allows new pages to be dynamically generated with little or no additional Java development, which greatly simplifies customization.

What Are HTML Components?

HTML display components are instances of Java classes that generate a string of HTML text. Each display component has:

Specifying Display Components

You can specify display components as follows:

<Field name=’Name’>
   <Display class=’Class’>
      <Property name=’Name’ value=’Value’/>

Page Processor Requirements for HTML Components

Forms that implement HTML components have the following page processor requirements.

Hidden Parameters

Most components have a name that corresponds to the name of a parameter posted from an HTML form. Identity Manager reserves a few parameter names for general use. Do not use these names as component names.

Table 7–1 Hidden Parameters

Reserved Name 



Contains the ID of the object being edited 


Contains the value of the button used to submit the form 


Contains the name of the last component that was active on the form 


Can contain an informational message to be displayed at the top of the page 


Can contain an error message to be displayed at the top of the page 

Component Classes

HTML components are independent objects that can be combined in various ways. Related components are organized into classes. There are two major groups of component classes:

Basic Component Classes

Common component classes include the components that are used to display and edit a single value. These components are defined in the section titled Basic Component Classes.

Container Classes

A container class defines a collection of components that are visually organized in a certain way. Typically, creating a container class results in the generation of an HTML table tag. Simple containers can concatenate the components horizontally or vertically. Other containers allow more flexible positioning of components and may add ornamentation around the components.

Because containers are themselves components, any container can be placed inside another container. You can use this mechanism to build complex page layouts. For example, many pages consist of a title, followed by a list of editing fields, followed by a row of form submission buttons. You can create this by creating a Panel component using vertical orientation that contains a Label component, an EditForm component, and a ButtonRow component. The EditForm component itself contains some number of subcomponents. The ButtonRow component is simply a Panel that uses horizontal orientation and contains a list of Button components.


Defines five regions (north, south, east, west, and center) into which items can be placed. Components in the north and south regions are positioned horizontally. Components in all other regions are positioned vertically.

Properties include:


Sets default options for button placement. Extends the Panel component.


This display component is the default display class used to render forms in a browser.

Form components are positioned in two columns, with titles on the left, and components on the right. Flyover help can be included with the titles. Multiple components can be concatenated on a single row.

Most edited properties include title, subTitle and adjacentTitleWidth.

<Form name=’Default User Form’ help=’account/modify-help.xml’>
   <Display class=’EditForm’>
     <Property name=’titleWidth’ value=’120’>
     <Property name=’adjacentTitleWidth’ value=’60’>

Additional EditForm properties include:


Consists of three classes: Menu, MenuBar, and MenuItem.

Menu contains the following properties:

MenuBar contains the following properties:

MenuItem contains the following properties:

You can set these properties on either a MenuBar or MenuItem:

The following XPRESS example creates a menu with two tabs. The second tab contain two subtabs:

Example 7–1 Implementation of Menu, MenuItem, and MenuBar Components

<Display class=’Menu’/> 
   <Display class=’MenuItem’> 
      <Property name=’URL’ value=’user/main.jsp’/> 
      <Property name=’title’ value=’Home’ /> 
   <Display class=’MenuBar’ > 
      <Property name=’title’ value=’Work Items’ /> 
      <Property name=’URL’ value=’user/workItemListExt.jsp’ /> 
      <Display class=’MenuItem’> 
         <Property name=’URL’ value=’user/workItemListExt.jsp’/> 
         <Property name=’title’ value=’Approvals’ /> 
      <Display class=’MenuItem’> 
         <Property name=’URL’ value=’user/otherWorkItems/listOtherWorkItems.jsp’/> 
         <Property name=’title’ value=’Other’ /> 

In the Identity Manager User Interface, the horizontal navigation bar is driven by the End User Navigation User form in enduser.xml.

The userHeader.jsp, which is included in all Identity Manager User Interface pages, includes another JSP named menuStart.jsp. This JSP accesses two system configuration objects:

style.css contains the CSS style classes that determine how the menu is rendered.


Defines the most basic container. Panel renders its children in a simple linear list.

Properties include:

The default orientation is vertical, but can be set to horizontal.


Provides a single- or multi- valued field (similar to Text or ListEditor components, respectively) with search fields below. After a search is executed, Identity Manager displays results beneath the search fields and populates the results into the value field.

Unlike other container components, Selector has a value (the field we are populating with search results). The contained fields are typically search criteria fields. Selector implements a property to display the contents of the search results.

Properties include:

The following properties are valid only in a multi-valued component:

These properties are valid only in a single-valued component:


Arranges components in a grid with an optional row of column titles at the top.

Properties include:


Use to render a tabbed panel that displays a row of tabs as shown below. By default, the tabs are aligned horizontally.

Properties include:

<Field name=’MainTabs’>
   <Display class=’TabPanel’>
     <Property name=’leftTabs’ value=’false’/>
     <Property name=’tabAlignment’ value=’left’/>


Use to create a Panel capable of horizontal alignment.


Use to create a table whose contents can be sorted by column header.Child components determine the content of this table. Create one child component per column (defined by the columns property). Columns are typically contained within a FieldLoop.

This component respects the align, valign, and width properties of the children components when rendering the table cells.

Properties include:

For example, if the SortingTable component displays the results of a query containing editable items, to ensure that Identity Manager displays the results page that contains the edited item after the user has edited an item in the result table, enter a value that exceeds 0.


Use to render one of several child components (typically EditForms) that use wizard-style Next and Previous buttons to navigate between components.

Properties include:

Component Subclasses

All components extend the Component class, which defines the properties common to most components. In addition, some components extend the Container class, which gives them the ability to contain other components.

Each Component subclass defines a number of properties that are used to specify the characteristics of the component beyond those implied by the Component base class. For example, the Label component supports a font property, which can be used to specify the font used when rendering the label.

Naming Conventions

Properties always begin with a lowercase letter and use camel case to separate adjacent words. Access method names are formed by capitalizing the property name, and prefixing either get or set. For example, the property named font is accessible from Java using the getfont and setfont methods.

The data type for each property varies and is documented with the property. the terminology used to describe property value types is described in the following table.

Data Types

This table lists the data types allowed in component properties.

Table 7–2 HTML Component Property Data Types




Indicates that a property has no value 


Represents the most common data type. String values are usually represented by an instance of the Java String class. Some components are values of any class. These are implicitly coerced to strings with the toString method.

Unless otherwise specified, you can assume that all properties are of type string.

Example: <String>Hello World</String>

List of string

Indicates that the value is expected to be a list of one or more strings. In Java, this value is always implemented as an instance of the List class. The elements of the list are then expected to be instances of the String class.


   <String>choice one</String>
   <String>choice two</String>

Base Component Class

The Component class is the base class for all HTML components. It contains the properties that are common to most components. Not all Component properties are relevant in every subclass. For example, Component defines a property allowedValues that can contain a list of value constraints. This property is relevant only in subclasses that allow value editing such as Select or MultiSelect. Further, Container classes almost never directly represent an editable value. Consequently, any properties related to the component value are irrelevant. Some properties are relevant only if the component is contained within a specific Container class.


Specifies the internal name of a field. All editing components must have a name, which is typically unique among all components displayed on the page. name is a string that is usually a path to a view attribute.

Container components do not require names and any assigned names are ignored. When building components from Java, component names are defined by the application. When building components from XML forms, component names are derived from the names of Field elements in the form. Field names are in turn path expressions within the view object that is used with the form.


<Field name =’global.firstname’>

For more information on how the name attribute refers to a specific attribute in the user view, see Chapter 3, Identity Manager Views.


(Optional) Specifies the external name of a field. Titles are typically used with the EditForm container, which builds an HTML table that contains titles in one column and components in another.

Components do not render their own titles. Rendering of titles is controlled by the container. Many containers ignore titles.


<Property name=’title’ value=’FirstName’/>
<Property name=’title’>
         <s>Edit User: </s>

In this example, the field title is in part derived dynamically from the user’s Identity Manager account ID.


Editing components have a value that may be null. The value is typically set automatically by Identity Manager from an attribute in a view. Some components allow you to set the value by explicitly ignoring current view content. This value can be null.

The Component class allows the value to be any Java object. The subclass must coerce the value to a particular type when it is assigned, or when the HTML is generated. Component values are almost always String objects or List objects that contain strings. See the section titled Data Types for more information on component value types.

Most container classes do not have values. If you assign a value, it is ignored. Some containers do allow values (for example, TabPanel and WizardPanel).

When building components from XML forms, the value is usually derived by using the component name as a path into the underlying view object, which contains all the values being edited.


<Property name= ’value’ value=’false ’/>


Specifies an optional list of allowed values for the component. If specified, the component allows you to select from only values that are on the list. If the component supports value restrictions, the list of allowed values is stored here. The value is always a list and usually contains strings. For convenience when setting properties from XML forms, you can also specify the allowed values as a comma list.


<Property name=’allowedValues’ value= ’Mon, Tue, Wed, Thurs, Fri’/>
<Property name=’allowedValues’/>
      <call name=’DaysoftheWeek’/>


This property is recognized only by the SortingTable container. The SortingTable container organizes components into a table with each column expected to contain components of the same class. SortingTable allows the rows to be sorted according to the values in any column. Typically, the sort order is determined from the value of each component in the column. There may be cases, however, where the value of the component is not suitable for sorting or may be inefficient to compare. In these cases, you can specify an alternate numeric sorting key.


If true, indicates that the field is expected to have a value before the form is submitted. If the component is contained within an EditForm, a red * (asterisk) will be placed after the component to indicate that the user must enter a value before saving. If the required schema map attribute is selected, (that is, set to a value of true), the field is always required.

The value of the property must be either true or false.


<Property name=’required ’ value=’true ’/>


If true, the field displays on the Identity Manager page next to the previous field. If not specified or set to false, the field appears on a new line, directly under the previous field. The default value is false

This Boolean property is recognized only if the field is contained in a form that uses the EditForm display class. Typically, EditForm renders each component on a new row with the titles aligned in the left column and the component in the right column. To conserve space, you can concatenate several components on the same row. If the component also has a title, the title is rendered as non-highlighted text between the previous component and this component.

Values include:

value=’true ’ | ’false ’


<Property name=’noNewRow ’ value=’true ’/>


Use if the container defines more than one display area and the component must be added to a specific area. Some containers allow the placement of components to be controlled by assigning a value to the location property. For example, the BorderedPanel container supports five different display areas: north, south, east, west, and center.

The recognized values for the location property are defined by the container. If you do not assign a location, or assign a location name that is not recognized, the container places the component in the default location.


Specifies text that may be displayed to assist the user in understanding purpose of the field. In most Identity Manager pages, this will cause the <icon> icon to be displayed next to the component title. Moving the mouse over this icon will cause the help text to be displayed in the left margin.

The value of the property can either be literal text to be displayed, or it can be a message catalog key. Literal text can include HTML markup.

For more information on adding help to your custom form, see Adding Guidance Help to Your Form.


Specifies the text that can be rendered beneath a component in Identity Manager pages.

The value of the property can either be literal text to be displayed, or it can be a message catalog key. Literal text can include HTML markup.


Specifies a command to submit when a component is modified. (When a user makes a change to a value, form output is recalculated.)

This property is typically used with the Button component. Some components must cause immediate submission of the surrounding HTML form when they are modified so that the application can regenerate the page based on that modification. Setting the command property to a non-null value causes this behavior.

When the command property is set, and the component is modified, the form is posted and an extra hidden parameter named command is posted whose value is the value of the command property.

The command specifies how the system will process the edits that have been made to a view. The command property must have one of the following values.

Table 7–3 Values of command Property




Causes the edits to be saved. 


Causes the edits to be discarded. 


Causes the page to be regenerated. 


Causes the edits to be saved, but no form validation to be performed. 

Because specifying a command value of Recalculate is so common in forms, an shorter alterative syntax is available. The Display element has an attribute named action that when set to true, has the same effect as setting the command property to Recalculate.

<Display class=’Select’ action=’true’>"


When specified, the value is expected to contain JavaScript that will be assigned as the value of the onClick attribute of the input element generated for this component. Not all components support the onClick property.

Use of this property is rare and requires detailed knowledge of the generated HTML. If you use this property, the page must typically contain a Javascript component that defines JavaScript functions you call from within the onClick value.


<Property name=’onClick’ value="Uncheck(this.form, ’resourceAccounts.selectAll’);"/>

Note –

Once forms are stored in the repository, Identity Manager always uses single quotes to surround attribute values. If single quotes appear within the attribute value, they will be replaced with &#039;. To prevent this escaping you can represent the string in an XPRESS s expression:

<Property name=’onClick’>
   <s>Uncheck(this.form, ’resourceAccounts.selectAll’); </s>


Similar to command. The value can be an arbitrary JavaScript statement to run when the field is modified.

Not all components support the onChange property.

Use of this property is rare and requires detailed knowledge of the generated HTML. If you use this property, the page must typically contain a Javascript component that defines JavaScript functions you call from within the onChange value.

nowrap, align, width, valign, and colspan

Most containers position subcomponents by surrounding them with an HTML table tag. The HTML generated for each component then is typically contained in a td tag. Some containers can recognize the nowrap, align, width, and colspan properties and use them when generating the surrounding table cell tag. You can use these components to adjust the position and size of the component within the container.


<Property name= ’width’ value=’3’/>
<Field name=’Start Day’ prompt=’Day’ nowrap=’true’/>


Allows you to set the name attribute of the HTML <FORM> tag in which the component will be rendered. This ensures that JavaScript functions used by the component reference the desired HTML form. Because the default value is mainform, this property is useful only if the component is to be rendered in a form other than mainform.


<Property name=’htmlFormName’ value=’endUserNavigation’>

Basic Components


Displays a link that returns to the previous page. The behavior of this component is the same as that of the browser Back button. However, you may want to place this link in a convenient position on the page.

Properties for this display component:


<Field name=’back’>
   <Display class=’BackLink’>
      <Property name=’value’ value=’previous page’/>


Displays a button. Buttons typically submit the surrounding form, but they can also be defined to run arbitrary JavaScript.

Properties for this display component are:


<Display class =’Button’>
   <Property name =’label’ value =’Change Password’/>
   <Property name =’value’ value =’Recalculate’/>


Displays a checkbox. When selected, the box represents a value of true. An unselected box represents a false value.

Properties for this display component are:


<Field name=’accounts[AD].passwordExpired’>
   <Display class=’Checkbox’>
      <Property name=’title ’value=’Password is Expired’/>


Allows the user to specify a date using a pop-up window that displays a calendar. Identity Manager displays the field in the form as a calendar icon. When a user clicks on the icon, Identity Manager opens the calendar in a separate pop-up window.

This component allows a user to enter a date value. Depending on how you set the component properties, the user can enter a date value using select menus, a text field, or a calendar pop-up window. By default, the component renders with a text field and an icon that you click to bring up the calendar pop-up.

Properties include:


<Field name=’ExpireDate’>
   <Display class=’DatePicker’>
      <Property name=’title’ value=’Set Password Expire  date’/>
      <Property name=’format’= value=’iso’/>


Displays a text field and a Browse button that allows the user to select a file and upload it to the server. Use this component to import data into Identity Manager from a file (such as users or configuration objects). This component supports all the properties that the Text component supports.


Allows you to insert arbitrary HTML markup into a form field or other component contained within an HTML page, including JavaScript.

This component contains one property: html, which allows you to specify the string(s) that are rendered into the page.


<Display class=’Html’>
   <Property name=’html’>
         <s><![CDATA[<div class="DashAlrtMsgTxt">]]></s>
         <s><![CDATA[&nbsp;<a href=’]]></s>
         <message name=’UI_USER_MAIN_CLICK_HERE_INTRO’/>
         <message name=’UI_USER_MAIN_CLICK_HERE_REMAINDER’/>


Describes the root HTML page. This component can contain arbitrary HTML and browser JavaScript. Properties include:


Displays an error, warning, success, or informative alert box. This component is typically located at the top of a page. You can display multiple alerts in a single alert box by defining child components of type InlineAlert$AlertItem.

Properties for this display component include:

Example of Single Alert Message

   <Display class=’InlineAlert’>
      <Property name=’alertType’ value=’warning’/>
      <Property name=’header’ value=’Data not Saved’/>
      <Property name=’value’ value=’The data entered is not yet saved. Please click 
                                    Save to save the information.’/>

Example of Multiple Alert Messages

Define alertType only within the InlineAlert property. You can define other properties in the InlineAlert$AlertItems.

   <Display class=’InlineAlert’>
      <Property name=’alertType’ value=’error’/>
     <Display class=’InlineAlert$AlertItem’>
        <Property name=’header’ value=’Server Unreachable’/>
        <Property name=’value’ value=’The specified server could not be contacted. 
                                      Please view the logs for more information.’/>
        <Property name=’linkURL’ value=’viewLogs.jsp’/>
        <Property name=’linkText’ value=’View logs’/>
        <Property name=’linkTitle’ value=’Open a new window with the server logs’/>
     <Display class=’InlineAlert$AlertItem’>
        <Property name=’header’ value=’Invalid IP Address’/>
        <Property name=’value’ value=’The IP address entered is in an invalid subnet. 
                                      Please use the 192.168.0.x subnet.’/>


Use to insert pre-formatted JavaScript into the page. This is useful if you are using the onClick or onChange properties in components and want to call custom JavaScript functions.

Though not required, consider specifying the name property when building components from XML forms. Using features such as field loops and field inclusion, you can add more than one JavaScript component containing the same script to the page. During HTML generation, JavaScript components that have the same name are included only once.


<Display class=’Javascript’>
   <Property name=’script’>
         function setTextFromSelect(sel, textFieldName) {
         if ( sel == null || sel.inchange ) return;
         sel.inchange = true;
         var textField = sel.form.elements[textFieldName];
         if ( textField == null ) return;
         textField.value = sel.value;
         sel.selectedIndex = 0;
         sel.inchange = false;
         }  // setTextFromSelect(sel, textFieldName)
   <Property name=’noNewRow’ value=’true’/>

The component has an extended property named script that can contain the JavaScript text.


Displays a string of text.

Properties for this display component are:

Note –

If no padding is specified, the default padding is leftPad=2, rightPad=2.

   <Display class=’Label’>
      <Property name=’title’ value=’Account ID’/>
      <Property name=’value’>


Places a link on the page.

Properties include:


   <Display class=’Link’>
      <Property name=’name’ value=’Request
            Group Access’/>
      <Property name=’URL’
      <Property name=’id’ value=’Group Request

Note –

Link components are one place in your form where you might use a <map> element to pass name/value pairs. In the following example, the <map> element contains several pairs: a mapping of a String to a Boolean value and a String to a List.

<invoke class=’com.waveset.ui.FormUtil’


Renders a bulleted list of links, resembling a menu.


Renders an editable list of strings.


Properties include:


The following example shows a field that uses the ListEditor display class (Tabbed User Form):

<Field name=’accounts[Sim1].Group’>
     <Display class=’ListEditor’ action=’true’>
        <Property name=’listTitle’ value=’stuff’/>
        <Property name=’allowTextEntry’>
        <Property name=’ordered’>

This code snippet creates a field where the customer can add groups to or remove them from a user.

Note –

This display class typically requires a List of Strings as input. To coerce a single String into a List of Strings:



A component that renders a collection of name/value pairs in a simple two column table. This component directly renders the data it contains.

Data can be specified in several forms:

Properties include _hideEmptyRows, which when set to true, hides rows for which no value exists.


Displays a multiselection text box, which displays as a two-part object in which a defined set of values in one box can be moved to a selected box. Values in the left box are defined by the allowedValues property, values are often obtained dynamically by calling a Java method such as FormUtil.getResources. The values displayed in the right side of a multiselection box are populated from the current value of the associated view attribute, which is identified through the field name.

The form titles for this two-part object are set through the availabletitle and selectedtitle properties.

If you want a MultiSelect component that does not use an applet, set the noApplet property to true.

See Alternative to the MultiSelect Component for a related discussion.

Note –

If you are running Identity Manager on a system running the Safari browser, you must customize all forms containing MultiSelect components to set the noApplet option. Set this option as follows:

<Display class=’MultiSelect’>
      <Property name=’noApplet’ value=’true’/>

Properties for this display component are:


<Field name=’accounts[LDAP].LDAPDept’ type=’string’>
   <Display class=’MultiSelect’ action=’true’>
      <Property name=’title’ value=’LDAP Department’/>
             <String>International Sales</String>


Displays a horizontal list of one or more radio buttons. A user can select only one radio button at a time. If the component value is null or does not match any of the allowed values, no button is selected.

Properties for this display component are:


<Field name=’attributes.accountLockExpiry.unit’>
   <Display class=’Radio’>
     <Property name=’noNewRow’ value=’true’/>
     <Property name=’labels’>
     <Property name=’allowedValues’>


Displays a new section heading defined by the value of the text property. It is an extension of the Label class that sets the font property to a style that results in large bold text. It also sets the pad property to zero to eliminate the default 2 space padding. Use it to break up long forms into sections separated by a prominent label.

The only property for this display component is text, which specifies the text to be displayed.


   <Display class=’SectionHead’>
      <Property name=’text’ value =’Calculated Fields’/>


Displays a single-selection list box. Values for the list box must be supplied by the allowedValues property.

Properties for this display component are:

The component supports the command and onChange properties.


<Field name=’city’ type=’string’>
   <Display class=’Select’>
      <Property name=’title’ value=’City’/>
      <Property name=’allowedValues’>
            <String>New York</String>


Displays a regular text entry box.

Common properties for this display component are:


<Field name=’variables.identityID’>
   <Display class=’Text’>
      <Property name=’required’>
      <Property name=’title’ value=’Identity ID’/>
      <Property name=’size’ value=’32’/>
      <Property name=’maxLength’ value=’128’/>
      <Property name=’submitOnEnter’ value=’Save’/>


Displays a multi-line text entry box.

Properties for this display component are:


To display a text box with five visible rows that wraps after each 70 characters specify:

<Field name=’Description’>
   <Display class=’TextArea’>
     <Property name=’rows’ value=’5’/>
     <Property name=’columns’ value=’70’/>

If the user enters text beyond the defined visible rows, the text area displays a scroll bar.

Alternative to the MultiSelect Component

It can be unwieldy to display many admin roles using the MultiSelect component (either the applet or HTML version). Identity Manager provides a more scalable way of displaying and managing admin roles: the objectSelector field template.

The Scalable Selection Library (in sample/formlib.xml) includes an example of using an objectSelector field template to search for admin role names that a user can select.

Example 7–2 Example of objectSelector Field Template

<Field name=’scalableWaveset.adminRoles’> 
   <FieldRef name=’objectSelector’> 
      <Property name=’selectorTitle’ value=’_FM_ADMIN_ROLES’/> 
      <Property name=’selectorFieldName’ value=’waveset.adminRoles’/> 
      <Property name=’selectorObjectType’ value=’AdminRole’/> 
      <Property name=’selectorMultiValued’ value=’true’/> 
      <Property name=’selectorAllowManualEntry’ value=’true’/> 
      <Property name=’selectorFixedConditions’> 
            <new class=’com.waveset.object.AttributeCondition’> 
      <Property name=’selectorFixedInclusions’> 

ProcedureHow to Use the objectSelector Example Code

  1. From the Identity Manager IDE, open the Administrator Library UserForm object.

  2. Add the following code to this form:

       <ObjectRef type=’UserForm’ name=’Scalable Selection Library’/>
  3. Select the accounts[Lighthouse].adminRoles field within the AdministratorFields field.

  4. Replace the entire accounts[Lighthouse].adminRoles with the following reference:

    <FieldRef name=scalableWaveset.adminRoles/>

  5. Save the object.

    When you subsequently edit a user and select the Security tab, Identity Manager displays the customized form. Clicking... opens the Selector component and exposes a search field. Use this field to search for admin roles that begin with a text string and set the value of the field to one or more values.

    To restore the form, import $WSHOME/sample/formlib.xml from Configure > Import Exchange File.

    See the Scalable Selection Library in sample/formlib.xml for other examples of using the objectSelector template to manage resources and roles in environments with many objects.