JBoss.orgCommunity Documentation

Chapter 2. Common Ajax attributes

2.1. Data processing
2.1.1. execute
2.1.2. bypassUpdates
2.2. Rendering
2.2.1. render
2.2.2. ajaxRendered
2.2.3. limitRender
2.3. Queuing and traffic control
2.3.1. requestDelay
2.3.2. ignoreDupResponses
2.4. Events and JavaScript interactions
2.4.1. onbeforesubmit
2.4.2. onbegin
2.4.3. onbeforedomupdate
2.4.4. oncomplete
2.4.5. onerror
2.4.6. Registering event callbacks with jQuery

The Ajax components in the a4j library share common attributes to perform similar functionality. Most RichFaces components in the rich library that feature built-in Ajax support share these common attributes as well.

Most attributes have default values, so they need not be explicitly set for the component to function in its default state. These attributes can be altered to customize the behavior of the component if necessary.

The RichFaces Ajax script is built on a base of the JSF 2 Ajax script. As such, each time a request is sent, the data from the requesting component's parent JSF form is submitted along with the XMLHTTPRequest object. The form data contains values from the input element and auxiliary information such as state-saving data.

The render attribute provides a reference to one or more components on the page that need updating after an Ajax interaction. It uses the UIComponent.findComponent() algorithm to find the components in the component tree using their id identifiers as a reference. Components can be referenced by their id identifier alone, or by their clientId identifier to make locating components more efficient. Example 2.1, “render example” shows both ways of referencing components. Each command button will correctly render the referenced panel grids, but the second button locates the references more efficiently with explicit clientId paths.

The value of the render attribute can also be an expression written using JavaServer Faces' Expression Language (EL); this can either be a Set, Collection, Array, or String.

Differences between JSF Ajax and RichFaces Ajax

JSF evaluates all parameters during page rendering. As such, during a request from a page, all execute and render values are passed to the server from the client. In contrast, RichFaces evaluates these options at the server side during the current request.

This means that with JSF, making changes during a request to a render value defined with EL will not influence the request. RichFaces, however, will always use the newer values.

The RichFaces approach additionally increases data integrity. Parameters that are changed from the client side are re-evaluated on the server, where they cannot be changed.

Conditionally-rendered component updates

A common problem with using render occurs when the referenced component is conditionally rendered via the rendered attribute. If a component is not initially rendered, it does not have any HTML representation in the Document Object Model (DOM). As such, when RichFaces renders the component via Ajax, the page does not update as the place for the update is not known.

To work around this issue, wrap the component to be rendered in an <a4j:outputPanel> component. The <a4j:outputPanel> component will receive the update and render the component as required.

JSF provides global jsf.ajax.onError and jsf.ajax.onEvent events to define handlers (the jsf.ajax.onEvent event is used for all begin, success, and complete events). RichFaces adds event-specific attributes at the component level.