<?xml version='1.0' encoding='UTF-8'?>
<chapter> 
  <chapterinfo>
    <keywordset>
      <keyword>a4j:commandButton</keyword>
    </keywordset>
  </chapterinfo>
      <para><table frame="all">
 <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.CommandButton</entry>
            </row>
            <row>
              <entry>component-family</entry>
              <entry>javax.faces.Command</entry>
            </row>
            <row>
              <entry>component-class</entry>
              <entry>org.ajax4jsf.component.html.HtmlAjaxCommandButton</entry>
            </row>
            <row>
              <entry>renderer-type</entry>
              <entry>org.ajax4jsf.components.AjaxCommandButtonRenderer</entry>
            </row>
          </tbody>
        </tgroup>
      </table></para>
        
      <section>
            <title>Creating the Component with a Page Tag</title>
            <para>
                  To create the simplest variant of the component on a page use the following syntax:
            </para>
            <para id="CB_example">
                  <emphasis role="bold">Example:</emphasis>
            </para>
            <programlisting role="XML"><![CDATA[<a4j:commandButton reRender="someData" action="#{bean.action}" value="Button"/>]]></programlisting>
            <para>
                  The example above creates a button on a page clicking on which causes an Ajax form submit on the server, <code>&quot;action&quot;</code> method performance, 
                  and rendering the component with <code>&quot;someData&quot;</code> ID after response comes back.
            </para>
      </section>
      
      <section>
            <title>Creating the Component Dynamically Using Java</title>
            <para>
                  <emphasis role="bold">Example:</emphasis>
            </para>
            <programlisting role="JAVA"><![CDATA[import org.ajax4jsf.component.html.HtmlAjaxCommandButton;
...
HtmlAjaxCommandButton myButton = new HtmlAjaxCommandButton();
...]]></programlisting>
      </section>
      
      <section>
            <title>Details of Usage</title>
            <para>
                  The <emphasis role="bold"><property>&lt;a4j:commandButton&gt;</property></emphasis> component is used in the same way as JSF <emphasis role="bold"><property>&lt;h:commandButton&gt;</property></emphasis>. 
                  The difference is that in case of <emphasis role="bold"><property>&lt;a4j:commandButton&gt;</property></emphasis> the components to be updated should be specified.
            </para>
            
            <para>
                  The example <link linkend="CB_example">above</link> generates the following HTML code:
            </para>
            
            <programlisting role="XML"><![CDATA[<input type="submit" onclick="A4J.AJAX.Submit(request parameters);return false;" value="Button"/>]]></programlisting>
            
            <para>      
                  Сlicking the generated anchor fires the utility method <code>A4J.AJAX.Submit()</code> that perfroms Ajax request.                  
            </para>
                       
            <note>
                  <title>Note:</title>
                  <para>
                        The <emphasis role="bold"><property>&lt;a4j:commandButton&gt;</property></emphasis> already has Ajax support built-in and there is no need to add <emphasis role="bold"><property>&lt;a4j:support&gt;</property></emphasis>.                        
                  </para>
            </note>
            
      <para>
            The usage of the keyword <code>&apos;this&apos;</code> in JavaScript code in the value for <emphasis><property>&quot;oncomplete&quot;</property></emphasis> attribute depends on the location of <emphasis role="bold"><property>&lt;a4j:commandButton&gt;</property></emphasis>. 
            If the <emphasis role="bold"><property>&lt;a4j:commandButton&gt;</property></emphasis> is situated outside the re-rendered region it is possible to use keyword <property>&apos;this&apos;</property> as in the following example:  
      </para>
            <programlisting role="XML"><![CDATA[<h:form>
      <a4j:commandButton action="director.rollCamera" onclick="this.disabled=true" oncomplete="this.disabled=false" /> 
</h:form>]]></programlisting>
            
            <para>
                  Otherwise, if the <emphasis role="bold"><property>&lt;a4j:commandButton&gt;</property></emphasis> is contained in a re-rendered region 
                  than the <emphasis><property>&quot;oncomplete&quot;</property></emphasis> attribute has a problem with obtaining a reference of the 
                  <property>commandButton</property> object when using the keyword  <code>&apos;this&apos;</code>. 
                  In this case use  the <emphasis><property>&quot;oncomplete&quot;</property></emphasis> attribute as in the following example:
            </para>
            
            <programlisting role="XML"><![CDATA[<h:form id="form">
      <a4j:commandButton id="cbutton" action="director.rollCamera" onclick="this.disabled=true" oncomplete="document.getElementById('form:cbutton').disabled=false" /> 
</h:form>]]></programlisting>
            
            <para>
                  Common JSF navigation could be performed after an Ajax submit and partial rendering, but Navigation Case must be defined as <emphasis role="bold"><property>&lt;redirect/&gt;</property></emphasis> in order to avoid problems with some browsers.
            </para>
            
            <para>
                  As any Core Ajax component that sends Ajax requests and processes server responses the <emphasis role="bold"><property>&lt;a4j:commandButton&gt;</property></emphasis> has all attributes that provide the required behavior of requests (delay, limitation of submit area and rendering, etc.)
            </para>
            
            <note>
                  <title>Note:</title>
                  <para>
                        When attaching a JavaScript API function to the <emphasis role="bold"><property>&lt;a4j:commandButton&gt;</property></emphasis> with the help of the <emphasis role="bold"><property>&lt;rich:componentControl&gt;</property></emphasis> do not use the <emphasis><property>&quot;attachTo&quot;</property></emphasis> attribute of the last one. 
                        The attribute adds event handlers using <code>Event.observe</code> but <emphasis role="bold"><property>&lt;a4j:commandButton&gt;</property></emphasis> has no such event. 
                        The example below will not work:
                  </para>
                        <programlisting role="XML"><![CDATA[<a4j:commandButton value="Show Current Selection" reRender="table" action="#{dataTableScrollerBean.takeSelection}" id="button">
      <rich:componentControl attachTo="button" for="panel" event="oncomplete" operation="show" />
</a4j:commandButton>]]></programlisting>
                        
                        <para>
                              This one should work properly:
                        </para>
                  <programlisting role="XML"><![CDATA[<a4j:commandButton value="Show Current Selection" reRender="table" action="#{dataTableScrollerBean.takeSelection}" id="button">
      <rich:componentControl for="panel" event="oncomplete" operation="show" />
</a4j:commandButton>]]></programlisting>
            </note>
            
            <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>
    </section>
  
      <section>
            <title>Relevant resources links</title>
            <para>Vizit
                  <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/commandButton.jsf?c=commandButton">CommandButton demo</ulink> page at RichFaces 
                  live demo for examples of component usage and their sources.
            </para>
            <!--  
            <para>Useful articles:</para>
            <itemizedlist>
                  <listitem>
                        <para>
                             
                        </para>
                  </listitem>
            </itemizedlist>
            -->
      </section>
	
</chapter>