Form Item

Form Item

Defines an item displayed in a hx:panelFormBox. Each item defines (at most) a label, content (an input field), an informational message, and an error message as well as rules for how the elements are coordinated. The panelFormBox organizes formItem contents into a coordinated display of fields.

Properties and All Attributes views

The Properties view for a component shows the most common set of attributes you can set on a component, and, depending on the component, you might also see options for adding controls, actions, or other components. To open the Properties view, click

Window | Show View | Properties.

These common attributes for the form item component display on the hx:FormItem, Accessibility and Styles tabs in the Properties view. See the Form Item attributes table for a list of attributes.

The All Attributes view shows a table of all the attributes you can set on a component, which includes those attributes you can access from the Properties view. To switch to the All Attributes view, click the
All Attributes icon in the upper right corner of the Properties view.

Table 1. Panel - Form Box attributes

Attribute name

Description

accesskey

Specifies a single keyboard key as an access key. Pressing the specified access key at runtime gives focus to this component. Pressing ALT plus the specified access key at runtime gives focus to this component (or executes the component if it is a kind of button).

binding

An expression that binds the component's instance (usually a user interface component) to a bean property (usually in the backing file).

errorText

Text to display when the value of the field in the formItem is not valid. If omitted, a "system provided" error text is used when the field is not valid. A field is validated on the server when the form containing the formItem is submitted. If any field's value is invalid, the page is redisplayed with the errorText displayed for the formItem (subject to the showHelp attribute). If an errorText is provided, the supplied text is displayed. If errorText is not provided, the message (h:message) generated on the server for the field is displayed. Control of where the text is displayed is specified on the panelFormBox. Control of whether the text is displayed is controlled by the showHelp attribute described below. In addition, a field can have client-side validation enabled (client-side validation is always enabled if the field is required). When a field loses focus (onblur fires), client-side validation is run. If the field fails validation, the error is displayed. If an errorText is provided, the supplied text is displayed. If errorText is not provided, an appropriate message from the hxclient string resource file is displayed. By supplying an errorText, a consistent error message is displayed when a field is invalid -- regardless of how (where) the error is flagged. Whether the error is flagged by client-side validation or server-side validation, the same error is displayed (in the same location).

escape

Specifies whether to escape HTML formatting (False) or to render HTML tags as HTML (True).

id

Assigns a name to a component. Should be a unique name within a JSP.

infoText

Additional informational or help text to be displayed with the item. For example, it can provide details on what the user should enter or it could describe the units of measure for the field. Control of where the text is displayed is specified on the panelFormBox. Control of whether the text is displayed is controlled by the showHelp attribute described below. As with errorText and label, HTML may be embedded in the string.

label

Specifies the displayed text.

releaseMargin

The contents of the formItems in a panel are aligned in table columns based on the labelPosition and helpPosition attributes of the panel. For example, all labels are put in one column and all contents in an adjacent column. Setting releaseMargin "releases" this item from this rule. When releaseMargin is set, the contents of this formItem are wrapped in a sub-table inserted in the panel's table. The contents of the subtable thus have an independent alignment. releaseMargin is often used when one item has a label (or content) that is significantly wider or narrower than the other items. By "releasing" this item, this item's elements can be aligned differently without forcing all other items in the panel to become "too wide". Note that releaseMargin is only meaningful if labels and/or messages are displayed to the left/right of the field. It has little effect if the labels and/or messages are displayed over/under the field.

rendered

Can be set to true or false:

false - Component will not be rendered to the browser at runtime.

true - Component will get rendered. This is the default value.

showHelp

Determines how (when) the infoText and errorText are displayed for this item. If Always the info text is always displayed unless there is an error in which case the error is displayed in its place. If As-needed the info text is displayed when the field has focus (unless there is an error). The error is always displayed if there is an error. If Info the info text is always displayed. The error text is never displayed. If Error the info text is never displayed. The error text is displayed if there is an error. If None neither text is ever displayed.

style

Specifies CSS style information for the component (for example, style="font-size : 8pt ; color : red"). Defines the properties (such as font and color) of the selected component. This may be done manually, or by clicking the button and selecting the desired properties from within the window.

