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.
By using the <h:commandScript> component to execute arbitrary server-side methods from a view. The component generates a JavaScript function with a given name that when invoked, in turn invokes, a given server-side method via Ajax.

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.