JWL JavaScript Behaviors

JWL JavaScriptâ„¢ Behaviors add event handlers which perform common functions to a tag. For example, you can add a JWL Behavior to the onblur handler of an input tag that validates the value of the tag when the onblur event is fired.

Using a behavior

When a behavior is invoked, it runs one or more JWL Actions along with any provided JavaScript. A JWL Action is a predefined block of JavaScript such as "disable a field", "hide a field", "show an alert box". In addition, some behaviors (notably ones that deal with validation) can also toggle which CSS classes are associated with a field (as well as executing functions and actions).

JWL Behaviors add to an object's event handler as opposed to replacing it. For example, you can attach a JavaScript function to the onblur handler of an object and then attach a behavior to the onblur function as well. Both the event handler and the behavior will be run when the event is fired. The sequencing of how event handlers and behaviors and the action(s) performed by a behavior are fired is described below.

To use a behavior:
  1. Add the tag the behavior applies to in the page. For example:
    <input id="form1:text1" type="text" value="fish" class="inputText" />
  2. Attach the behavior to the DOM object. For example:
    <script>
        hX_5.addBehavior("form1:text1", "onfocus", new hX_5.JSFBehaviorGeneric("action:show", "target:form1:tooltip1"));
    </script>
The behavior is now attached to the object -- when the onfocus event fires on the object, the JWL Generic Behavior will be invoked which causes form1:tootop1 to be displayed.

hx calls to create and find a behavior

Each behavior is constructed using a Javascript constructor and added to the page via an addBehavior call.

hX_5.addBehavior("id", "eventname", new hX_5.JSFBehaviorName(attributes)); where

id

The ID of the HTML tag to which the behavior is attached. To attach to the body tag, use #body and for the document use #document.

eventname

The HTML eventname that invokes the behavior. For example, onclick or onkeydown. Each behavior supports only some HTML event names (for example, the mouseclick behavior can't be bound to a keyboard event). In some cases, the behavior needs to be bound to multiple HTML events in which case a "pseudo" event name is used. For example, the mouseclick behavior is bound to multiple events so the eventname is "onmouse".

name

The name of the JSF Component.

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".

Note: Multiple behaviors may be attached to a DOM object.

To get a specific behavior object:

var o = hX_5.getBehaviorById("id", "name", "eventname"); where

id

The ID of the HTML tag to which the behavior is attached. To attach to the body tag, use #body and for the document use #document.

name

The name of the JSF Component.

eventname

The HTML eventname that invokes the behavior. For example, onclick or onkeydown. Each behavior supports only some HTML event names (for example, the mouseclick behavior can't be bound to a keyboard event). In some cases, the behavior needs to be bound to multiple HTML events in which case a "pseudo" event name is used. For example, the mouseclick behavior is bound to multiple events so the eventname is "onmouse".

returns

A JavaScript object of the type of the converter (Number, DateTime or String). If the conversion cannot be done, null is returned and lastError is set.

To get all behavior objects attached to a DOM object:

var a = hX_5.getBehaviorsById("id"); where

id

The ID of the HTML tag to which the behavior is attached. To attach to the body tag, use #body and for the document use #document.

returns

A JavaScript object of the type of the converter (Number, DateTime or String). If the conversion cannot be done, null is returned and lastError is set.

Common API calls on a behavior

To change an attribute of a behavior:

b.setAttribute("arg"); where

b

A behavior object.

arg

A JSF attribute/value string.

To get an attribute of a behavior:

var x = b.getAttribute("argname"); where

b

A behavior object.

argname

A string containing the name of the attribute.

returns

A JavaScript object of the type of the converter (Number, DateTime or String). If the conversion cannot be done, null is returned and lastError is set.

Sequencing of Execution

If a behavior can execute a user-supplied JavaScript function, the function is executed before any JWL Actions. If the function returns false, the actions are not executed. Similarly, if the function returns false, any CSS styles are not applied. Actions behave similarly -- if an action returns false, any additional actions are not performed.

If a JavaScript event handler is provided in addition to the behavior (e.g., script is attached to an onblur event handler and a behavior is attached to the same onblur event handler), the supplied JavaScript will either be executed first or last depending on the event. If the JavaScript event handler runs first and it returns false, the behavior will not be run.

Table 1. Behavior objects

Behavior

Description

JSFBehaviorGeneric Bind a function/action to any HTML event handler
JSFBehaviorAjaxGet Defines how to retrieve/parse content asynchronously from the same originating page.
JSFBehaviorAjaxGetExternal Defines how to retrieve/parse content asynchronously from a different URL than the originating URL.
JSFBehaviorAjaxSubmit Defines how to submit/retrieve/parse content asynchronously to/from the originating page.
JSFBehaviorAssist Enable input assist (character-by-character prompting) on an HTML input field
JSFBehaviorFocus When a page loads, set initial focus to a control in the page
JSFBehaviorKeybind Bind a function/action to a function/control key
JSFBehaviorMouseclick Bind a function/action to the right mouse button or all mouse buttons
JSFBehaviorTrack Enable field/cursor tracking so that when a form is submitted, information about where the focus/cursor last was is transmitted as part of the submit
JSFBehaviorTypeahead Add typeahead support to an input field.
JSFBehaviorValidate Validate that the value of an HTML input or select tag is correct and display error if not
JSFBehaviorRowAction Internal use only. Add a row action to a row in a h:dataTable
JSFBehaviorRowCategory Internal use only. Add a row category behavior to a row in a h:dataTable
JSFBehaviorRowEditSave Internal use only. Add save behavior to an editable row in a h:dataTable
JSFBehaviorRowEditShowHide Internal use only. Add show/hide (edit area) behavior to an editable row in a h:dataTable
JSFBehaviorPager Internal use only. Support paging behavior in a h:dataTable
JSFBehaviorHS Internal use only. Implementation of the client-side logic for the <hx:panelActionbar>
JSFBehaviorAlert Deprecated. Display an alert/confirm dialog box when an event is triggered (use JSFBehaviorGeneric instead)
Related concepts
JSF Widget Library (JWL)

Feedback