13.3 Using Ajax with Facelets

As mentioned in the previous section, JavaServer Faces technology supports Ajax by using a built-in JavaScript resource library that is provided as part of the JavaServer Faces core libraries. This built-in Ajax resource can be used in JavaServer Faces web applications in one of the following ways.

By using the f:ajax tag along with another standard component in a Facelets application. This method adds Ajax functionality to any UI component without additional coding and configuration.
By using the JavaScript API method jsf.ajax.request() directly within the Facelets application. This method provides direct access to Ajax methods and allows customized control of component behavior.

13.3.1 Using the f:ajax Tag

The f:ajax tag is a JavaServer Faces core tag that provides Ajax functionality to any regular UI component when used in conjunction with that component. In the following example, Ajax behavior is added to an input component by including the f:ajax core tag:

<h:inputText value="#{bean.message}">
    <f:ajax />
</h:inputText>

In this example, although Ajax is enabled, the other attributes of the f:ajax tag are not defined. If an event is not defined, the default action for the component is performed. For the inputText component, when no event attribute is specified, the default event is valueChange. Table 13-1 lists the attributes of the f:ajax tag and their default actions.

Table 13-1 Attributes of the f:ajax Tag

Name	Type	Description
`disabled`	`javax.el.ValueExpression` that evaluates to a `Boolean`	A `Boolean` value that identifies the tag status. A value of `true` indicates that the Ajax behavior should not be rendered. A value of `false` indicates that the Ajax behavior should be rendered. The default value is `false`.
`event`	`javax.el.ValueExpression` that evaluates to a `String`	A `String` that identifies the type of event to which the Ajax action will apply. If specified, it must be one of the events supported by the component. If not specified, the default event (the event that triggers the Ajax request) is determined for the component. The default event is `action` for `javax.faces.component.ActionSource` components and `valueChange` for `javax.faces.component.EditableValueHolder` components.
`execute`	`javax.el.ValueExpression` that evaluates to an `Object`	A `Collection` that identifies a list of components to be executed on the server. If a literal is specified, it must be a space-delimited `String` of component identifiers and/or one of the keywords. If a `ValueExpression` is specified, it must refer to a property that returns a `Collection` of `String` objects. If not specified, the default value is `@this`.
`immediate`	`javax.el.ValueExpression` that evaluates to a `Boolean`	A `Boolean` value that indicates whether inputs are to be processed early in the lifecycle. If `true`, behavior events generated from this behavior are broadcast during the Apply Request Values phase. Otherwise, the events will be broadcast during the Invoke Application phase.
`listener`	`javax.el.MethodExpression`	The name of the listener method that is called when a `javax.faces.event.AjaxBehaviorEvent` has been broadcast for the listener.
`onevent`	`javax.el.ValueExpression` that evaluates to a `String`	The name of the JavaScript function that handles UI events.
`onerror`	`javax.el.ValueExpression` that evaluates to a `String`	The name of the JavaScript function that handles errors.
`render`	`javax.el.ValueExpression` that evaluates to an `Object`	A `Collection` that identifies a list of components to be rendered on the client. If a literal is specified, it must be a space-delimited `String` of component identifiers and/or one of the keywords. If a `ValueExpression` is specified, it must refer to a property that returns a `Collection` of `String` objects. If not specified, the default value is `@none`.

The keywords listed in Table 13-2 can be used with the execute and render attributes of the f:ajax tag.

Table 13-2 Execute and Render Keywords

Keyword	Description
`@all`	All component identifiers
`@form`	The form that encloses the component
`@none`	No component identifiers
`@this`	The element that triggered the request

Note that when you use the f:ajax tag in a Facelets page, the JavaScript resource library is loaded implicitly. This resource library can also be loaded explicitly as described in Loading JavaScript as a Resource.

13.3 Using Ajax with Facelets

13.3.1 Using the f:ajax Tag

Table of Contents

Java Platform, Enterprise Edition: The Java EE Tutorial