6.23.  < a4j:support >

6.23.1. Description

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 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
ajaxSingleif "true", submits ONLY one field/link, instead of all form controls
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.
disableDefaultDisable default action for target event ( append "return false;" to javascript )
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", updates on client side ONLY elements from this 'reRender' property. If "false" (default) updates all rendered by ajax region components
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
statusID (in format of call UIComponent.findComponent()) of Request status component
timeoutTimeout (in ms) for request

Table 6.46. Component identification parameters

NameValue
component-typeorg.ajax4jsf.Support
component-familyorg.ajax4jsf.AjaxSupport
component-classorg.ajax4jsf.component.html.HtmlAjaxSupport
renderer-typeorg.ajax4jsf.components.AjaxSupportRenderer

6.23.2. Creating on a page

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.

6.23.3. Creating the Component Dynamically Using Java

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);

6.23.4. Key attributes and ways of usage

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

Note

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.

6.23.5. Relevant resources links

Here you can see the example of <a4j:support> usage and sources for the given example.