<?xml version='1.0' encoding='UTF-8'?>
<section>
	<sectioninfo>
		<keywordset>
			<keyword>a4j:support</keyword>
		</keywordset>
	</sectioninfo>
	<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 the Component with a Page Tag</title>
		<para>
			To create the simplest variant on a page you should put
			<emphasis role="bold">
				<property>&lt;a4j:support&gt;</property>
			</emphasis>
			as a nested element into the component that you want to enhance with
			Ajax functionality.
			You should also specify an event that will trigger
			an Ajax request.
		</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>
	</section>

	<section>
		<title>Creating the Component Dynamically Using Java</title>
		<para>
			In order to add the
			<emphasis role="bold">
				<property>&lt;a4j:support&gt;</property>
			</emphasis>
			in Java code you should add it as
			<property>facet</property>
			, not as a child:
		</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>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>&quot;event&quot;</property></emphasis> attribute that defines the JavaScript event 
					the Ajax support will be attached to 
				</para>
			</listitem>
			<listitem>
				<para>
				<emphasis><property>&quot;reRender&quot;</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&apos;s create ajaxed <emphasis role="bold"><property>&lt;h:selectOneMenu&gt;</property></emphasis> called
			&quot;Planets and Their Moons&quot;. 
		</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>&quot;onsubmit&quot;</property>
			</emphasis>
			and
			<emphasis>
				<property>&quot;oncomplete&quot;</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>&quot;oncomplete&quot;</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>
				&quot;Planets and Their Moons&quot;
			</title>
			<mediaobject>
				<imageobject>
					<imagedata fileref="images/supportSample.png"/>
				</imageobject>
			</mediaobject>
		</figure>
		<para>
			Information about the
			<emphasis>
				<property>&quot;process&quot;</property>
			</emphasis>
			attribute usage you can find in the &quot;
			<link linkend="process">Decide what to process</link>
			&quot; 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>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>