styleClass

Space-separated list of CSS style classes to be applied when this element is rendered. This value must be passed through as the class attribute on generated markup. Defines the classes (such as style sheets) of the selected component. This may be done manually, or by clicking the button and selecting the desired Classes from within the window.

title

Specifies the title text, shown in browser as a tooltip at runtime. Used by a browser as the alternative text of a component if the alternative text is not specified.

Attribute name	Description
accesskey	Specifies a single keyboard key as an access key. Pressing the specified access key at runtime gives focus to this component. Pressing ALT plus the specified access key at runtime gives focus to this component (or executes the component if it is a kind of button).
binding	An expression that binds the component's instance (usually a user interface component) to a bean property (usually in the backing file).
errorText	Text to display when the value of the field in the formItem is not valid. If omitted, a "system provided" error text is used when the field is not valid. A field is validated on the server when the form containing the formItem is submitted. If any field's value is invalid, the page is redisplayed with the errorText displayed for the formItem (subject to the showHelp attribute). If an errorText is provided, the supplied text is displayed. If errorText is not provided, the message (h:message) generated on the server for the field is displayed. Control of where the text is displayed is specified on the panelFormBox. Control of whether the text is displayed is controlled by the showHelp attribute described below. In addition, a field can have client-side validation enabled (client-side validation is always enabled if the field is required). When a field loses focus (onblur fires), client-side validation is run. If the field fails validation, the error is displayed. If an errorText is provided, the supplied text is displayed. If errorText is not provided, an appropriate message from the hxclient string resource file is displayed. By supplying an errorText, a consistent error message is displayed when a field is invalid -- regardless of how (where) the error is flagged. Whether the error is flagged by client-side validation or server-side validation, the same error is displayed (in the same location).
escape	Specifies whether to escape HTML formatting (False) or to render HTML tags as HTML (True).
id	Assigns a name to a component. Should be a unique name within a JSP.
infoText	Additional informational or help text to be displayed with the item. For example, it can provide details on what the user should enter or it could describe the units of measure for the field. Control of where the text is displayed is specified on the panelFormBox. Control of whether the text is displayed is controlled by the showHelp attribute described below. As with errorText and label, HTML may be embedded in the string.
label	Specifies the displayed text.
releaseMargin	The contents of the formItems in a panel are aligned in table columns based on the labelPosition and helpPosition attributes of the panel. For example, all labels are put in one column and all contents in an adjacent column. Setting releaseMargin "releases" this item from this rule. When releaseMargin is set, the contents of this formItem are wrapped in a sub-table inserted in the panel's table. The contents of the subtable thus have an independent alignment. releaseMargin is often used when one item has a label (or content) that is significantly wider or narrower than the other items. By "releasing" this item, this item's elements can be aligned differently without forcing all other items in the panel to become "too wide". Note that releaseMargin is only meaningful if labels and/or messages are displayed to the left/right of the field. It has little effect if the labels and/or messages are displayed over/under the field.
rendered	Can be set to true or false: false - Component will not be rendered to the browser at runtime. true - Component will get rendered. This is the default value.
showHelp	Determines how (when) the infoText and errorText are displayed for this item. If Always the info text is always displayed unless there is an error in which case the error is displayed in its place. If As-needed the info text is displayed when the field has focus (unless there is an error). The error is always displayed if there is an error. If Info the info text is always displayed. The error text is never displayed. If Error the info text is never displayed. The error text is displayed if there is an error. If None neither text is ever displayed.
style	Specifies CSS style information for the component (for example, style="font-size : 8pt ; color : red"). Defines the properties (such as font and color) of the selected component. This may be done manually, or by clicking the button and selecting the desired properties from within the window.
styleClass	Space-separated list of CSS style classes to be applied when this element is rendered. This value must be passed through as the class attribute on generated markup. Defines the classes (such as style sheets) of the selected component. This may be done manually, or by clicking the button and selecting the desired Classes from within the window.
title	Specifies the title text, shown in browser as a tooltip at runtime. Used by a browser as the alternative text of a component if the alternative text is not specified.