This chapter describes the Waveset HTML display component library. HTML display components are used when customizing forms. See Chapter 2, Waveset Forms for a discussion of the larger topic of customizing forms.
This chapter covers the following topics:
If you are designing forms, you will use the HTML components described in this section. To create a form, you can use the Waveset 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.
HTML display components are instances of Java classes that generate a string of HTML text. Each display component has:
A class name (defined in the field by the class attribute of the Display element). This name identifies the component class, which determines the component’s fundamental behavior and defines the set of properties recognized by the component.
One or more properties (defined in the field with Property elements). Properties further define field behavior and appearance.
You can specify display components as follows:
<Field name=’Name’> <Display class=’Class’> <Property name=’Name’ value=’Value’/> </Display> </Field>
Forms that implement HTML components have the following page processor requirements.
Most components have a name that corresponds to the name of a parameter posted from an HTML form. Waveset reserves a few parameter names for general use. Do not use these names as component names.Table 7–1 Hidden Parameters
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
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– Components used to display and edit a single value.
Container classes– Components that can contain one or more components.
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.
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.
eastWidth– Specifies the width of the east region
westWidth– Specifies the width of the west region
Sets default options for button placement. Extends the Panel component.
buttonDivStyle - Specifies the CSS class to apply to a div surrounding the buttons.
defaultAlign - Specifies the default alignment of the buttons in the row. Waveset consults this property if the align property has not been explicitly set on the row. Defaults to left.
defaultDivider - Specifies whether to render a divider above or below the button row. Waveset consults this property if the divider property has not been explicitly set on the row. Defaults to false.
divider– Specifies whether the divider should be rendered as a horizontal or blank line. When true, the divider will be rendered as a horizontal line (for example, an <hr>). (Boolean)
dividerSet — is false until the setter has been called on the divider property.
dividerStyle - Specifies the CSS class to use to style the divider if it is rendered. If this property is not set, Waveset renders a horizontal rule. Defaults to unset.
pad– Specifies where to insert this space between the button row and an adjacent component. Allowed values are top and bottom. If the value is null, no space is added. Default value is top.
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’> </Display>
Additional EditForm properties include:
adjacentTitleWidth– Specifies the width of the titles of adjacent fields. If this property is not defined, it defaults to zero. If you define adjacentTitleWidth as equal to zero, columns titles will automatically resize. If set to a non-zero value, then the title width of adjacent columns (for example, the second and third columns) will be the value of adjacentTitleWidth.
border - Specifies the width in pixels of the table that contains the EditForm component. Defaults to 0, which indicates no border.
cellpadding - Specifies the cellpadding of the table that contains the EditForm component. Defaults to 5.
cellspacing - Specifies the cellspacing of the table that contains the EditForm component. Defaults to 0.
componentTableWidth– Specifies the width (in pixels) of the EditForm. If not specified, this defaults to either 400 pixels or the value of the defaultComponentTableWidth global property for EditForm
defaultComponentTableWidth - Specifies the width in pixels of the table in which Waveset renders each component. Waveset consults this property if the componentTableWidth property has not been explicitly set on the EditForm. When this component is not set, no width is specified for the component table.
defaultRequiredAnnotationLocation - Specifies the default location (left, right, or none) with respect to the component to render the required annotation. Waveset consults this property if the requiredMarkerLocation property has not been explicitly set on the EditForm. Defaults to right.
evenRowClass - Specifies the CSS class to use to style the even rows of the EditForm table (if the noAlternatingRowColors property is not set to true). Defaults to formevenrow.
helpIcon - Specifies the icon to render for flyover help messages for components. Defaults to images/helpi_gold.gif.
noAlternatingRowColors– Specifies whether rows in the EditForm are rendered in the same color. When noAlternatingRowColors is set to true, every row in the EditForm is rendered the same color. If not specified, this defaults to false.
oddRowClass - Specifies the CSS class to use to style the odd rows of the EditForm table (if the noAlternatingRowColors property is not set to true). Defaults to formoddrow.
requiredAnnotation - Specifies the annotation to render next to a required field. This defaults to an image of a red asterisk.
requiredClass - Specifies the CSS class to use to style the required field legend. Defaults to errortxt.
requiredLegendLocation - Specifies the location (top or bottom) at which to render the required legend if the form contains any required fields. Defaults to bottom.
rowPolarity - Specifies the polarity of alternating gray and white row colors in a table. The default is true. A value of false inverts the polarity and gives the first form field a white background. The code shown in the following example results in a table whose first form field has a white background.
<Display class=’EditForm’> <Property name=’componentTableWidth’ value=’100%’/> <Property name=’rowPolarity’ value=’false’/> <Property name=’requiredMarkerLocation’ value=’left’/> <Property name=’messages’> <ref>msgList</ref> </Property> </Display>
tableClass - Specifies the CSS class to use to style the table that contains the EditForm component.
tableWidth - Specifies the width in pixels of the table in which Waveset renders the EditForm component. Defaults to 400.
titleClass - Specifies the CSS class to use to style help messages for components.
Consists of three classes: Menu, MenuBar, and MenuItem.
Menu refers to the entire component.
MenuItem is a leaf, or node, that corresponds to a tab on the first or second level.
MenuBar corresponds to a tab that contains MenuBars, or MenuItems.
Menu contains the following properties:
layout - A String with value horizontal or vertical. A value of horizontal generates a horizontal navigation bar with tabs. A value of vertical causes the menu to be rendered as a vertical tree menu with typical node layout.
stylePrefix - String prefix for the CSS class name. For the Waveset End User pages, this value is User.
MenuBar contains the following properties:
default - A String URL path that corresponds to one of the MenuBar’s MenuItem URL properties. This controls which subtab is displayed as selected by default when the MenuBar tab is clicked.
MenuItem contains the following properties:
containedUrls - A List of URL path(s) to JSPs that are ”related” to the MenuItem. The current MenuItem will be rendered as “selected”if any of the containedUrls JSPs are rendered. An example is the request launch results page that is displayed after a workflow is launched from the request launch page.
You can set these properties on either a MenuBar or MenuItem:
title - Specifies the text String displayed in the tab or tree leaf as a hyperlink
URL - Specifies the String URL path for the title hyperlink
The following XPRESS example creates a menu with two tabs. The second tab contain two subtabs:
<Display class=’Menu’/> <Field> <Display class=’MenuItem’> <Property name=’URL’ value=’user/main.jsp’/> <Property name=’title’ value=’Home’ /> </Display> </Field> <Field> <Display class=’MenuBar’ > <Property name=’title’ value=’Work Items’ /> <Property name=’URL’ value=’user/workItemListExt.jsp’ /> </Display> <Field> <Display class=’MenuItem’> <Property name=’URL’ value=’user/workItemListExt.jsp’/> <Property name=’title’ value=’Approvals’ /> </Display> </Field> <Field> <Display class=’MenuItem’> <Property name=’URL’ value=’user/otherWorkItems/listOtherWorkItems.jsp’/> <Property name=’title’ value=’Other’ /> </Display> </Field> </Field>
In the Waveset 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 Waveset User Interface pages, includes another JSP named menuStart.jsp. This JSP accesses two system configuration objects:
ui.web.user.showMenu - Toggles the display of the navigation menu on/off (default is true).
ui.web.user.menuLayout - Determines whether the menu is rendered as a horizontal navigation bar with tabs (the default value is horizontal) or a vertical tree menu (vertical).
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.
horizontal– Aligns components horizontally, when set to true. (Boolean)
horizontalPad– Specifies the number of pixels to use for the cell padding attribute of the table surrounding horizontal components.
verticalPad– Specifies the number of blank lines added between components. (Boolean)
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, Waveset 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.
fixedWidth– Specifies whether the component should have a fixed width (same behavior as Multiselect). (Boolean)
multivalued– Indicates whether the value is a List or a String. (The value of this property determines whether a ListEditor or Text field is rendered for the value). (Boolean)
allowTextEntry– Indicates whether values must be selected from the supplied list or can be entered manually. (Boolean)
valueTitle– Specifies the label to use on the value component. (String)
pickListTitle– Specifies the label to use on the picklist component. (String)
pickValues– the available values in the picklist component (if null, the picklist is not shown). (List)
pickValueMap– a map of display labels for the values in the picklist. (Map or List)
searchLabel– Labels the button next to the input text field with the supplied text. If not set, the text defaults to “...”.
sorted– Indicates that the values should be sorted in the picklist (if multivalued and not ordered, the value list will also be sorted). (Boolean)
clearFields– Lists the fields that should be reset when the Clear button is selected. (List)
The following properties are valid only in a multi-valued component:
ordered– Indicates that the order of values is important. (Boolean)
allowDuplicates– Indicates whether the value list can contain duplicates. (Boolean)
valueMap– Provides a map of display labels for the values in the list. (Map)
These properties are valid only in a single-valued component:
nullLabel– Specifies a label to use to indicate a value of null. (String)
Arranges components in a grid with an optional row of column titles at the top.
columns– Defines the column headers. Usually a list of message keys, but can also be simple strings. (List)
rows– Defines the cells of the table. Each cell must be a component. (List)
columnCount– Specifies the number of columns if there is no column title list.
border– Determines the width of the table border. Set to 0 to create invisible borders.
noItemsMessage– Specifies the message to display in the table when there are no rows.
Use to render a tabbed panel that displays a row of tabs as shown below. By default, the tabs are aligned horizontally.
leftTabs– When set to true, aligns tabs along left margin, not along the top. (Boolean)
border– Draws a border around the main panel under the tabs, when set to true. (Boolean)
renderTabsAsSelect– Renders tabs as a Select drop-down rather than tabs, when set to true. This is useful when a form contains many tabs that would cause the browser to scroll horizontally. Do not use in conjunction with aligning the tabs on the left.
tabAlignment– Determines the position of the tabs relative to the page content. Valid values include left (default setting), top, right, bottom, center, and middle.
validatePerTab -- When set to true, Waveset performs validation expressions as soon as the user switches to a different tab.
<Field name=’MainTabs’> <Display class=’TabPanel’> <Property name=’leftTabs’ value=’false’/> <Property name=’tabAlignment’ value=’left’/> </Field>
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.
emptyMessage– Specifies the String or message key to display in the table when the table has no rows. If you omit this property, Waveset displays a generic message.
pageButtonAlign– Determines position of buttons relative to page content. Valid values include left, right, bottom, and center. The default value is right.
sortEnable– Enables column sorting when set to true. (Boolean)
sortURL– Identifies the URL that Waveset posts to when column sorting is selected. If column sorting is not set, Waveset uses the _postURL of the HtmlPage. (String)
sortURLParams– Specifies the parameters that get passed along with the sortURL. (String)
sortColumn– Specifies the number of the column that we are currently sorting by. The default is to set this value to the first column. (Integer)
sortOrder– Specifies the sort order. Values includes asc (for ascending) or desc (for descending). Default value is asc. (String)
linkEnable– Indicates if this table is to be generated with the first column as links. (Boolean)
linkURL– Specifies the URL that Waveset links to when generating links. If not specified, defaults to the post URL of the containing HtmlPage. (String)
linkURLArguments– Indicates the arguments to include in the link URL.
linkColumn– Specifies the column number that will be used for the generated links as specified by the linkURL attribute. (Integer)
linkParameter– Specifies the name of the post data parameter that will have the value of the link row id. The default value is id.
selectEnable– Indicates whether a column of checkboxes is displayed along a MultiSelect table’s left margin. When set to true, Waveset displays a column of checkboxes. (Boolean)
columns– Lists table column headers. (List of strings)
pageSize– Specifies that the table should display at most _pageSize entries simultaneously. If more than _pageSize entries exist, then interface elements allow paging through the results. If _pageSize is less than 1 (the default setting), then all entries are displayed at once. (Integer)
useSavedPage– If set to true and if the value of pageSize exceeds 0, then the sorting table saves the current sorting table page on the HTTP session in the <fieldName>_currentPage attribute. The _useSavedPage property indicates whether the current page should be retrieved from the HTTP session and displayed. By making the value of this property the result of an XPRESS expression, the form or view can control when the current page is recalled after when returning back to the JSP containing the SortingTable component. (Boolean)
If you use multiple sorting tables in a form, you must enable the useSavedPage property for each table. Each field in the form must have a unique name.
For example, if the SortingTable component displays the results of a query containing editable items, to ensure that Waveset 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.
button– Specifies a value for child component’s location property that will place it in the button row. (String)
nextLabel– Specifies the label to display on the Next button. The default text is Next. (String)
prevLabel– Specifies that the label in the Previous button is displayed. (String)
cancelLabel– Specifies that the label in the Cancel button is displayed. (String)
okLabel– Specifies that the label is displayed in the OK button. (String)
noOk– Specifies that the OK button is not displayed. (Boolean)
alwaysOk– Determines that the OK button is displayed, when set to true. (Boolean)
noCancel– Specifies that the Cancel button is not displayed, when set to true. (Boolean)
topButtons– Causes the buttons to be rendered at the top of the page rather than the page bottom, when set to true. (Boolean)
noButtons– Suppresses all button rendering when set to true. (Boolean)
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.
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.
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.
<List> <String>choice one</String> <String>choice two</String> </List>
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, Waveset 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’> <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 Waveset account ID.
Editing components have a value that may be null. The value is typically set automatically by Waveset 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’/> <expression> <call name=’DaysoftheWeek’/> </expression> </Property>
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 Waveset 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.
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 Waveset 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 Waveset 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’>"
<Property name=’onClick’ value="Uncheck(this.form, ’resourceAccounts.selectAll’);"/>
Once forms are stored in the repository, Waveset always uses single quotes to surround attribute values. If single quotes appear within the attribute value, they will be replaced with '. 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>"
Not all components support the onChange property.
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.
<Property name= ’width’ value=’3’/> <Field name=’Start Day’ prompt=’Day’ nowrap=’true’/>
<Property name=’htmlFormName’ value=’endUserNavigation’>
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:
text– Specifies the text of the link. If you do not specify text, the link defaults to Back.
<Field name=’back’> <Display class=’BackLink’> <Property name=’value’ value=’previous page’/> </Display> </Field>
Properties for this display component are:
class - Specifies the CSS class to use for an enabled button. Defaults to formbutton.
command– Specifies an optional value to submit along with the name parameter (for example, Save, Cancel, Recalculate).
confirmDialogAccept — Specifies the text to display on the button that accepts the action on the confirmation dialog. This property is not available on the legacy interfaces.
confirmDialogCancel — Specifies the text to display on the button that cancels the action on the confirmation dialog. This property is not available on the legacy interfaces.
confirmDialogText — Specifies the ext that is displayed to the user in a dialog that asks whether to confirm an action. This property is not available on the legacy interfaces.
disabledclass - Specifies the CSS class to use for a disabled button. Defaults to formbutton.
formName — Specifies the name of the man form.
hiddenID– Specifies an optional value for an id parameter to be included in the form post data.
label– Specifies the visible text that displays on the button.
link — Causes the button to look like a link when set to true. This properties is for forms that combine links and editable fields on the same page. Because normal links do not post form data, the link behaves like a button.
linkClass - Specifies the CSS class to use when a button is rendered as a link.
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.
nullValue — Indicates the result of getPostData should be null when this value is set to true.
postURL– Specifies an alternate, target URL to which the form will be posted. This value overrides the URL specified in the JSP.
value– Specifies the value of the parameter posted when the user clicks this button.
waitDialogText — Specifies the text that is displayed to the user in a dialog after the button is clicked. This property is not available on the legacy interfaces.
<Display class =’Button’> <Property name =’label’ value =’Change Password’/> <Property name =’value’ value =’Recalculate’/> </Display>
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:
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.
checkAll– Set when this checkbox is serving as a Select All checkbox, which should then propagate its value to a set of other checkboxes. The value of the property is a regular expression that is used to match the names of other checkboxes on the HTML page.
uncheck– Set to the name of another checkbox field that represents the Select All checkbox in a collection of synchronized checkboxes. If this is set, whenever the selected status of this checkbox is changed, the Select All checkbox is unselected.
syncCheck– Set to the name of another checkbox field that must stay in sync with the value of the checkbox field on which this property is set. If this is set, whenever the value of this checkbox is changed, the sync’ed checkbox’s value is set to the same value.
syncUncheck– Set to the name of another checkbox field that should stay in sync when the value of the checkbox field on which this property is set is changed to false. If this is set, whenever the value of this checkbox is changed to false, the synchronized checkbox’s value will also be set to false (unselected).
syncCheckAllTo– Indicates that all Select All checkboxes matching the regular expression will be kept in sync with the value of the checkbox field on which this property is set when its value is changed to false. The value of this property is a regular expression that represents one or more of the Select All checkboxes.
syncUncheckAll– Set to the name of another checkbox field that should stay in sync when the value of the checkbox field on which this property is set is changed to false. If this is set, whenever the value of this checkbox is changed to false, the synchronized checkbox’s value will also be set to false (unselected).
syncCheckTo– Indicates that all checkboxes matching the regular expression will be kept in sync with the value of the checkbox field on which this property is set. Whenever the value of the checkbox field on which this property is set is changed, the sync’ed checkbox’s value will be set to the same value. The value of the property is a regular expression.
dontUncheckAllIfTrue — Specifies a regular expression of a set of checkboxes that will be checked, and if true, the value of syncCheckAllTo or syncUncheckAll will not be set to false. This property is only valid when syncCheckAllTo or syncUncheckAll is set.
syncUncheckMatching — This property is only valid when syncCheck, syncCheckTo, or syncUncheck is set. When this property is set, the value specified will be checked, and if true, the syncCheck, syncCheckTo, or syncUncheck value will not be set to false (unchecked).
dontUncheckIfTrue — Specifies the name of another checkbox field, which represents the “select all” checkbox in a collection of synchronized checkboxes. When the “select all” checkbox is selected, this checkbox does not become unselected.
syncCheckIfAllSame — Specifies the name of another checkbox field, which represents the “select all” checkbox in a collection of synchronized checkboxes. This property is only valid when syncCheckIfAllSame is set.
checkIfTrue — Used with syncCheckAllTo, syncCheckTo, and syncCheck to specify the namespace where the “All” checkbox can be found that corresponds with this checkbox.
namespace — Used with syncCheckIfAllSame when checkIfTrue is set to specify the namespace for the list of individual checkboxes.
value– Determines the state of the checkbox. If the value is logically true, the checkmark appears.
<Field name=’accounts[AD].passwordExpired’> <Display class=’Checkbox’> <Property name=’title ’value=’Password is Expired’/> </Display> </Field>
Allows the user to specify a date using a pop-up window that displays a calendar. Waveset displays the field in the form as a calendar icon. When a user clicks on the icon, Waveset 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.
command– Specifies an optional value to submit (for example, Save, Cancel, or Recalculate). Setting this property to Recalculate has the same effect as setting the action property to true, which triggers a refresh (or other) operation. You can trigger a refresh operation by either:
Selecting the date with the date widget
Changing the date in the text area and tabbing to or clicking another screen area for the refresh to occur.
See the discussion of the command property in Base Component Class for more information.
disableTextInput– (Boolean) When set to true, the component renders the date text string without the text input box. Without a text input box, a user cannot edit this field. To change the value of the date string, the user must click the calendar icon and select a date using the pop-up window. Waveset displays the newly selected date as plain text next to the calendar icon.
If this property is not present, or if set to false, the component renders the input text field normally.
displayFormatHint– Determines whether the component presents a hint of the expected date format to be entered in the text field. When set to true, Waveset renders a “hint” of the expected date format. The value of the format string is determined by the component’s format property. Waveset does not present a hint under these circumstances:
this property is set to false
this property is missing
multiField property is set to true
disableTextInput is true.
format– Specifies the date format to use for displaying the date. This can be a Java-style date formatting string that uses any of the following formatting characters: y, M, or d. This can also be the value iso, specifying ISO format (yyyy-MM-dd), or the value local, specifying a locale-sensitive format (the Java default for the locale). If omitted, Waveset uses the format “MM/dd/yyyy”.
multiField– Indicates whether separate input fields should be displayed for each element of the date. If omitted or false, Waveset uses a single text field for input, expecting properly formatted date text.
value– 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.
<Field name=’ExpireDate’> <Display class=’DatePicker’> <Property name=’title’ value=’Set Password Expire date’/> <Property name=’format’= value=’iso’/> </Display> </Field>
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 Waveset from a file (such as users or configuration objects). This component supports all the properties that the Text component supports.
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’> <concat> <s><![CDATA[<div class="DashAlrtMsgTxt">]]></s> <ref>loginWarning</ref> <s><![CDATA[ <a href=’]]></s> <s>user/changePassword.jsp</s> <s><![CDATA[’>]]></s> <message name=’UI_USER_MAIN_CLICK_HERE_INTRO’/> <s><![CDATA[</a>]]></s> <message name=’UI_USER_MAIN_CLICK_HERE_REMAINDER’/> <s><![CDATA[</div>]]></s> </concat> </Property> </Display>
title– Specifies the title of the page. Can be a String or Message, but typically is a String.
postUrl– Specifies the URL that Waveset posts to when the main form is submitted.
messages– Indicates which informational messages to display.
comments– Indicates the special comments to include. This property is typically used by GenericEditForm and FormConverter when these methods catch exceptions.
focussedFieldName– Specifies the name of the first field to receive focus. Typically null. The value of this property is calculated as the first text field, or if no text fields, the first field.
activeControl– Specifies the name of the last known active form field. (String)
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:
alertType– Specifies the type of alert to display. This property determines the styles and images to use. Valid values are error, warning, success, and info. The value of this property defaults to info. This property is valid only for InlineAlert.
header– Specifies the title to display for the alert box. This can be either a string or a message object. This property is valid for InlineAlert or InlineAlert$AlertItem.
value– Specifies the alert message to display. This value can either be a string or a message object. This property is valid for InlineAlert or InlineAlert$AlertItem.
linkURL– Specifies an optional URL to display at the bottom of the alert. This property is valid for InlineAlert or InlineAlert$AlertItem.
linkText– Specifies the text for the linkURL. This can be either a string or a message object. This property is valid for InlineAlert or InlineAlert$AlertItem.
linkTitle– Specifies the title for the linkURL. This can be either a string or a message object. This property is valid for InlineAlert or InlineAlert$AlertItem.
<Field> <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.’/> </Display> </Field>
Define alertType only within the InlineAlert property. You can define other properties in the InlineAlert$AlertItems.
<Field> <Display class=’InlineAlert’> <Property name=’alertType’ value=’error’/> </Display> <Field> <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> </Field> <Field> <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.’/> </Display> </Field> </Field>
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.
If no padding is specified, the default padding is leftPad=2, rightPad=2.
<Field> <Display class=’Label’> <Property name=’title’ value=’Account ID’/> <Property name=’value’> <ref>waveset.accountId,/ref> </Property> </Display> </Field>
font– Specifies the font style. The value must be one of the styles defined in the styles/style.css file of the Waveset installation directory.
color– Specifies the label color. Use standard HTML color formatting (#xxxxxx) to specify the color value.
Places a link on the page.
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.
baseURLOption– (Optional) Specifies the prefix of the generated URL. This setting overrides the baseURL RequestState setting in cases where a different base URL is needed.
<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>
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’ name=’getOrganizationsDisplayNames’> <ref>:display.session</ref> <map> <s>filterVirtual</s> <o><Boolean>true</Boolean></o> <s>current</s> <list> <ref>original.orgParentName</ref> </list> <s>excluded</s> <list><ref>orgName</ref></list> </map> </invoke>
Renders a bulleted list of links, resembling a menu.
Renders an editable list of strings.
listTitle - (String) Specifies the label that Waveset places next to the ListEditor graphical representation.
pickListTitle - (String) Specifies the label to use on the picklist component.
valueMap - (Map) Specifies a map of display labels for the values in the list.
allowDuplicates - (Boolean) A value of true indicates that Waveset allows duplicates in the managed list.
allowTextEntry - (Boolean) A value of true indicates that Waveset displays a text entry box, along with an add button.
fixedWidth - (Boolean) A value of true indicates that the component should be of fixed width (same behavior as Multiselect component).
ordered - (Boolean) A value of true indicates that the order of values is important.
sorted - (Boolean) A value of true indicates that the values should be sorted in the pick list. If values are multivalued and not ordered, Waveset also sorts the value list.
pickValueMap - (List or Map) Specifies a map of display labels for the values in the pick list.
pickValues - (List) Specifies the available values in the picklist component. If null, the picklist is not shown.
height - (Integer) Specifiies preferred height.
width - (Integer) Specifies the preferred width. Can be used by the Container as a property of the table cell in which this item is rendered.
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’> <Boolean>true</Boolean> </Property> <Property name=’ordered’> <Boolean>true</Boolean> </Property> </Display> <Expansion> <ref>accounts[Sim1].Group</ref> </Expansion> </Field>
This code snippet creates a field where the customer can add groups to or remove them from a user.
This display class typically requires a List of Strings as input. To coerce a single String into a List of Strings:
<Expansion> <appendAll><ref>accounts[Sim1].Group</ref></appendAll> </Expansion>
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:
flat list– The list is expected to contain name/value pairs such that element 0 is a name, element 1 is a value, element 2 is a name.
map– The entries in the map are emitted in alphabetical order.
GenericObject– The object is flattened to and emitted as a map.
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.
If you are running Waveset 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:
allowedValues– Specifies the values associated with the left side of the multiselection box. This value must be a list of strings. Note: The <Constraints> element can be used to populate this box, but its use is deprecated.
availableTitle– Specifies the title of the available box.
class - Specifies the CSS class to use to style the MultiSelect buttons when the component is not rendered as an applet. Defaults to formbutton.
disabledclass - Specifies the CSS class to use to style the disabled MultiSelect buttons when the component not rendered as an applet. Defaults to formbutton.
displayCase– Maps each of the allowedValues to their uppercase or lowercase equivalents. Takes one of these two values: upper and lower.
height– Specifies the width of the selected box in pixels. The default value is 400.
noApplet– Specifies whether the MultiSelect component 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. See preceding note for information on using this option on systems running the Safari browser.
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.
selectedTitle– Specifies the title of the selected box.
sorted– Specifies that the values in both boxes will be sorted alphabetically.
typeSelectThreshold– (Available only when the noApplet property is set to true.) Controls whether a type-ahead select box appears underthe allowedValue list. When the number of entries in the left selectbox 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.
width– Specifies the width of the selected box in pixels. The default value is 150.
<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>
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.
<Field name=’attributes.accountLockExpiry.unit’> <Display class=’Radio’> <Property name=’noNewRow’ value=’true’/> <Property name=’labels’> <List> <String>UI_TASKS_XML_SCHED_MINUTES</String> <String>UI_TASKS_XML_SCHED_HOURS</String> <String>UI_TASKS_XML_SCHED_DAYS</String> <String>UI_TASKS_XML_SCHED_WEEKS</String> <String>UI_TASKS_XML_SCHED_MONTHS</String> </List> </Property> <Property name=’allowedValues’> <List> <String>minutes</String> <String>hours</String> <String>days</String> <String>weeks</String> <String>months</String> </List> </Property> </Display> </Field>
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.
<Field> <Display class=’SectionHead’> <Property name=’text’ value =’Calculated Fields’/> </Display> </Field>
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.
allowedOthers– When set, specifies that initial values that were not on the allowedValues list should be tolerated and silently added to the list.
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.
optionGroupMap– Allows the selector to render options in groups using the <optgroup> tag. Format the map such that the keys of the maps are the group labels, and the elements are lists of items to be selectable. (Values must be members of allowedValues in order to render.)
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.
<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>
Displays a regular text entry box.
Common properties for this display component are:
autocomplete– Specifies whether browsers should offer to store the user’s credentials on their computer. By default, this property is set to off, which prevents browers from storing this information. See SystemConfiguration Object in Oracle Waveset 8.1.1 Deployment Guide for information about enabling this feature on the Waveset login pages.
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.
notrim– Specifies whether text posted from the HTML form is trimmed. Set to true to not trim white space. To preserve white space, set this option.
noTranslate– When set to true, causes values that are message keys to be display as-is, rather than substituted. (Default is false.)
maxLength– Specifies the maximum length of the string that can be edited in the text box.
multiValued– Displays text boxes with Add and Remove buttons to add and remove values, when set to true.
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 this property is set 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 Save.
<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>
Displays a multi-line text entry box.
Properties for this display component are:
rows– Specifies the number of text area rows. (Integer)
columns– Specifies the number of text area columns. (Integer)
readOnly– Displays read-only text in the text entry box. When set to true, this component will not have a border. (Boolean)
format– Set to control how setValue() behaves and determine the type of object returned by getPostData(). (String)
sorted– Enables sorting of lines in the text area, when set to true. This feature is convenient when the area is used to display a list of selections, not free-form text. (Boolean)
noTrim– Specifies whether text posted from the HTML form is trimmed. The default is to trim white space. To preserve white space, set this value to true.
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.
It can be unwieldy to display many admin roles using the MultiSelect component (either the applet or HTML version). Waveset 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.
<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’> <appendAll> <new class=’com.waveset.object.AttributeCondition’> <s>hidden</s> <s>notEquals</s> <s>true</s> </new> <map> <s>onlyAssignedToCurrentSubject</s> <Boolean>true</Boolean> </map> </appendAll> </Property> <Property name=’selectorFixedInclusions’> <appendAll> <ref>waveset.original.adminRoles</ref> </appendAll> </Property> </FieldRef> </Field>
From the Identity Manager IDE, open the Administrator Library UserForm object.
Add the following code to this form:
<Include> <ObjectRef type=’UserForm’ name=’Scalable Selection Library’/> </Include>
Select the accounts[Lighthouse].adminRoles field within the AdministratorFields field.
Replace the entire accounts[Lighthouse].adminRoles with the following reference:
Save the object.
When you subsequently edit a user and select the Security tab, Waveset 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.