JBoss.orgCommunity Documentation

Chapter 2. Common Ajax attributes

2.1. Rendering
2.1.1. render
2.1.2. ajaxRendered
2.1.3. limitRender
2.2. Queuing and traffic control
2.2.1. queue
2.2.2. requestDelay
2.2.3. ignoreDupResponses
2.3. Data processing
2.3.1. execute
2.3.2. immediate
2.3.3. bypassUpdates
2.4. Action and navigation
2.4.1. action
2.4.2. actionListener
2.5. Events and JavaScript interactions
2.5.1. onsubmit
2.5.2. onbegin
2.5.3. onclick
2.5.4. onsuccess
2.5.5. oncomplete
2.5.6. onerror
2.5.7. data

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 render attribute provides a reference to one or more areas 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 attributes as a reference. Components can be referenced by their id attribute alone, or by a hierarchy of components' id attributes 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 hierarchy 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.

rendered attributes

A common problem with using render occurs when the referenced component has a rendered attribute. JSF does not mark the place in the browser's Document Object Model (DOM) where the rendered component would be placed in case the rendered attribute returns false. As such, when RichFaces sends the render code to the client, 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> with layout="none". The <a4j:outputPanel> will receive the update and render the component as required.

RichFaces uses a form-based approach for sending Ajax requests. 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 action and actionListener attributes can be used to invoke action methods and define action events.

RichFaces allows for Ajax-enabled JSF applications to be developed without using any additional JavaScript code. However it is still possible to invoke custom JavaScript code through Ajax events.