JBoss.orgCommunity Documentation

6.24.  < a4j:support >

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.47. a4j : support attributes

Attribute NameDescription
actionMethodBinding 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
actionListenerMethodBinding pointing at method accepting an ActionEvent with return type void
ajaxSingleboolean attribute which provides possibility to limit JSF tree processing(decoding, conversion/validation, value applying) to the component which send the request only
bindingThe attribute takes a value-binding expression for a component property of a backing bean
bypassUpdatesIf "true", after process validations phase it skips updates of model beans on a force render response. It can be used for validating components input
dataSerialized (on default with JSON) data passed on the client by a developer on AJAX request. It's accessible via "data.foo" syntax
disabledIf "true", disable this component on page.
disableDefaultDisables default action for target event ( append "return false;" to JavaScript ). Default value is "false"
eventName of JavaScript event property ( onclick, onchange, etc.) of parent component, for which we will build AJAX submission code
eventsQueueName 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.)
focusid of element to set focus after request completed on client side
idEvery component may have a unique id that is automatically created if omitted
ignoreDupResponsesAttribute 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
immediateTrue 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
limitToListIf "true", then of all AJAX-rendered on the page components only those will be updated, which ID's are passed to the "reRender" attribute of the describable component. "false"-the default value-means that all components with ajaxRendered="true" will be updated.
onbeforedomupdateJavaScript code for call before DOM has been updated on client side
oncompleteJavaScript code for call after request completed on client side
onsubmitJavaScript code for call before submission of ajax event
processId['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
renderedIf "false", this component is not rendered
requestDelayAttribute 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
reRenderId['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
similarityGroupingIdIf there are any component requests with identical IDs then these requests will be grouped.
statusID (in format of call UIComponent.findComponent()) of Request status component
timeoutTimeout (in ms) for request

Table 6.48. Component identification parameters

NameValue
component-typeorg.ajax4jsf.Support
component-familyorg.ajax4jsf.AjaxSupport
component-classorg.ajax4jsf.component.html.HtmlAjaxSupport
renderer-typeorg.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.

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:

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".

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.