Author: artdaw Date: 2009-09-08 13:44:21 -0400 (Tue, 08 Sep 2009) New Revision: 15498 Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/a4j_form.xml Log: https://jira.jboss.org/jira/browse/RF-7275 - a4j:form section restructuring Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/a4j_form.xml =================================================================== --- branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/a4j_form.xml 2009-09-08 16:02:37 UTC (rev 15497) +++ branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/a4j_form.xml 2009-09-08 17:44:21 UTC (rev 15498) @@ -1,140 +1,214 @@ <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> + <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 is very similar to JSF <emphasis role="bold"> - <property>&lt;h:form&gt;</property> - </emphasis> the only difference is in generation of links inside and possibility of default Ajax submission. + 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> - The difference with the original component is that all hidden fields - required for command links are always rendered and it doesn't depend - on links rendering on the initial page. It solves the problem with - invalid links that weren't rendered on a page immediately, but after - some Ajax request.</para> - <para>Beginning with release 1.0.5 additional attributes that make this form - variant universal have appeared. </para> - <para> If <emphasis> - <property>"ajaxSubmit"</property> - </emphasis> attribute is true, it becomes possible to set Ajax - submission way for any components inside with the help of the javascript - <code>A4J.AJAX.Submit(...)</code>call. In this case, the <emphasis> - <property>"reRender"</property> - </emphasis> attribute contains a list of Ids of components defined for - re-rendering. 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 the form, they work as <emphasis role="bold"> - <property>&lt;a4j:commandButton&gt;</property> - </emphasis>. </para> - <para> - <emphasis role="bold">Example:</emphasis> - </para> - <programlisting role="XML"><![CDATA[<a4j:form id="helloForm" ajaxSubmit="true" reRender="table"> - ... - <t:dataTable id="table"... > - ... - </t:dataTable> - ... - <t:datascroller for="table"... > - ... - </t:datascroller> - ... + </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 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> - This example shows that in order to make <emphasis role="bold"> - <property>&lt;t:datascroller&gt;</property> - </emphasis> submissions to be Ajax ones it's required only to place this <emphasis role="bold"> - <property>&lt;t:datascroller&gt;</property> - </emphasis> into <emphasis role="bold"> - <property>&lt;a4j:form&gt;</property> - </emphasis>. - In the other case it is necessary to redefine renders for its child links elements that are defined as <emphasis role="bold"> - <property>&lt;h:commandLink&gt;</property> - </emphasis> and can't be made Ajax ones with using e.g. <emphasis role="bold"> - <property>&lt;a4j:support&gt;</property> - </emphasis>. - </para> - <para> - With the help of <emphasis> - <property>"limitToList"</property> - </emphasis> attribute you can limit areas, which are updated after the responses. - If <emphasis> - <property>"limitToList"</property> - </emphasis> is true, only the reRender attribute is taken in account. - Therefore, if you use blocks of text wrapped with <emphasis role="bold"> - <property>&lt;a4j:outputPanel&gt;</property> - </emphasis> and <code>ajaxRendered= "true"</code>, blocks of text are ignored. - </para> - <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> - </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=... at RichFaces Livedemo for examples of component usage and their sources. - a</para> - </section> +...]]></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</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/ajaxAttribu... + Attribute' section</ulink>. + </para> + </section> </section> \ No newline at end of file