AJAX external request behavior

Replaces the content of a "panel" tag in the page with content from a different page. The content is retrieved using an AJAX get (sub)request so that the entire page is not redrawn when the additional content is retrieved.

JSF tags that emit the component

<hx:ajaxExternalRequest>

Base HTML

Invoked only from a JWL GET action which is part of a behavior (for example, a generic behavior) attached to any HTML tag that supports event handlers. The target of the GET must be the ID of the panel that contains (or is the target of) this behavior.

JavaScript constructor

hX_5.addBehavior("id", "onget", new hX_5.JSFBehaviorAjaxGetExternal(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

onget

Note the use of the special event name. This is required.

Attributes

Table 1.

Attribute name

Description

href

The URL of the page from which content is to be retrieved. If omitted, content will be retrieved from the current (originating) page.

hreflang

The language of the page that is retrieved (the page that the link resolves to). This is advisory only (most browsers ignore the attribute). Specified as an ISO-standard language abbreviation code. For example, "en" for English, "en-US" for American English, "fr" for French, "de" for German.

charset

The (preferred) character encoding of page that is retrieved (the page the link resolves to).

source

The ID of a tag in the targeted URL whose content will replace the content of the container this component is associated with. If not specified or if the ID is not found in the page referenced by the URL, the ID of container is used. If this ID is not found in the page referenced by the URL, the body content is used.

title

While a request is in progress, the title is assigned to the panel's primary tag (for example, a div) and to the "temporary tabstop" assigned to the panel. This shows as both a tooltip if you mouse over the panel and is available to screen readers.

progress-actions

While the request is in progress, the JWL action(s) to apply to the panel. Currently the only supported action is LOCKED.

params

A semi-colon separated list of parameter names. When the page is retrieved, the URL will be encoded to include these parameter names and the corresponding values as identified by param-fields.

param-fields

If params is provided, this is a parallel list of identifiers. The value of the field identified by the ID will be encoded in the URL as the value of the param name. The size of the lists param and param-fields must be the same. The param names are usually the undecorated ids of a field while the param-field that corresponds to it is usually the "decorated" id of a field. For example, if you want to encode the value of the field form1:text1 you shoul use text1 as the param and form1:text1 as the param-fields. This will result in text1=value being encoded on the URL where value is the current field of the field form1:text1.

on-start

Before the request is sent, this JavaScriptâ„¢ function is executed. It has no arguments. If it returns false execution is halted. This function can be used (in conjunction with oncomplete to customize what is displayed while the request is in progress.

on-error

If a request fails/times out, this JavaScript is executed. The signature is (thisObj, thisError) where thisObj points to the panel and thisError is a string that describes the error.

on-complete

If a request succeeds, after the content of the panel is replaced, this JavaScript is executed. The function has no meaningful arguments.

on-start

Before the request is sent, this JavaScript function is executed. It has no arguments. If it returns false execution is halted. This function can be used (in conjunction with oncomplete to customize what is displayed while the request is in progress.

Sequencing

Runs when the "GET" is issued. Does not stop the event (a "STOP" action should be encoded in the originating behavior).

API calls

Table 2. AJAX external request 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.

Example code

Add AJAX retrieval to a page ccontainging a panel with the ID "form1:panelHelp". Encodes the value of the field "form1:lookUpText" as a parameter named "lookupText" whenever ta request is made to retrieve content.

hX.addBehavior("form1:panelHelp", "onget", new hX.JSFBehaviorAjaxGetExternal("on-error:return doError(this, event);", 
    "source:form1:panelHelp", "params:lookUpText", "param-fields:form1:lookUpText", "on-start:return doPrep(this, event);", 
    "href:JWL3-TEST-AJAX-External1-source1.jsp"));

Feedback