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.

name

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.

Example

<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.

title

(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.

Example

<Property name=’title’ value=’FirstName’/>
<Property name=’title’>
   <expression>
      <concat>
         <s>Edit User: </s>
         <ref>waveset.accountId</ref>
      </concat>
   </expression>
</Property>
 

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

value

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.

Example

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

allowedValues

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.

Example

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

primaryKey

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.

required

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.

Example

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

noNewRow

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 ’

Example

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

location

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.

help

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.

inlineHelp

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.

command

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

Value	Description
Save	Causes the edits to be saved.
Cancel	Causes the edits to be discarded.
Recalculate	Causes the page to be regenerated.
SaveNoValidate	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’>"

onClick

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.

Example

<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>
</Property>"

---

onChange

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.

• nowrap– Specifies how some components are displayed if they contain a long string of text. If the value of nowrap is false or unspecified, the browser can break up the component text into multiple lines when it is displayed. If the value of noWrap is true, the browser will try to keep the component text on a single line.

• align– Rarely used. Adjusts the element horizontally on the form. Allowed values are left, right, and center.

• valign– Rarely used. Specifies where components are rendered vertically. Allowed values are top, bottom, and middle.

• colspan– Deprecated

Example

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

htmlFormName

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.

Example

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