Assist behavior

Enable "input assist" on a field. When the field gets focus, prompt characters are displayed in the field indicating where a user may type. As the user types, the cursor is managed so it is always positioned where a user may type. If a user enters an invalid character for that position, the character is ignored.

For details on how input assist works for each data type, refer to JSF Assist.

Enables "input assist" on a field. Input assist currently supports three kinds of assist:
  • When the field gets focus, prompt characters are displayed in the field indicating where a user may type. As the user types, the cursor is managed so it is always positioned where a user may type. If a user enters an invalid character for that position, the character is ignored. When focus leaves the field, it is reformatted without the prompt characters.
  • When the field is "full", focus advances to the next field (or the form is submitted).
  • When the field gets focus, the state of the IME (Input Method Editor) used for entering characters in some Asian languages can be toggled.

To enable prompting, a converter must be provided (that is, the field must be a number, a date/time or a mask). The pattern/format defined by the converter determines how prompting works for the field. The details of how prompt characters are handled, how input is restricted, how the cursor works, etc. is described in the section on JSF Assist.

Auto-tab can be turned on for the field independently from prompting. If auto-tab is enabled, a converter is not required though it is recommended if the field is a number, date/time or string. If both prompting and auto-tab are turned on, the cursor is advanced when the last prompt character (the rightmost character) is entered. If prompting is not enabled, the cursor advances when the "maximum number of characters" are entered. The calculation of this value is rather complex. If a converter is not provided, the maximum number of characters should be specified as the value of the auto-tab attribute. If the value is not provided, the maximum-length HTML attribute of the field is examined and the converter (if present) is examined and from these two values something "sensible" is constructed. For date/times and numbers this value may be quite large. For example, for a date/time it will take into account the largest possible "names" that might be entered (e.g., "December") and for numbers it will take into account negative signs, the maximum number of thousands separators, etc. If necessary, the maximum-length HTML attribute of the field is adjusted to reflect the computed value.

Instead of advancing when the maximum number of characters are entered, auto-submit can be set to modify the behavior of the auto-tab (auto-tab must be set for auto-submit to work). In this case, when the maximum number of characters are entered, the form containing the field is submitted. This feature is deprecated (it is not Section 508 compliant). It is available for special cases where "antique" UI paradigms are being used in the page.

If the ime-mode attribute is provided, it works exactly like the CSS ime-mode property in IE. In IE (only), when the field receives focus, the IME is set to the specified state (e.g., it's enabled). Because this is exactly the same as specifying the ime-mode property on the field via CSS, use of this feature is deprecated.

JSF tags that emit the component

<hx:inputHelperAssist>

Base HTML

Use with <input type="text"> only.

JavaScriptâ„¢ constructor

hX_5.addBehavior("id", "oninput", new hX_5.JSFBehaviorAssist(attributes)); where

id

The ID of the HTML tag to which the component is attached.

attributes

Comma separated list of attributes where each attribute is a quoted string consisting of the attribute name and value separated by a colon, for example "label:MyLabel".

Supported events

Event

Description

oninput

Note the use of the special event name. The behavior modifies all keyboard event handlers as well as focus and blur.

Attributes

Table 1. Assist behavior attributes

Attribute name

Description

converter

The ID of a converter that has already been constructed. The converter describes the format of the value in the input field.

validator

The ID of a validator that has already been constructed. If the validator is supplied, the constraints described in the validator are used limit the values a user can pick.

prompt-char

The character to use as the prompt character (shows users where to type). Space is a legal prompt character. Care must be taken that the prompt character makes sense with the pattern, for example, "." is not a good prompt character for a number. Not used if a converter is not provided.

auto-tab

If present, the maximum number of characters that can be entered. After the maximum number of characters are entered, focus will advance to the next field. For date/time and masked fields, a value is not required (it's computed from the pattern). For numbers, a value is optional (if not provided, the maximum size of the pattern is used). If no converter is provided, a value must be provided.

auto-submit

If auto-tab is set for the field, changes the behavior of the auto-tab from advancing to the next field to submitting the form that contains the field. By default, the submit is done using the first submit button found in the form. To have the submit use a different button provide the ID of the button as the value of the attribute. See the SUBMIT actions for a description of how auto-submit determines how to submit the form.

ime-mode

If provided, when the field receives focus, the ime-mode is set to the specified state. Only works in IE. Use is deprecated, instead use CSS to do this.

Sequencing

Runs after any other handlers provided for the event. Stops the event.

API calls

Table 2. Assist behavior API calls

API call

Description

object = setAttribute(attribute)

Sets an attribute or changes its value (if it was set previously).

string = getAttribute(attribute-name)

Retrieves the current value of an attribute.

Limitations

Example code

Enable auto-tabbing after five characters on a field:

hX.addBehavior ("form1:text1", "oninput", new hX.JSFBehaviorAssist("auto-tab:5"));

Enable prompting using * as the prompt character and autotabbing on a number field:

hX.addConverter("2", new hX.NumberConverter( "pattern:US$ ###,##0.00;( US$ ###,##0.00 )"));
hX.addBehavior ("form1:text2", "oninput", new hX.JSFBehaviorAssist("converter:2", "auto-tab", 
                  "prompt-char:*"));

Enable prompting using space as the prompt character and autotabbing on a date/time field. Include the validator for the field.

hX.addConverter("3", new hX.DateTimeConverter("strict:1", "format:MM/dd/yyyy"));
hX.addValidator("C", new hX.DateTimeValidator( "required", "min-bound:20040101120000",  
                  "max-bound:20041001120000"));
hX.addBehavior ("form1:text3", "oninput", new hX.JSFBehaviorAssist("validator:C", 
                  "converter:3", "auto-tab", "prompt-char: "));

Feedback