<section role="NotInToc" id="a4j_form">
    <title>
        &lt;
        a4j:form
        &gt;
        <emphasis role="since">
            <superscript>available since
                <emphasis role="version">3.0.0</emphasis>
            </superscript>
        </emphasis>
    </title>
    <section>
        <sectioninfo>
            <keywordset>
                <keyword>a4j:form</keyword>
                <keyword>component</keyword>
            </keywordset>
        </sectioninfo>
        <title>Description</title>
        <para>
            The
            <emphasis role="bold">
                <property>&lt;a4j:form&gt;</property>
            </emphasis>
            component enhances functionality of the standard JSF
            <emphasis role="bold">
                <property>&lt;h:form&gt;</property>
            </emphasis>
            component with possibility of default Ajax submission
            and fixes the problem with
            <emphasis role="bold">
                <property>&lt;h:commandLink&gt;</property>
            </emphasis>
            generation inside the form.
        </para>
    </section>
    <section>
        <title>Details of Usage</title>
        <para>
            Along with
            <emphasis role="bold">
                <property>a4j:htmlCommandLink</property>
            </emphasis>
            ,
            <emphasis role="bold">
                <property>&lt;a4j:form&gt;</property>
            </emphasis>
            component fixes the problem of
            <emphasis role="bold">
                <property>&lt;h:commandLink&gt;</property>
            </emphasis>
            component that cannot be re-rendered
            without re-rendering the whole form it belongs to. For the further details see the
            <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/form.jsf?c=form">Ajax Form Usage</ulink>
            page at RichFaces Livedemo.
        </para>

        <para>
            The
            <emphasis role="bold">
                <property>&lt;a4j:form&gt;</property>
            </emphasis>
            component adds extra functionality to non-Ajax action/command components: submission is performed
            via Ajax when
            <emphasis>
                <property>&quot;ajaxSubmit&quot;</property>
            </emphasis>
            attribute set to &quot;true&quot;.
        </para>
        <para>
            If the
            <emphasis role="bold">
                <property>&lt;a4j:form&gt;</property>
            </emphasis>
            component
            works in an Ajax mode, the standard Ajax attributes such as
            <emphasis>
                <property>&quot;reRender&quot;</property>
            </emphasis>
            ,
            <emphasis>
                <property>&quot;limitToList&quot;</property>
            </emphasis>
            ,
            <emphasis>
                <property>&quot;requestDelay&quot;</property>
            </emphasis>
            , etc. can be used.
        </para>
        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>
        <programlisting role="XML"><![CDATA[...
<a4j:form ajaxSubmit="true" reRender="name">
    <h:panelGrid>
        <h:commandButton value="Set Local Name to John (Ajax)" action="#{userBean.nameItJohn}" />
        <h:outputText id="name" value="Name:#{userBean.name}" />
    </h:panelGrid>
</a4j:form>
...]]></programlisting>
        <para>
            Here is a managed bean:
        </para>
        <programlisting role="JAVA"><![CDATA[...
public class UserBean {
	private String name="";

    public String nameItJohn() {
		setName("John");
		return null;
	}
    public String getName() {
		return this.name;
	}
	public void setName(String name) {
		this.name = name;
	}
}
...]]></programlisting>
        <para>
            In the example above the
            <code>ajaxSubmit=&quot;true&quot;</code>,
            so all standard action components on this form become ajaxable.
            The
            <emphasis>
                <property>&quot;reRender&quot;</property>
            </emphasis>
            attribute contains an Id of component for
            re-rendering after an Ajax response.
        </para>
        <tip>
            <title>Tip:</title>
            <para>
                If you have
                <emphasis role="bold">
                    <property>&lt;h:commandButton&gt;</property>
                </emphasis>
                or
                <emphasis role="bold">
                    <property>&lt;h:commandLink&gt;</property>
                </emphasis>
                inside a form, they work as
                <emphasis role="bold">
                    <property>&lt;a4j:commandButton&gt;</property>
                </emphasis>
                .
            </para>
        </tip>
        <note>
            <title>Note:</title>
            <para>
                You should not use
                <emphasis role="bold">
                    <property>&lt;a4j:form&gt;</property>
                </emphasis>
                component with
                <code>ajaxSubmit="true"</code>
                if it contains other Ajax command components.
                Also, due to the security reason, file upload form element cannot be convertible to the be ajaxable.
            </para>
        </note>
    </section>
    <section>
        <title>Reference Data</title>
        <para>
            <ulink url="&tlddoc;a4j/form.html">Table of
                &lt;a4j:form&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.Form</entry>
                    </row>
                    <row>
                        <entry>component-family</entry>
                        <entry>javax.faces.Form</entry>
                    </row>
                    <row>
                        <entry>component-class</entry>
                        <entry>org.ajax4jsf.component.html.AjaxForm</entry>
                    </row>
                    <row>
                        <entry>renderer-type</entry>
                        <entry>org.ajax4jsf.FormRenderer</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </section>
    <section>
        <title>Relevant Resources Links</title>
        <para>
            Visit
            <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/form.jsf?c=form">Ajax Form</ulink>
            page
            at RichFaces Livedemo for examples of component usage and their sources.
        </para>
        <para>
            For additional information about attributes of this component read
            <ulink
                url="http://livedemo.exadel.com/richfaces-demo/richfaces/ajaxAttributes.jsf?c=ajaxattributes">'Ajax
            Attribute</ulink> section.
        </para>
    </section>
</section>
