[richfaces-svn-commits] JBoss Rich Faces SVN: r14640 - branches/community/3.3.X/docs/userguide/en/src/main/docbook/included.
richfaces-svn-commits at lists.jboss.org
richfaces-svn-commits at lists.jboss.org
Wed Jun 17 09:01:58 EDT 2009
Author: atsebro
Date: 2009-06-17 09:01:57 -0400 (Wed, 17 Jun 2009)
New Revision: 14640
Modified:
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/commandButton.desc.xml
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/commandButton.xml
Log:
RF-7343: a4j:commandButton component description review
Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/commandButton.desc.xml
===================================================================
--- branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/commandButton.desc.xml 2009-06-17 11:18:41 UTC (rev 14639)
+++ branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/commandButton.desc.xml 2009-06-17 13:01:57 UTC (rev 14640)
@@ -7,10 +7,20 @@
</keywordset>
</sectioninfo>
<title>Description</title>
- <para>The <emphasis role="bold">
- <property><a4j:commandButton></property>
- </emphasis>component is very similar to the<emphasis role="bold">
- <property><h:commandButton></property>
- </emphasis>component, the only difference is that an Ajax form submit is generated on a click and it allows dynamic rerendering after a response comes back. It's not necessary to plug any support into the component, as Ajax support is already built in.</para>
+ <para>
+ The <emphasis role="bold"><property><a4j:commandButton></property></emphasis>component is very similar to JSF <emphasis role="bold"><property><h:commandButton></property></emphasis>, the only difference is that an Ajax form submit is generated on a click and it allows dynamic rerendering after a response comes back.
+ </para>
+
+ <figure>
+ <title>
+ The <emphasis role="bold"><property><a4j:commandButton></property></emphasis> component rendered in Blue Sky skin
+ </title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/commandButton_init.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
</section>
</chapter>
\ No newline at end of file
Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/commandButton.xml
===================================================================
--- branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/commandButton.xml 2009-06-17 11:18:41 UTC (rev 14639)
+++ branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/commandButton.xml 2009-06-17 13:01:57 UTC (rev 14640)
@@ -34,77 +34,105 @@
</tbody>
</tgroup>
</table></para>
- <section>
- <title>Creating on a page</title>
- <para>The simplest tag usage example:</para>
- <para>
- <emphasis role="bold">Example:</emphasis>
- </para>
- <programlisting role="XML"><![CDATA[...
-<a4j:commandButton reRender="someData" action="#{bean.action1}" value="Link"/>
-...]]></programlisting>
-
- </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;
+
+ <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>"action"</code> method performance,
+ and rendering the component with <code>"someData"</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>Key attributes and ways of usage</title>
- <para><emphasis role="bold"><property><a4j:commandButton></property></emphasis> is used in the same way as <emphasis role="bold"><property><h:commandButton></property></emphasis>, but with definition of the area that is updated after the response comes back from the server.</para>
- <para>This definition of the component provides a link, a click on the link causes an Ajax form submit on the server, <code>action1</code> method performance, and rendering of the component with <code>someData</code> id after the response comes back from the server.</para>
- <para>The component <emphasis role="bold"><property><a4j:commandButton></property></emphasis> placed on a page generates the following HTML code:</para>
- <programlisting role="XML"><![CDATA[...
-<input type="submit" onclick="A4J.AJAX.Submit(...request parameters);return false;" value="sort"/>
-...]]></programlisting>
- <para>Hence, the utility method <code>A4J.AJAX.Submit</code> is called on a click, the method performs Ajax request as the <emphasis role="bold"><property><a4j:support></property></emphasis> component</para>
- <note>
- <title>Note:</title>
- <para>AJAX support is built in and it's not necessary to add nested <emphasis role="bold"><property><a4j:support></property></emphasis> to the component.</para>
- </note>
+ </section>
+
+ <section>
+ <title>Details of Usage</title>
+ <para>
+ The <emphasis role="bold"><property><a4j:commandButton></property></emphasis> component is used in the same way as JSF <emphasis role="bold"><property><h:commandButton></property></emphasis>.
+ The difference is that in case of <emphasis role="bold"><property><a4j:commandButton></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><a4j:commandButton></property></emphasis> already has Ajax support built-in and there is no need to add <emphasis role="bold"><property><a4j:support></property></emphasis>.
+ </para>
+ </note>
+
<para>
- The usage of the keyword <code>'this'</code> in JavaScript code in the <emphasis><property>"oncomplete"</property></emphasis> attribute
- depends on the location of <emphasis role="bold"><property><a4j:commandButton></property></emphasis>. If the <property>commandButton</property> is situated outside the re-rendered region
- you can use keyword <property>'this'</property> as in the following example:
+ The usage of the keyword <code>'this'</code> in JavaScript code in the value for <emphasis><property>"oncomplete"</property></emphasis> attribute depends on the location of <emphasis role="bold"><property><a4j:commandButton></property></emphasis>.
+ If the <emphasis role="bold"><property><a4j:commandButton></property></emphasis> is situated outside the re-rendered region it is possible to use keyword <property>'this'</property> 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="this.disabled=false" />
-</h:form>
-...]]></programlisting>
- <para>
- Otherwise if the <property>commandButton</property> contained in re-rendered region
- the <emphasis><property>"oncomplete"</property></emphasis> attribute has a problem obtaining a reference of the <property>commandButton</property> object
- when using the keyword <code>'this'</code>. In this case you can use the <emphasis><property>"oncomplete"</property></emphasis> attribute as in the following example:
+ <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><a4j:commandButton></property></emphasis> is contained in a re-rendered region
+ than the <emphasis><property>"oncomplete"</property></emphasis> attribute has a problem with obtaining a reference of the
+ <property>commandButton</property> object when using the keyword <code>'this'</code>.
+ In this case use the <emphasis><property>"oncomplete"</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><redirect/></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><a4j:commandButton></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>"process"</property></emphasis> attribute usage you can find in the "<link linkend="process">Decide what to process</link>" guide section.
</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><redirect/></property></emphasis> in order to avoid problems with some browsers.</para>
- <para>As any Core Ajax component sending Ajax requests and processing server responses
- <emphasis role="bold"><property><a4j:commandButton></property></emphasis> has all attributes described above
- (see <emphasis role="bold"><property><a4j:support></property></emphasis> <link linkend="support">chapter</link>)
- that provide the required behavior of requests sending (delay, limitation of submit area and rendering, and etc.)</para>
- <para>
- Information about the <emphasis><property>"process"</property></emphasis> attribute usage you can find <link linkend="process">" Decide what to process " </link> guide section.
- </para>
</section>
- <section>
- <title>Relevant resources links</title>
- <para>
- <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/commandButton.jsf?c=commandButton">On the component LiveDemo page</ulink> you can see the example of <emphasis role="bold"
- ><property><a4j:commandButton></property></emphasis> usage and sources for the given example.
- </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>
\ No newline at end of file
More information about the richfaces-svn-commits
mailing list