JBoss.orgCommunity Documentation
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.
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 name
identifier 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 complete
event is fired after a request is completed. The request object is passed as a parameter to the event handler, so the queue is accessible using request.queue
and the element which was the source of the request is accessible using this
.
The requestqueue
event is fired after a new request has been added to the queue.
The requestdequeue
event 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 the hotkey
attribute, which specifies the letter key to use in combination with Ctrl+Shift instead of L.
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.
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 |
---|---|---|
|
| color |
| 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 startText
attribute defines the text shown after the request has been started and is currently in progress. Set the styles for the text with the startStyle
and startStyleClass
attributes. Alternatively, use the start
facet to customize the text appearance.
The stopText
attribute defines the text shown once the request is complete. Set the styles for the text with the stopStyle
and stopStyleClass
attributes. Alternatively, use the stop
facet to customize the text appearance.
If the stopText
attribute 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 errorText
attribute defines the text shown when an error has occurred. Set the styles for the text with the errorStyle
and errorStyleClass
attributes. Alternatively, use the error
facet 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 start
state.
stop()
Switches status to the stop
state.
error()
Switches status to the error
state.