You can customize a form to make it more user-friendly, change its display characteristics, or include logic for processing field data.
The basic steps for customizing any form in the Waveset system include:
Selecting a form to customize. Describes how to identify which form to customize.
Editing and saving the form. Presents basic information about modifying the default end user and administrator forms shipped with the product.
Testing your changes. Suggests guidelines for testing your changes before loading them into your production environment and turning on error logging.
When you edit a form, you typically perform the following tasks:
Add and remove fields in the form. Typical tasks include removing some default fields or adding additional fields that have been customized for your environment.
Define how a field is displayed within a form. This requires using a library of HTML components shipped with Waveset. For information on editing a field’s display characteristics, see the section titled Field Display Properties.
Set the logical expressions that define the field’s value. To do this, you must create logical expressions using the XPRESS language. For information on working with XPRESS, see Chapter 5, XPRESS Language.
Property |
Description |
---|---|
Title |
Specifies the text that displays adjacent to the form field. |
Class |
Identifies the HTML display class to which the element belongs. |
Required |
Identifies whether the element is required to process the form. This field must have a non-null value upon submission. When set, results in a red asterisk appearing to the right of the field. Message text at the bottom of the form indicates that red asterisk denotes fields that must have a value for submission to proceed. |
Action |
When set, a change causes the page to refresh any Select or MultiSelect controls. In the Waveset Administrator Interface, this causes the underlying view to be refreshed. Role selection exemplifies this behavior. When a new role is selected in the Tabbed User Form, the view is refreshed to reflect the resources that are assigned through that role during that edit session. After the view has been refreshed, resource account attributes on those newly assigned resources can be explicitly set. |
No New Row |
Used strictly for form layout. When true, forces the field to appear to the right of the proceeding field. For example, Name fields are examples where this is useful, where it is desirable to allow the user to enter the last name, first name, and middle initial from right to left, rather than down the page. |
Hidden |
Indicates the field should not be visible to the user. The field is typically used to set attribute values that are calculated form other fields, such as constructing the full name from a concatenation of first and last name. |
Title |
Controls the character width of the control (text boxes). |
Class |
Specifies the character width of the control buffer (text boxes). Characters scroll if the user types in a string greater than the value specified by the size property. |
Required |
Identifies the name for this form field, typically a path expression in to the view that is used with this form. |
Set the characteristics in the following table from the Main tab view.
Table 2–3 Characteristics Set from Main Tab View
Field |
Description |
---|---|
Name |
Enter the name for this field. A field name is typically a path expression into the view that is being used with this form. All fields that display as editing components (such as text boxes, checkboxes, and selects) must have a name that specifies a view path. Fields that do not display as editing components (such as SectionHead and Javascript) do not require names. However, you can give non-editing fields names if they need to be referenced by another form through a Field reference. |
Title |
Enter a title for the field. This title displays adjacent to the field on the form. Select the data type of this element from the drop-down menu immediately adjacent to this field. To edit the text displayed in this field, click the adjacent Edit button. |
Sub Title |
(Optional) Specify text that Waveset can display beneath the form title. Select the data type of this element from the drop-down menu immediately adjacent to this field. To edit the text displayed in this field, click the adjacent Edit button. |
Help Catalog |
Enter the help key that associates guidance help with the field. This value is the name of an entry in an associated help catalog specified by the form. Specifying a help key causes an icon to appear to the left of the field. Moving the mouse over the icon causes the text referenced in the help catalog to display. |
Base Context |
(Not typically used in standard user forms.) Enter the base context to avoid the need to specify the full path in every field. Base context identifies the underlying Map (specifically, com.waveset.object.Genericobject and is typically named user or userview. In the Waveset Administrator Interface, the editing context is user, so the base context reference is left blank. In forms launched from manual actions, such as approvals, the workflow context is the context of the form. |
Options |
Select one or more display options for the field: Required– Identifies whether the element is required to process the form. This field must have a non-null value upon submission. When set, results in a red asterisk appearing to the right of the field. Message text at the bottom of the form indicates that red asterisk denotes fields that must have a value for submission to proceed. Button– Causes the field to display in a single, horizontal row at the bottom of the form. Otherwise, it displays on the next line of the form. This is most set with fields that use the display class Button. Action– When set, a change causes the page to refresh any Select or MultiSelect controls. In the Waveset Administrator Interface, this causes the underlying view to be refreshed. Role selection exemplifies this behavior. When a new role is selected in the Tabbed User Form, the view is refreshed to reflect the resources that are assigned through that role during that edit session. After the view has been refreshed, resource account attributes on those newly assigned resources can be explicitly set. Library– Indicates that a field should only display when it is referenced, rather than when it is declared. This is useful when the order in which fields are evaluated on a form may differ from the order in which they are displayed to the user. |
Default |
Specify an expression to calculate a default value for the field. The default expression is called before the form is displayed if the current value for this field is null. |
Derivation |
Specify an expression to calculate the value of a field before it is displayed. It is similar to a Default expression, except that it is evaluated even if the current field value is non-null. The derivation expression is evaluated before the form is first displayed, and then again each time the form is refreshed. |
Validation |
Specify logic to determine whether a value entered in a form is valid. Validation expressions return null to indicate success, or a string containing a readable error message to indicate failure |
Expansion |
Specify an expression to calculate the value of the field after the form has been submitted. Expansion expressions are typically used with fields that are also marked hidden. Since hidden fields are not directly editable by the user, the value can be calculated with an Expansion expression. See Hiding Fields. |
Disable |
Specify an expression that, if evaluated to true, disables the field and any of its nested fields. A disabled field does not display on the form. It is used to determine if a user has a specific type of resource. If the user does, the form then displays the appropriate fields for that resource. |
Display Class |
Identify the HTML component class used to render this form component in the browser. By default, the Display Class selection is EditForm. If the form is a link form (such as the End User menu), then select LinkForm from the Display Class options. See the HTML Display Class table in Chapter 7, HTML Display Components |
size |
Controls the character width of the control (text boxes). |
maxLength |
Specify the maximum number of characters for this element. |
A field name is often a path expression into the view that is being used with this form, and is typically associated with a particular attribute on a resource. To browse a list of resources and their attributes, click Browse resources. The Browse resource dialog opens, displaying an expandable tree of resource types. Click the name of the resource type to display a list of resource instances and the names of their attributes. To use the name of resource attribute as your new form field name, click the resource attribute name, then click OK. This inserts the attribute name into the Name field.
HTML Component |
Purpose |
---|---|
Apple |
Inserts an applet reference into the page. |
BackLink |
Displays a link that returns to the previous page. |
BorderedPanel |
A container that organizes its components into 5 regions: north, south, east, west, and center. |
Button |
Displays a button. |
ButtonRow |
A container that arranges its components in a horizontal row with padding in between. Typically used to display a row of Button components |
CheckBox |
Arranges its components in a horizontal row with padding in between. Typically used to display a row of Button components. (Container) |
DatePicker |
Displays a calendar icon on the page. The user can click this icon to select a calendar date and populate a page field. |
EditForm |
The default container for forms. Displays component titles in one column and components in another. Each row has an alternating gray or white background. |
FileUpload |
Variant of the Text component used for specifying the name of a file to be uploaded. |
Hidden |
A component used to include data into the HTML page that is not displayed |
Html |
Inserts pre-formatted HTML into the page. |
Javascript |
Defines JavaScript functions. |
Label |
Displays read-only text. |
Link |
Places a link on the page. |
LinkForm |
Places components in a bulleted vertical list with no titles. Typically used for pages that contain lists of Link components. Alternative to EditForm container. (Container) |
MultiSelect |
Displays a multiselection 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. |
NameValueTable |
Displays a list of name/value pairs in a simple table with a beige background. |
Panel |
Organizes its components in either a horizontal or vertical line.(Container) |
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. |
SectionHead |
Displays a section heading. These are recognized by the EditForm container to and are rendered in bold text that spans both the title and component columns. |
Select |
Displays a single-selection list box. |
SimpleTable |
Arranges components in a simple grid with a row of column titles. |
SubTitle |
Identifies the text that displays below the form title. |
Text |
Displays read-only text. |
TextArea |
Places a link on the page. |
Title |
Identifies the text that displays at the top of the form. |
Table 2–5 Form Elements
Form Element |
Description |
---|---|
Name |
Enter the name for this field. A field name is typically a path expression into the view that is being used with this form. All fields that display as editing components (such as text boxes, checkboxes, and selects) must have a name that specifies a view path. Fields that do not display as editing components (such as SectionHead and Javascript) do not require names. However, you can give non-editing fields names if they need to be referenced by another form through a Field reference. |
Title |
Enter a title for the field. This title displays adjacent to the field on the form. Select the data type of this element from the drop-down menu immediately adjacent to this field. To edit the text displayed in this field, click the adjacent Edit button. |
Help Key |
Enter the help key that associates guidance help with the field. This value is the name of an entry in an associated help catalog specified by the form. Specifying a help key causes an icon to appear to the left of the field. Moving the mouse over the icon causes the text referenced in the help catalog to display. |
Options |
Select one or more display options for the field: Required– An entry or selection in this field is required to process the form. Button– Causes the field to display in a single, horizontal row at the bottom of the form. Otherwise, it displays on the next line of the form. This is most set with fields that use the display class Button. Action– When set, a change causes the page to refresh any Select or MultiSelect controls. In the Waveset Administrator Interface, this causes the underlying view to be refreshed. Role selection exemplifies this behavior. When a new role is selected in the Tabbed User Form, the view is refreshed to reflect the resources that are assigned through that role during that edit session. After the view has been refreshed, resource account attributes on those newly assigned resources can be explicitly set. Library– Indicates that a field should only display when it is referenced, rather than when it is declared. This is useful when the order in which fields are evaluated on a form may differ from the order in which they are displayed to the user. |
Default |
Specify an expression to calculate a default value for the field. The default expression is called before the form is displayed if the current value for this field is null. |
Derivation |
Specify an expression to calculate the value of a field before it is displayed. It is similar to a Default expression, except that it is evaluated even if the current field value is non-null. The derivation expression is evaluated before the form is first displayed, and then again each time the form is refreshed. |
Validation |
Specify logic to determine whether a value entered in a form is valid. Validation expressions return null to indicate success, or a string containing a readable error message to indicate failure. Validation rules are evaluated only when a form is submitted, not after each refresh or recalculate. |
Expansion |
Specify an expression to calculate the value of the field after the form has been submitted. Expansion expressions are typically used with fields that are also marked hidden. Since hidden fields are not directly editable by the user, the value can be calculated with an Expansion expression. |
Disable |
Specify an expression that, if evaluated to true, disables the field and any of its nested fields. A disabled field does not display on the form. It is used to determine if a user has a specific type of resource. If the user does, the form then displays the appropriate fields for that resource. |
Display Class |
Identifies the HTML component class used to render this form component in the browser. By default, the Display Class selection is EditForm. If the form is a link form (such as the End User menu), then select LinkForm from the Display Class options. See the HTML Display Class table in Chapter 7, HTML Display Components |
value |
Specifies the property attribute. Typically is a string. |
Variable |
Waveset assigns a scope to all <Variable> elements when the element is declared. If you do not assign a value to the scope attribute, Waveset assigns it a value of local, which means that the variable can be accessed only within the XPRESS section that it is declared in. Additional Variable attributes that define scope include:
|
maxLength |
Specifies the maximum number of characters for this element. |
Table 2–6 Default Services in Forms Toolbox
Service |
Description |
---|---|
Text |
Displays a regular text entry box. |
Secret Text |
Displays text as asterisks (*). Typically used for encrypted data like passwords |
Select |
Displays a single-selection list box. Values for the list box must be supplied by the allowedValues property. |
MultiSelect |
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. |
Checkbox |
Displays a checkbox. When checked, the box represents a value of true. An unselected box represents a false value. |
Label |
Displays a multi-line text entry box |
TextArea |
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. |
Radio |
Places a link on the page. |
Link |
Displays a button. |
Button |
Refers to a variable that is defined by the view that is used with this form. |
accountId |
Displays a multi-line text entry box |