<section role="NotInToc" id="a4j_support">
   <title>
				&lt;
				a4j:support
				&gt;
				<emphasis role="since">
         <superscript> available since <emphasis role="version">3.0.0</emphasis>
         </superscript>
      </emphasis>
   </title>
   <section>
      <sectioninfo>
         <keywordset>
            <keyword>a4j:support</keyword>
            <keyword>component</keyword>
         </keywordset>
      </sectioninfo>
    
      <title>Description</title>
        <para>
        	The <emphasis role="bold">
            <property>&lt;a4j:support&gt;</property>
         </emphasis> component 
        	is the most important core component in the RichFaces library. 
        	It enriches any existing non-Ajax JSF or RichFaces component with  Ajax capability. 
            All other RichFaces Ajax components are based on the same principles 
            <emphasis role="bold">
            <property>&lt;a4j:support&gt;</property>
         </emphasis> has.  
             <!-- 
             The requests are invoked by definite user activity and used for updating 
             and re-rendering page contents partially after a response from server.
              --> 
        </para>
   </section>
   <section>
		    <title>Details of Usage</title>
		    <para>
			The <emphasis role="bold">
				        <property>&lt;a4j:support&gt;</property>
			      </emphasis>
			component has two key attributes:
		</para>
		    <itemizedlist>
			      <listitem>
				        <para>
					mandatory
					<emphasis>
                  <property>"event"</property>
               </emphasis> attribute that defines the JavaScript event 
					the Ajax support will be attached to 
				</para>
			      </listitem>
			      <listitem>
				        <para>
				           <emphasis>
                  <property>"reRender"</property>
               </emphasis> attribute that defines id(s) 
				of JSF component(s) that should be rerendered after an Ajax request 
				</para>
			      </listitem>
		    </itemizedlist>
		    <para>
			As mentioned above, the <emphasis role="bold">
            <property>&lt;a4j:support&gt;</property>
         </emphasis> component
			adds Ajax capability to non-Ajax JSF components.
			Let's create ajaxed <emphasis role="bold">
            <property>&lt;h:selectOneMenu&gt;</property>
         </emphasis> called
			"Planets and Their Moons". 
		</para>
		    <para>
			We begin with the common behavior description. When a page is rendered you see only one select box with the list of planets.
			When you select a planet the  <emphasis role="bold">
            <property>&lt;h:dataTable&gt;</property>
         </emphasis>
			containing moons of the selected planet appears.   
		</para>
		    <para>
			In other words we need <emphasis role="bold">
            <property>&lt;h:selectOneMenu&gt;</property>
         </emphasis>
			with the nested <emphasis role="bold">
            <property>&lt;a4j:support&gt;</property>
         </emphasis> component that 
			is attached to the <property>onchange</property> event. 
		</para>
		    <para>
			When an Ajax response comes back the <emphasis role="bold">
            <property>&lt;h:dataTable&gt;</property>
         </emphasis>
			is re-rendered on the server side and updated on the client.			
		</para>
		    <programlisting role="XML"><![CDATA[...
<h:form id="planetsForm">
	<h:outputLabel value="Select the planet:" for="planets" />
	<h:selectOneMenu id="planets" value="#{planetsMoons.currentPlanet}" valueChangeListener="#{planetsMoons.planetChanged}">
		<f:selectItems value="#{planetsMoons.planetsList}" />
		<a4j:support event="onchange" reRender="moons" />
	</h:selectOneMenu>
	<h:dataTable id="moons" value="#{planetsMoons.moonsList}" var="item">
		<h:column>
			<h:outputText value="#{item}"/>
		</h:column>
	</h:dataTable>
</h:form>
...]]></programlisting>
		    <para>
			Finally we need a backing bean:
		</para>
		    <programlisting role="JAVA"><![CDATA[...
public class PlanetsMoons {
	private String currentPlanet="";
	public List<SelectItem> planetsList = new ArrayList<SelectItem>();
	public List<String> moonsList = new ArrayList<String>();
	private static final String [] EARTH = {"The Moon"};
	private static final String [] MARS = {"Deimos", "Phobos"};
	private static final String [] JUPITER = {"Europa", "Gamymede", "Callisto"};
	
	public PlanetsMoons() {
        SelectItem item = new SelectItem("earth", "Earth");
        planetsList.add(item);
        item = new SelectItem("mars", "Mars");
        planetsList.add(item);
        item = new SelectItem("jupiter", "Jupiter");
        planetsList.add(item);
    }
	
	public void planetChanged(ValueChangeEvent event){
		 moonsList.clear();
         String[] currentItems;
         if (((String)event.getNewValue()).equals("earth")) {
             currentItems = EARTH;
         }else if(((String)event.getNewValue()).equals("mars")){
             currentItems = MARS;
         }else{
        	 currentItems = JUPITER;
         }
         for (int i = 0; i < currentItems.length; i++) {
             moonsList.add(currentItems[i]);
         }       
     }
	    
	//Getters and Setters
	...   
}
]]></programlisting>
		    <para>
			There are two properties <code>planetsList</code> and <code>moonsList</code>. 
			The <code>planetsList</code> is filled with planets names in the constructor.   
			After you select the planet,
			the  <code>planetChanged()</code> listener is called and
			the <code>moonsList</code> is populated with proper values of moons. 
		</para>
		    <para>
			With the help of
			<emphasis>
				        <property>"onsubmit"</property>
			      </emphasis>
			and
			<emphasis>
				        <property>"oncomplete"</property>
			      </emphasis>
			attributes the <emphasis role="bold">
            <property>&lt;a4j:support&gt;</property>
         </emphasis> component 
			allows to use JavaScript calls before and after an Ajax request
			respectively. 
			Actually the JavaScript specified in the <emphasis>
            <property>"oncomplete"</property>
         </emphasis> attribute
			will be executed in any case whether the Ajax request is completed successfully or not. 
		</para>
		    <para> 
			You can easily add confirmation dialog for the planet select box and colorize 
			<emphasis role="bold">
            <property>&lt;h:dataTable&gt;</property>
         </emphasis> after the Ajax response:
		</para>
		    <programlisting role="XML"><![CDATA[...
<h:form id="planetsForm">
	<h:outputLabel value="Select the planet:" for="planets" />
	<h:selectOneMenu id="planets" value="#{planetsMoons.currentPlanet}" valueChangeListener="#{planetsMoons.planetChanged}">
		<f:selectItems value="#{planetsMoons.planetsList}" />
		<a4j:support event="onchange" reRender="moons" 
					onsubmit="if(!confirm('Are you sure to change the planet?')) {form.reset(); return false;}" 
					oncomplete="document.getElementById('planetsForm:moonsPanel').style.backgroundColor='#c8dcf9';" />
	</h:selectOneMenu>
	<h:dataTable id="moons" value="#{planetsMoons.moonsList}" var="item">
		<h:column>
			<h:outputText value="#{item}"/>
		</h:column>
	</h:dataTable>
</h:form>
...]]></programlisting>
	     <para>
		There is the result:
	</para>
	     <figure>
			      <title>
				"Planets and Their Moons"
			</title>
			      <mediaobject>
				        <imageobject>
					          <imagedata fileref="images/supportSample.png"/>
				        </imageobject>
			      </mediaobject>
		    </figure>
		    <para>
			Information about the
			<emphasis>
				        <property>"process"</property>
			      </emphasis>
			attribute usage you can find in the "
			<link linkend="process">Decide what to process</link>
			" guide section.
		</para>

		    <note>
			      <title>Tip:</title>
			      <para>
				The
				<emphasis role="bold">
					          <property>&lt;a4j:support&gt;</property>
				        </emphasis>
				component created on a page as following
			</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 in HTML as</para>
			      <programlisting role="XML"><![CDATA[<input  onkeyup="A4J.AJAX.Submit( Some request parameters )"/>]]></programlisting>
		    </note>
	  </section>
   <section>
      <title>Reference Data</title>
      <para>
         <ulink url="&tlddoc;a4j/support.html">Table of 
							&lt;a4j:support&gt; 
							 attributes</ulink>.
						</para>
      <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>
   <section>
		    <title>Relevant Resources Links</title>
		    <para>
			Visit
			<ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/support.jsf?c=support">&lt;a4j:support&gt; demo page</ulink>
			at RichFaces live demo for examples of component usage and their
			sources.
		</para>

	  </section>
</section>
