JBoss.orgCommunity Documentation
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 execute attribute allows JSF processing to be limited to defined components. The execute attribute can point to an id identifier of a specific component to process. Components can also be identified through the use of Expression Language ( EL).
Alternatively, the execute attribute accepts the following keywords:
@all@none@thisexecute attribute is processed. This is the default behavior for components.
@form@region<a4j:region> component as a wrapper element to specify regions.
Some components make use of additional keywords. These are detailed under the relevant component entry in this book.
If the bypassUpdates attribute is set to true, the Update Model phase of the request processing lifecycle is bypassed. This is useful if user input needs to be validated but the model does not need to be updated. This is the opposite functionality to the execute attribute in RichFaces.
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.
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.
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.
A component with ajaxRendered="true" will be re-rendered with every Ajax request, even when not referenced by the requesting component’s render attribute. This can be useful for updating a status display or error message without explicitly requesting it.
The ajaxRendered attribute’s functionality is the basis for the <a4j:outputPanel> component. The <a4j:outputPanel> component is designed to mark parts of the page for automatic updating. Refer to Section 5.1, “<a4j:outputPanel>” for details.
Automatic rendering of such components can be repressed by adding limitRender="true" to the requesting component, as described in Section 2.2.3, “limitRender”.
RichFaces Ajax-enabled components and Ajax behaviors with limitRender="true" specified will not cause components with ajaxRendered="true" to re-render, and only those components listed in the render attribute will be updated. This essentially overrides the ajaxRendered attribute in other components.
Example 2.3, “Data reference example” describes two command buttons, a panel grid rendered by the buttons, and an output panel showing error messages. When the first button is clicked, the output panel is rendered even though it is not explicitly referenced with the render attribute. The second button, however, uses limitRender="true" to override the output panel’s rendering and only render the panel grid.
The requestDelay attribute specifies an amount of time in milliseconds for the request to wait in the queue before being sent to the server. If a similar request is added to the queue before the delay is over, the original request is replaced with the new one.
When set to true, the ignoreDupResponses attribute causes responses from the server for the request to be ignored if there is another similar request in the queue. This avoids unnecessary updates on the client when another update is expected. The request is still processed on the server, but if another similar request has been queued then no updates are made on the client.
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.
The onbeforesubmit event attribute invokes the event listener before an Ajax request is sent. The request is canceled if the event listener defined for the onbeforesubmit event returns false.
The onbeforedomupdate event attribute invokes the event listener after an Ajax response has been returned but before the DOM tree of the browser is updated.
The oncomplete event attribute invokes the event listener after an Ajax response has been returned and the DOM tree of the browser has been updated.
The data attribute allows additional data to be handled with the oncomplete event. Use JSF Expression Language ( EL) to reference the property of the managed bean, and its value will be serialized in JavaScript Object Notation ( JSON) and returned to the client side. The property can then be referenced through the event.data variable in the event attribute definitions. Both primitive types and complex types such as arrays and collections can be serialized and used with data.
Example 2.3. Data reference example
<a4j:commandButton value="Update" oncomplete="showTheName(event.data.name)" data="#{userBean.name}" />
The onerror event attribute invokes the event listener when an error has occurred during Ajax communications.
RichFaces allows one to register callbacks for the events listed above using jQuery:
ajaxsubmit: triggered before an Ajax request is sent.
ajaxbegin: triggered after an Ajax request is sent.
ajaxbeforedomupdate: triggered after an Ajax response has been returned but before the DOM tree of the browser has been updated.
ajaxcomplete: triggered after an Ajax response has been returned and the DOM tree of the browser has been updated.
The event callback can be registered either on a form or a whole page:
<h:outputScript>
jQuery(document).ready(function() {
jQuery(#{rich:element('form_id')}).on("ajaxsubmit", function() {
// the callback will be triggered before the form is submitted using JSF AJAX
console.log("ajaxsubmit");
});
jQuery(document).on("ajaxcomplete", function() {
// the callback will be triggered for each completed JSF AJAX for the current page
console.log("ajaxcomplete");
});
}
</h:outputScript>