<?xml version='1.0' encoding='UTF-8'?>
<chapter>
  <chapterinfo>
    <keywordset>
      <keyword>a4j:commandLink</keyword>
    </keywordset>
  </chapterinfo>
      <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.CommandLink</entry>
            </row>
            <row>
              <entry>component-family</entry>
              <entry>javax.faces.Command </entry>
            </row>
            <row>
              <entry>component-class</entry>
              <entry>org.ajax4jsf.component.html.HtmlAjaxCommandLink</entry>
            </row>
            <row>
              <entry>renderer-type</entry>
              <entry>org.ajax4jsf.components.AjaxCommandLinkRenderer </entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    
    <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="CL_example">
        <emphasis role="bold">Example:</emphasis>
      </para>
          <programlisting role="XML"><![CDATA[<a4j:commandLink value="Follow this link" reRender="some ID" action="#{bean.action}" />]]></programlisting>
    <para>
          The example above creates a link 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.HtmlAjaxCommandLink;
...
HtmlAjaxCommandLink myLink = new HtmlAjaxCommandLink();
...
]]></programlisting>
    </section>
    <section>
          <title>Details of Usage</title>
      <para>
            The <emphasis role="bold"><property>&lt;a4j:commandLink&gt;</property></emphasis> component is used in the same way as JSF <emphasis role="bold"><property>&lt;h:commandLink&gt;</property></emphasis>. 
            The difference is that in case of <emphasis role="bold"><property>&lt;a4j:commandLink&gt;</property></emphasis> the components to be updated should be specified.
            In this chapter we will use the code from <link linkend="RichFacesGreeterindex">RichFaces Greeter</link> and change there <emphasis role="bold"><property>&lt;a4j:commandButton&gt;</property></emphasis> to <emphasis role="bold"><property>&lt;a4j:commandLink&gt;</property></emphasis>:
      </para>
          
          <programlisting role="XML"><![CDATA[...
<a4j:commandLink value="Get greeting" reRender="greeting" />
...]]></programlisting>
          
          <para>
                It&apos;s not necessary to add nested <emphasis role="bold"><property>&lt;a4j:support&gt;</property></emphasis> as the <emphasis role="bold"><property>&lt;a4j:commandLink&gt;</property></emphasis> has an Ajax support already built-in. 
                As a result of our changes we will get a form with &quot;Get greeting&quot; link instead of the button:
          </para>
          <figure>
                <title>
                      The RicjFaces greeter with <emphasis role="bold"><property>&lt;a4j:commandLink&gt;</property></emphasis>
                </title>
                
                <mediaobject>
                      <imageobject>
                            <imagedata fileref="images/commandLink_init.png"/>
                      </imageobject>
                </mediaobject>
          </figure>
                  
          <para>
                The example <link linkend="CL_example">above</link> generates the following HTML code:
          </para>
          
          <programlisting role="XML"><![CDATA[<a href="#" onclick="A4J.AJAX.Submit(?"request parameters"); return false;"><span>Get greeting</span></a>]]></programlisting>
          
          <para>
                If you click on the generated anchor the utility method <code>A4J.AJAX.Submit()</code> will be fired. 
                
          </para> 
          
          <note>
                <title>Note:</title>
                <para>
                      Common JSF navigation could be performed after 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>
          </note>
          
          <para>
                As any Core Ajax component that sends Ajax requests and processes server responses the <emphasis role="bold"><property>&lt;a4j:commandLink&gt;</property></emphasis> has all attributes that provide the required behavior of requests (delay, limitation of submit area and rendering, etc.)
          </para>
          
      <para>
            Information about the <emphasis><property>&quot;process&quot;</property></emphasis> attribute usage you can find &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/commandLink.jsf?c=commandLink">CommandLink demo</ulink> page at RichFaces 
		live demo for examples of component usage and their sources.
	</para>
	<para>Useful articles:</para>
	<itemizedlist>
	  <listitem>
	    <para>
	      <ulink url="http://www.jboss.org/community/docs/DOC-11850">How to use "window.confirm" JavaScript with &lt;a4j:commandLink&gt; "onclick" attribute</ulink> 
		  in RichFaces cookbook at JBoss portal.
		</para>
	  </listitem>
	</itemizedlist>
  </section>
  
</chapter>