<?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;eventsQueue&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 in the 
                              <link linkend="process"> &quot;Decide what to process&quot; </link> guide section. </para>
          </section>

          <section>
                    <title>Relevant resources links</title>
                    <para>
                              <ulink
                                        url="http://livedemo.exadel.com/richfaces-demo/richfaces/support.jsf?c=support"
                                        >On the component LiveDemo page</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>
