This chapter covers those components that manage the processing of information, requests, and updates.
The <a4j:queue> component manages the JSF queue of Ajax requests. It provides additional options for a finer control of request processing.
The <a4j:queue> component works in the same basic way as the standard JSF queue. It can be enabled and disabled through the enabled attribute.
Requests from other libraries
The <a4j:queue> component does not handle standard JSF requests or requests from component libraries other than RichFaces.
Use the requestDelay attribute to add a delay between each request in the queue. Set the requestDelay attribute to the number of milliseconds to wait in between each request. Delaying requests avoids unnecessary processing for actions that would otherwise cause multiple requests, such as typing. Similar requests in the queue are combined while waiting for the request delay.
Example 7.1. Delaying requests
<a4j:queue requestDelay="1500"/>
The queue delays each request by 1500 milliseconds.
The client side can update unnecessarily if duplicate responses require similar updates. Set ignoreDupResponses="true" to ignore duplicate responses. With this setting, the client will not update from a request if a similar request is in the queue.
Define the queue scope to make it the default queue for all requests in that scope. The scope depends on the placement of the queue and any naming identifiers.
-
An unnamed
<a4j:queue>component placed outside any forms becomes the default queue for all requests on the page. -
An unnamed
<a4j:queue>component placed inside a form becomes the default queue for all requests within that form. -
Use the
nameidentifier attribute to name an<a4j:queue>component. Named queues can be accessed with the<a4j:attachQueue>behavior to act as a queue for specific components and behaviors. Refer to Section 7.1.7, “<a4j:attachQueue>” for details.
Example 7.2. Queue scopes
<a4j:queue name="viewQueue" requestDelay="2000"/>
<h:form>
<a4j:queue name="formQueue" requestDelay="1500"/>
...
</h:form>
The queue outside the form is scoped to the view. The queue inside the form is scoped only to that form.
The <a4j:queue> component features several events relating to queuing actions in addition to the common JSF events:
-
The
completeevent is fired after a request is completed. The request object is passed as a parameter to the event handler, so the queue is accessible usingrequest.queueand the element which was the source of the request is accessible usingthis. -
The
requestqueueevent is fired after a new request has been added to the queue. -
The
requestdequeueevent is fired after a request has been removed from the queue.
-
component-type:org.richfaces.Queue -
component-class:org.richfaces.component.UIQueue -
component-family:org.richfaces.Queue -
renderer-type:org.richfaces.QueueRenderer
The <a4j:attachQueue> behavior is used together with a <a4j:queue> component to further customize queuing for particular components and behaviors. The <a4j:attachQueue> behavior can override the scope-wide queue settings for an individual component, or attach specific requests to a queue.
Queues can be scoped to various levels as described in Section 7.1.4, “Queue scopes”. Use an <a4j:attachQueue> behavior in the same scope as a queue to override the queue settings for a particular control.
Example 7.3. Overriding scope settings
<a4j:queue requestDelay="2000"/>
<h:form>
<rich:panel>
<h:inputText>
<a4j:ajax event="keyup" />
</h:inputText>
<a4j:commandButton value="submit">
<a4j:attachQueue requestDelay="0" />
</a4j:commandButton>
</rich:panel>
</h:form>
The request delay is overridden by the <a4j:attachQueue> behavior on the submit button.
Name an <a4j:queue> component using the name attribute. It can then be used by specific components through the <a4j:attachQueue> behavior. Use the name attribute of the <a4j:attachQueue> behavior to identify the name of the destination queue.
Example 7.4. Using a named queue
<a4j:queue name="viewQueue"/>
<h:form>
<a4j:queue name="formQueue"/>
<rich:panel>
<a4j:commandButton value="submit">
<a4j:attachQueue name="viewQueue" />
</a4j:commandButton>
</rich:panel>
</h:form>
The requests from the button are attached to the viewQueue queue, rather than the formQueue queue.
Use grouping to process multiple requests together. Specify a grouping identifier with the requestGroupingId attribute. Requests from multiple <a4j:attachQueue> behaviors can use the same identifier to group requests together.
Example 7.5. Grouping requests
<h:form>
<a4j:queue requestDelay="2000"/>
<h:inputText id="input1" value="#{queueBean.text1}">
<a4j:attachQueue requestGroupingId="registrationForm"/>
</h:inputText>
<h:inputText id="input2" value="#{queueBean.text2}">
<a4j:attachQueue requestGroupingId="registrationForm"/>
</h:inputText>
</h:form>
Requests from both the text input boxes are grouped together with the registrationForm identifier.
The <a4j:log> component generates JavaScript that opens a debug window, logging application information such as requests, responses, and DOM changes.
The <a4j:log> component doesn’t require any additional attributes for basic functionality.
The mode attribute determines how the log appears on the page.
-
Set
mode="inline"to place the logging data in-line on the current page. This is the default setting. -
Set
mode="popup"to present the logging data in a new pop-up window. The window is set to be opened by pressing the key combination Ctrl+Shift+L; this can be partially reconfigured with thehotkeyattribute, which specifies the letter key to use in combination with Ctrl+Shift instead of L. -
Set
mode="console"to present the logging data in the JavaScript console of the browser.
The amount of data logged can be determined with the level attribute:
-
Set
level="ERROR"to log all errors. -
Set
level="FATAL"to log only fatal messages. -
Set
level="INFO"to log only informational messages. -
Set
level="WARN"to log only warning messages. -
Set
level="ALL"to log all data. This is the default setting.
Log renewal
The log is automatically renewed after each Ajax request. It does not need to be explicitly re-rendered. To clear previous requests, implement a Clear button or similar functionality.
-
component-type:org.richfaces.AjaxLog -
component-class:org.richfaces.component.UIAjaxLog -
component-family:org.richfaces.AjaxLog -
renderer-type:org.richfaces.AjaxLogRenderer
The <a4j:log> component is intended primarily for debugging during development. However it is still possible to style the component if desired.
Table 7.1. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
|
|
|
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
The <a4j:status> component displays the status of current Ajax requests. The status can be either in progress, complete, or an error is shown after a failed request.
The text display can be customized depending on the current status.
-
The
startTextattribute defines the text shown after the request has been started and is currently in progress. Set the styles for the text with thestartStyleandstartStyleClassattributes. Alternatively, use thestartfacet to customize the text appearance. -
The
stopTextattribute defines the text shown once the request is complete. Set the styles for the text with thestopStyleandstopStyleClassattributes. Alternatively, use thestopfacet to customize the text appearance.If the
stopTextattribute is not defined, and no facet exists for the stopped state, the complete status is simply not shown. In this way, only the progress of the request is displayed to the user, along with any errors. -
The
errorTextattribute defines the text shown when an error has occurred. Set the styles for the text with theerrorStyleanderrorStyleClassattributes. Alternatively, use theerrorfacet to customize the text appearance.
The <a4j:status> component monitors the status of the region relevant to where it is placed.
- If unnamed and placed outside any forms, it monitors the status at the view level.
- If unnamed and placed inside a form, it monitors the status at the form level.
However, if identified with the name attribute, the <a4j:status> component can monitor any Ajax component or behavior. Use the status attribute on the Ajax component or behavior to reference the name identifier of the <a4j:status> component.
Example 7.8. Updating a referenced <a4j:status> component
<rich:panel>
<f:facet name="header">
<h:outputText value="User Details Panel" />
</f:facet>
<h:panelGrid columns="3">
<h:outputText value="User name:" />
<h:inputText value="#{userBean.name}">
<a4j:ajax status="nameStatus" event="keyup" />
</h:inputText>
<a4j:status name="nameStatus">
<f:facet name="start">
<h:graphicImage value="/images/ai.gif" />
</f:facet>
</a4j:status>
<h:outputText value="Address:" />
<h:inputText value="#{userBean.address}">
<a4j:ajax status="addressStatus" event="keyup" />
</h:inputText>
<a4j:status name="addressStatus">
<f:facet name="start">
<h:graphicImage value="/images/ai.gif" />
</f:facet>
</a4j:status>
</h:panelGrid>
</rich:panel>
The <a4j:status> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
start()-
Switches status to the
startstate. stop()-
Switches status to the
stopstate. error()-
Switches status to the
errorstate.