The <a4j:support> component adds an Ajax support to any existing JSF component. It allows a component to generate asynchronous requests on the necessary event demand and with partial update of page content after a response incoming from the server.
Table 6.45. a4j : support attributes
Attribute Name | Description |
---|---|
action | MethodBinding pointing at the application action to be invoked, if this UIComponent is activated by you, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of the immediate property |
actionListener | MethodBinding pointing at method accepting an ActionEvent with return type void |
ajaxSingle | if "true", submits ONLY one field/link, instead of all form controls |
binding | The attribute takes a value-binding expression for a component property of a backing bean |
bypassUpdates | If "true", after process validations phase it skips updates of model beans on a force render response. It can be used for validating components input |
data | Serialized (on default with JSON) data passed on the client by a developer on AJAX request. It's accessible via "data.foo" syntax |
disabled | If true, disable this component on page. |
disableDefault | Disable default action for target event ( append "return false;" to javascript ) |
event | Name of JavaScript event property ( onclick, onchange, etc.) of parent component, for which we will build AJAX submission code |
eventsQueue | Name of requests queue to avoid send next request before complete other from same event. Can be used to reduce number of requests of frequently events (key press, mouse move etc.) |
focus | id of element to set focus after request completed on client side |
id | Every component may have a unique id that is automatically created if omitted |
ignoreDupResponses | Attribute allows to ignore an Ajax Response produced by a request if the newest 'similar' request is in a queue already. ignoreDupResponses="true" does not cancel the request while it is processed on the server, but just allows to avoid unnecessary updates on the client side if the response isn't actual now |
immediate | True means, that the default ActionListener should be executed immediately (i.e. during Apply Request Values phase of the request processing lifecycle), rather than waiting until the Invoke Application phase |
limitToList | If "true", updates on client side ONLY elements from this 'reRender' property. If "false" (default) updates all rendered by ajax region components |
onbeforedomupdate | JavaScript code for call before DOM has been updated on client side |
oncomplete | JavaScript code for call after request completed on client side |
onsubmit | JavaScript code for call before submission of ajax event |
process | Id['s] (in format of call UIComponent.findComponent()) of components, processed at the phases 2-5 in case of AjaxRequest caused by this component. Can be single id, comma-separated list of Id's, or EL Expression with array or Collection |
rendered | If "false", this component is not rendered |
requestDelay | Attribute defines the time (in ms.) that the request will be wait in the queue before it is ready to send. When the delay time is over, the request will be sent to the server or removed if the newest 'similar' request is in a queue already |
reRender | Id['s] (in format of call UIComponent.findComponent()) of components, rendered in case of AjaxRequest caused by this component. Can be single id, comma-separated list of Id's, or EL Expression with array or Collection |
status | ID (in format of call UIComponent.findComponent()) of Request status component |
timeout | Timeout (in ms) for request |
Table 6.46. Component identification parameters
Name | Value |
---|---|
component-type | org.ajax4jsf.Support |
component-family | org.ajax4jsf.AjaxSupport |
component-class | org.ajax4jsf.component.html.HtmlAjaxSupport |
renderer-type | org.ajax4jsf.components.AjaxSupportRenderer |
To use a component, place <a4j:support> as nested to the component requesting Ajax functionality and specify an event of a parent component that generates Ajax request and the components to be rerendered after a response from the server.
Example:
<h:inputText value="#{bean.text}">
<a4j:support event="onkeyup" reRender="repeater"/>
</h:inputText>
<h:outputText id="repeater" value="#{bean.text}"/>
On every keyup event generated by an input field, a form is submitted on the server with the help of Ajax and on a response coming from the server, element with repeater id, founded in a DOM tree is redrawn according to a new data from the response.
In order to add <a4j:support> in Java code you should add it as facet , not children:
Example:
HtmlInputText inputText = new HtmlInputText();
...
HtmlAjaxSupport ajaxSupport = new HtmlAjaxSupport();
ajaxSupport.setActionExpression(FacesContext.getCurrentInstance().getApplication().getExpressionFactory().createMethodExpression(
FacesContext.getCurrentInstance().getELContext(), "#{bean.action}", String.class, new Class[] {}));
ajaxSupport.setEvent("onkeyup");
ajaxSupport.setReRender("output");
inputText.getFacets().put("a4jsupport", ajaxSupport);
<a4j:support> addition is very similar to correspondent event redefinition of a component, i.e.
Example:
...
<h:inputText value="#{bean.text}">
<a4j:support event="onkeyup" reRender="output" action="#{bean.action}"/>
</h:inputText>
...
Is decoded on a page as:
Example:
<input onkeyup="A4J.AJAX.Submit( Some request parameters )"/>
As you see from the code, the onkeyup event calls a utility RichFaces method that submit a form creating a special marks for a filter informing that it is an Ajax request. Thus, any supports quantity could be added to every component, the supports define component behavior on these events.
The components: <a4j:commandLink> , <a4j:commandButton> , <a4j:poll> and others from RichFaces library are already supplied with <a4j:support> functionality and there is no necessity to add the support to them.
With the help of "onsubmit" and "oncomplete" attributes the component allows using JavaScript before (for request sending conditions checking) and after an Ajax response processing termination (for performance of user-defined activities on the client)
Example:
<h:selectOneMenu value="#{bean.text}">
<f:selectItem itemValue="First Item " itemLabel="First Item"/>
<f:selectItem itemValue=" Second Item " itemLabel="Second Item"/>
<f:selectItem itemValue=" Third Item " itemLabel="Third Item"/>
<a4j:support event="onblur" reRender="panel" onsubmit="if(!confirm('Are you sure to change the option ?'))
{form.reset(); return false;}" oncomplete="alert('Value succesfully stored')"/>
</h:selectOneMenu>
In example there is the condition checking (confirm) is used before request sending and message printing after the request processing is over.
The components allows different Ajax request managing ways for its various optimization in particular conditions such as:
Limitation of the submit area and updating area for the request.
"ajaxSingle" is an attribute that allows submission on the server only component sending a request, as if the component presented on a separate form.
"limitToList" is an attribute that allows to limit areas, which are updated after the responses. Only these components defined in the "reRender" attribute are updated.
Example 1:
<h:form>
<h:inputText value="#{person.name}">
<a4j:support event="onkeyup" reRender="test" ajaxSingle="true"/>
</h:inputText>
<h:inputText value="#{person.middleName}"/>
</form>
In this example the request contains only the input component causes the request generation, not all the components contained on a form, because of "ajaxSingle" ="true" usage.
Example 2:
<h:form>
<a4j:outputPanel ajaxRendered="true">
<h:messages/>
</a4j:outputPanel>
<h:inputText value="#{person.name}">
<a4j:support event="onkeyup" reRender="test" limitToList="true"/>
</h:inputText>
<h:outputText value="#{person.name}" id="test"/>
</form>
In this example the component <h:messages> is always updated (as it capturing all Ajax requests, located in ajaxRendered <a4j:outputPanel> ), except the case when a response is sent from the input component from the example. On sending this component marks that updating area is limited to the defined in it components, it means that on its usage with "limitToList" ="true" the only component updated is the one with "id" ="test".
Limitation of requests frequency and updates quantity after the responses.
"requestDelay" is an attribute that defines a time interval in seconds minimally permissible between responses.
"eventQueue" is an attribute for naming of the queue where the next response is kept in till its processing, but if the next event comes in till this time is over, the waiting event is taken away, replacing with a new one.
"ignoreDupResponces" is an attribute that allows to disable any updates on the client after an Ajax request if another Ajax request is already sent.
"timeout" is an attribute that allows to set a time interval in millisecond to define a maximum time period of response wait time. In case of the interval interaction, a new request is sent and the previous one is canceled. Postprocessing of a response isn't performed.
Example:
<h:form>
<h:inputText value="#{person.name}">
<a4j:support event="onkeyup" reRender="test"
requestDelay="1000" ignoreDupResponces="true" eventsQueue="myQueue"/>
</h:inputText>
<h:outputText value="#{person.name}" id="test"/>
</form>
This example clearly shows mentioned above attributes. If quick typing in a text field happens, every next requests sending is delayed for a second and requests quantity is reduced. The requests are kept in the queue till its the sending. Moreover, if the next request is already sent, the rerendering after the previous request is banned, and it helps to avoid unnecessary processing on the client.
Information about the "process" attribute usage you can find here.
Here you can see the example of <a4j:support> usage and sources for the given example.