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

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

## Dynamical creation of a component from Java code

Example:

    import org.ajax4jsf.component.html.HtmlAjaxSupport;
    ...
    HtmlAjaxSupport mySupport = new HtmlAjaxSupport();>

## 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="repeater"/>
    </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 "d"="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.

## Relevant resources links

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