<?xml version='1.0' encoding='UTF-8'?>
<chapter>
  <chapterinfo>
    <keywordset>
      <keyword>a4j:support</keyword>
    </keywordset>
  </chapterinfo>
    <table>
	 <title>Component identification parameters</title>
      <tgroup cols="2">
	  <thead>
            <row>
                <entry>Name</entry>
                <entry>Value</entry>
            </row>
        </thead>	 
        <tbody>
          <row>
            <entry>component-type</entry>
            <entry>org.ajax4jsf.Support</entry>
          </row>
          <row>
            <entry>component-family</entry>
            <entry>org.ajax4jsf.AjaxSupport</entry>
          </row>
          <row>
            <entry>component-class</entry>
            <entry>org.ajax4jsf.component.html.HtmlAjaxSupport</entry>
          </row>
          <row>
            <entry>renderer-type</entry>
            <entry>org.ajax4jsf.components.AjaxSupportRenderer</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
 
  <section>
    <title>Creating on a page</title>
    <para>To use a component, place <emphasis role="bold">
          <property>&lt;a4j:support&gt;</property>
        </emphasis> 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.</para>
    <para><emphasis role="bold">Example:</emphasis></para>
    <programlisting role="XML"><![CDATA[<h:inputText value="#{bean.text}">
	<a4j:support event="onkeyup" reRender="repeater"/>
</h:inputText>
<h:outputText id="repeater" value="#{bean.text}"/>]]></programlisting>
    <para>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 <code>repeater</code> id, founded in a DOM tree is 
    redrawn according to a new data from the response.</para>
  </section>
  <section>
    <title>Creating the Component Dynamically Using Java</title>
    <para>In order to add <emphasis role="bold">
      <property>&lt;a4j:support&gt;</property>
    </emphasis> in Java code you should  add it as <emphasis><property>facet</property></emphasis>, not children:</para>
  <para>
      <emphasis role="bold">Example:</emphasis>
 </para>
    <programlisting role="JAVA"><![CDATA[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);
]]></programlisting>
  </section>
  <section>
    <title>Key attributes and ways of usage</title>
    <para><emphasis role="bold"><property>&lt;a4j:support&gt;</property></emphasis> addition is very similar to correspondent event redefinition of a component, i.e. 
</para>
    <para><emphasis role="bold">Example:</emphasis></para>
	<programlisting role="XML"><![CDATA[...
<h:inputText value="#{bean.text}">
    <a4j:support event="onkeyup" reRender="output" action="#{bean.action}"/>
</h:inputText>
...]]></programlisting>    
<para>Is decoded on a page as:</para>

  <para>
      <emphasis role="bold">Example:</emphasis>
 </para>
<programlisting role="XML"><![CDATA[
<input  onkeyup="A4J.AJAX.Submit( Some request parameters )"/>
]]></programlisting>
    <para>As you see from the code, the <emphasis><property>&quot;onkeyup&quot;</property></emphasis>
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. </para>
    <note>
      <para>The components: <emphasis role="bold"><property>&lt;a4j:commandLink&gt;</property></emphasis>, <emphasis role="bold"><property>&lt;a4j:commandButton&gt;</property></emphasis>, <emphasis role="bold">
          <property>&lt;a4j:poll&gt;</property>
        </emphasis> and others from RichFaces library are already supplied with <emphasis role="bold">
          <property>&lt;a4j:support&gt;</property>
        </emphasis> functionality and there is no necessity to add the support to them. </para>
    </note>
    <para>With the help of <emphasis >
        <property>&quot;onsubmit&quot;</property></emphasis> and <emphasis >
        <property>&quot;oncomplete&quot;</property></emphasis> 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) </para>
    <para><emphasis role="bold">Example:</emphasis></para>
	<programlisting role="XML"><![CDATA[<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>]]></programlisting>
    <para>In example there is the condition checking (confirm) is used before request sending and message printing after the request processing is over. </para>
      <para>The components allows different Ajax request managing ways for its various optimization in particular conditions such as: 
<itemizedlist>
        <listitem><para>
          <emphasis role="bold">Limitation of the submit area and updating area for the request.</emphasis></para>
          <para><emphasis ><property>&quot;ajaxSingle&quot;</property></emphasis> is an attribute that allows submission on the server only component sending a request, as if the component presented on a separate form. 

</para>
          <para><emphasis ><property>&quot;limitToList&quot;</property></emphasis> is an attribute  that allows to limit areas, which are updated after the responses. Only these components defined in the <emphasis><property> &quot;reRender&quot; </property></emphasis>attribute are updated. </para>
        </listitem>
      </itemizedlist></para>
    <para><emphasis role="bold">Example 1:</emphasis></para>
	<programlisting role="XML"><![CDATA[<h:form>
	<h:inputText value="#{person.name}">
		<a4j:support event="onkeyup" reRender="test" ajaxSingle="true"/>
	</h:inputText>
	<h:inputText value="#{person.middleName}"/>
</form>]]></programlisting>
    <para>In this example the request contains only the input component causes the  request generation, not  all the components contained on a form, because of <code>ajaxSingle=&quot;true&quot;</code> usage.  </para>
    <para><emphasis role="bold">Example 2:</emphasis></para>
	<programlisting role="XML"><![CDATA[<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>]]></programlisting>
    <para>In this example the component <emphasis role="bold"><property>&lt;h:messages&gt;</property></emphasis> is always updated (as it capturing all Ajax requests, located in ajaxRendered <emphasis role="bold"><property>&lt;a4j:outputPanel&gt;</property></emphasis>), 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 <code>limitToList=&quot;true&quot;</code>  the only component updated is the one with <code>id=&quot;test&quot;</code>.</para>
	<itemizedlist>
        <listitem><para>
          <emphasis role="bold">Limitation of requests frequency and updates quantity after the responses. </emphasis></para>
          <para><emphasis ><property>&quot;requestDelay&quot;</property></emphasis> is an attribute that defines a time interval in seconds minimally permissible between responses. 

</para>
          <para><emphasis ><property>&quot;eventQueue&quot;</property></emphasis> 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. 

</para>
          <para><emphasis ><property>&quot;ignoreDupResponces&quot;</property></emphasis> is an attribute that allows to disable any updates on the client after an Ajax request if another Ajax request is already sent. 
</para>
          <para><emphasis ><property>&quot;timeout&quot;</property></emphasis> 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.
</para>
          <para><emphasis role="bold">Example:</emphasis></para>
		  <programlisting role="XML"><![CDATA[<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>]]></programlisting>
          <para>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.</para>
        </listitem>
	</itemizedlist>
    <para>
      Information about the <emphasis><property>&quot;process&quot;</property></emphasis> attribute usage you can find <link linkend="process">here</link>.
    </para>
  </section>
  
    <section>
    <title>Relevant resources links</title>
	<para>
	  <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/support.jsf?c=support">Here</ulink>  you can see the example of <emphasis role="bold"
	    ><property>&lt;a4j:support&gt;</property></emphasis> usage and sources for the given example. 
	</para>
  </section>
  </chapter>