Sun Java System Directory Editor 1 2005Q1 Installation and Configuration Guide |
Appendix A
HTML Components Used to Define Directory Editor FormsThis appendix describes the HTML components you can use when customizing Directory Editor forms.
OverviewTo customize a Directory Editor form, you can use Directory Editor’s Form XML language (also called forms), to describe HTML display components.
Directory Editor interprets this language at runtime to build the necessary components, allowing you to generate new pages dynamically with little or no additional Java development — which greatly simplifies customization.
This section contains the following topics:
What Are HTML Components?HTML display components are instances of Java classes that generate a string of HTML text. Each display component has:
- Class name (defined in the field by the DisplayClass element): Identifies the component class, which determines the component’s fundamental behavior and defines the set of properties recognized by the component.
- Properties (defined in the field with Property elements): Further define field behavior and appearance. You can specify one or more properties.
Specify display components as follows:
<Field name=' Name '>
<Display class=' Class '>
<Property name=' Name ' value=' Value '/>
</Display>
</Field>
Component ClassesHTML 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 Components.
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 a page 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.
Page Processor Requirements for HTML ComponentsThis section describes the Directory Editor page processor requirements to display forms that implement HTML components. It covers:
Hidden Parameters
Most components have a name that corresponds to the name of a parameter posted from an HTML form. Directory Editor reserves a few parameter names for general use. Do not use these names as component names.
Component SubclassesAll 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 following methods:
The data type for each property varies and is documented with the property.
Data Types
This table lists the data types allowed in component properties.
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.
This section describes the Base Component Classes used by Directory Editor:
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. The name value 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'>
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.
Examples:
<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 Directory Editor account ID.
value
Editing components have a value that may be null. The value is typically set automatically by Directory Editor 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 Data Types for more information about 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 Directory Editor 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 Directory Editor 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.
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.
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');"/>
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, 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.
The nowrap property affects 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.
The align property is rarely used. You can use align to adjust the element horizontally on the form. Allowed values are left, right, and center.
Use of the colspan property is deprecated.
Examples
<Property name= 'width' value='3'/>
<Field name='Start Day' prompt='Day' nowrap='true'/>Basic Components
This section describes the Basic Components used by Directory Editor:
BackLink
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.
The only property for this display component is text, which is used to specify text for the link. If you do not specify text, the link defaults to Back.
Example:
<Field name='back'>
<Display class='BackLink'>
<Property name='value' value='previous page'/>
</Display>
</Field>
Button
Displays a button.
Properties for this display component are:
- name: Specifies the name of the parameter that will be posted when the user clicks this button. This property is optional; if not specified, the default value is command.
- value: Specifies the value of the parameter posted when the user clicks this button.
- label: Specifies the visible text that displays on the button.
- command: Specifies an optional value to submit along with the name parameter (for example, Save, Cancel, Recalculate).
- postURL: Specifies an alternate, target URL to which the form will be posted. This value overrides the URL specified in the JSP.
- hiddenID: Specifies an optional value for an id parameter to be included in the form post data.
Example:
<Display class='Button'>
<Property name='label' value='Change Password'/>
<Property name='value' value='Recalculate'/>
</Display>
Checkbox
Displays a checkbox.
Properties for this display component are:
- label: (Optional) Specifies a label that is displayed to the right of the checkbox. It is displayed adjacent to the component, but is not displayed in the title column
- leftLabel: Specifies that the label should appear to the left of the checkbox.
- value: Determines the state of the checkbox. If the value is logically true, the checkmark is displayed.
Example:
<Field name='accounts[NT].passwordExpired'>
<Display class='checkbox'>
<Property name='title 'value='Password is Expired'/>
</Display>
</Field>DatePicker
Allows the user to specify a date using an applet that displays a calendar. The field is displayed in the form as a calendar icon. When the icon is clicked, the calendar applet is launched in a separate window.
Properties for this display component are:
The only property for this display component is value, which specifies the date to be highlighted on the calendar as the current date. You can parse the Date property from either a Date object or a String object. String values are expected to conform to the "MM/dd/yyyy" format.
Example:
<Field name='ExpireDate'>
<Display class='DatePicker'>
<Property name='title' value='Set Password Expire date'/>
</Display>
</Field>Javascript
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, you should specify 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.
The component has an extended property named script that can contain the JavaScript text.
You can also include JavaScript by setting the property named source. This should be a string containing a URL fragment relative to the base context. It is the JavaScript contained in the indicated file to be loaded by the browser.
Label
Displays a string of text.
Properties for this display component are:
- value: Defines the text to be displayed. The value can be either a string or a list of strings. When the value is a list, each string in the list is displayed on a separate line.
- leftPad: Specifies the number of spaces to insert to the left of the label.
- pad: Specifies the number of spaces to insert to the left and right of the label.
- rightPad: Specifies the number of spaces to insert to the right of the label.
Link
Places a link on the page.
Properties for this display component are:
- URL: Specifies the target Uniform Resource Locator (URL).
- imageURL: (optional) Specifies the URL to an icon or image that will be rendered to the right of the link.
- imageURL2: (optional) Specifies the URL to an icon or image used will be rendered to the right of the first image.
- hoverText: Specifies text to display when the mouse rests over the first or second image.
- id: (optional) Specifies a value to be included as the id query argument in the link.
- arguments: (optional) Specifies a set of name/value pairs to be included as query arguments.
- extraURL: (optional) Specifies an additional URL fragment to be included after the base URL and arguments.
Example:
<Field>
<Display class='Link'>
<Property name='name' value='Request Group Access'/>
<Property name='URL' value='user/processLaunch.jsp?newView=true'>
<Property name='id' value='Group Request Process'/>
</Display>
</Field>MultiSelect
Displays a multiple-selection 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 multiple-selection 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.
Properties for this display component are:
- availableTitle: Specifies the title of the available box.
- selectedTitle: Specifies the title of the selected box.
- ordered: Defines whether selected items can be moved up or down within the list of items in the text box. A true value indicates that additional buttons will be rendered to permit selected items to be moved up or down.
- allowedValues: Specifies the values associated with the left side of the multiple-selection box. This value must be a list of strings.
- sorted: Specifies that the values in both boxes will be sorted alphabetically.
- noApplet: Specifies whether the multiselect will be implemented with an applet or with a pair of standard HTML select boxes. The default is to use an applet, which is better able to handle long lists of values.
- typeSelectThreshold: (Available only when the noApplet property is set to true.) Controls whether a type-ahead select box appears under the allowedValue list. When the number of entries in the left select box reaches the threshold defined by this property, an additional text entry field appears under the select box. As you type characters into this text field, the select box will scroll to display the matching entry if one exists. For example, if you enter w, the select box scrolls to the first entry that begins with w.
- lockhart: Controls the look-and-feel of the non-applet version of this component.
Example:
<Field name='accounts[LDAP].LDAPDept' type='string'>
<Display class='MultiSelect' action='true'>
<Property name='title' value='LDAP Department'/>
</Display>
<Constraints>
<o>
<List>
<String>Sales</String>
<String>Marketing</String>
<String>International Sales</String>
</List>
</o>
</Constraints>
</Field>Radio
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:
- title: Specifies the title for all radio buttons.
- labels: Specifies an alternate list of button labels. The labels list must be as long as the values in the allowedValues list. Alternate labels can be used in cases where the values are cryptic. For example, values can be letter codes such as "H", "M", and "S”, but you would use this property to identify button labels "hours", "minutes", and "seconds".
- allowedValues: Specifies the value associated with each button. This value must be a list of strings.
- value: Specifies values for the buttons. This value accepts one string. If not set, then the values are the same as the labels.
Example:
To display a container that contains two fields that prompt the user for a delayed start time for an activity, specify the following code. It will create a text field in which the user enters a numeric value and a second field of radio buttons that the user sets to specify the increment. The field has three radio buttons labeled (in order) Days, Hours, and Minutes, with values of minutes, hours, days, weeks, and months.
The StartDate field converts the value specified by the user into hours.
The only property for this display component is value, which specifies the date to be highlighted on the calendar as the current date. Date can be parsed from either a Date object or a String object. String values are expected to conform to the "MM/dd/yyyy" format.
Example:
<Field name='ExpireDate'>
<Display class='DatePicker'>
<Property name='title' value='Set Password Expire date'/>
</Display>
</Field>SectionHead
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 two-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.
Example:
<Field>
<Display class='SectionHead'>
<Property name='text' value ='Calculated Fields'/>
</Display>
</Field>Select
Displays a single-selection list box. Values for the list box must be supplied by the allowedValues property.
Properties for this display component are:
- allowedValues: Specifies the list of selectable values for display in the list box.
- autoSelect: When set to true, this property causes the first value in the allowedValues list to be automatically selected if the initial value for the field is null.
- multiple: When set to true, allows more than one value to be selected.
- nullLabel: Specifies the text that displays at the top of the list box when no value is selected.
- size: (optional) Specifies the maximum number of rows to display. If the number of rows exceeds this size, a scroll bar is added.
- sorted: When set to true, causes the values in the list to be sorted.
- valueMap: Maps raw values to displayed values.
The component supports the command and onChange properties.
Example:
<Field name='city' type='string'>
<Display class='Select'>
<Property name='title' value='City'/>
<Property name='allowedValues'>
<List>
<String>Austin</String>
<String>Portland</String>
<String>New York</String>
</List>
</Property>
</Display>
</Field>SimpleTable
Arranges components in a grid with an optional row of column titles at the top. The only property for this display component is columns, which assigns column titles and defines the width of the table as defined in a list of strings.
Text
Displays a regular text entry box.
Common properties for this display component are:
- size: Specifies the number of characters that are visible in the text entry box. The box size is recalculated depending upon the length of the text in the box.
- maxLength: Specifies the maximum length of the string that can be edited in the text box.
- secret: Displays ***** (asterisks) in the place of entered text. This option is most often used in password fields.
- readOnly: Displays read-only text. This text cannot be edited by the user. You might use this property if, for example, you want to display resource attribute information that an administrator needs to view when creating or editing user accounts.
- submitOnEnter: When you set this property and the Text field has focus, then when the user presses the Enter key, the form is submitted using the command that is specified in the property value. In the following example, the form is submitted exactly as though the user has clicked the Save button.
- multivalued: When you set this property, the component is rendered with controls that allow users to add or remove multiple values of an attribute.
Example:
<Field name='variables.identityID'>
<Display class='Text'>
<Property name='required'>
<Boolean>true</Boolean>
</Property>
<Property name='title' value='Identity ID'/>
<Property name='size' value='32'/>
<Property name='maxLength' value='128'/>
<Property name='submitOnEnter' value='Save'/>
</Display>
</Field>Text Area
Displays a multi-line text entry box.
Properties for this display component are:
Example:
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'/>
</Display>
</Field>If the user enters text beyond the defined visible rows, the text area displays a scroll bar.