[richfaces-svn-commits] JBoss Rich Faces SVN: r14599 - 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
Thu Jun 11 13:48:45 EDT 2009
Author: atsebro
Date: 2009-06-11 13:48:45 -0400 (Thu, 11 Jun 2009)
New Revision: 14599
Modified:
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/support.desc.xml
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/support.xml
Log:
RF-7340: a4j:support component description review
Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/support.desc.xml
===================================================================
--- branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/support.desc.xml 2009-06-11 15:54:30 UTC (rev 14598)
+++ branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/support.desc.xml 2009-06-11 17:48:45 UTC (rev 14599)
@@ -9,8 +9,8 @@
</sectioninfo>
<title>Description</title>
- <para>The <emphasis role="bold">
- <property><a4j:support></property>
- </emphasis> component adds an Ajax support to any existing JSF component. It allows a component to generate asynchronous requests on the necessary event demand and with partial update of page content after a response incoming from the server.</para>
+ <para>The <emphasis role="bold"><property><a4j:support></property></emphasis> component enriches any existing JSF or RichFaces component with an Ajax capability by generating an asynchronous Ajax requests for them.
+ The requests are invoked by definite user activity and used for updating and re-rendering page contents partially after a response from server.
+ </para>
</section>
</root>
\ No newline at end of file
Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/support.xml
===================================================================
--- branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/support.xml 2009-06-11 15:54:30 UTC (rev 14598)
+++ branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/support.xml 2009-06-11 17:48:45 UTC (rev 14599)
@@ -36,31 +36,25 @@
</table>
<section>
- <title>Creating on a page</title>
- <para>To use a component, place <emphasis role="bold">
- <property><a4j:support></property>
- </emphasis> as nested to the component requesting Ajax functionality
- and specify an event of a parent component that generates Ajax request
- and the components to be rerendered after a response from the server.</para>
+ <title>Creating the Component with a Page Tag</title>
+ <para>To create the simplest variant on a page nest the <emphasis role="bold"><property><a4j:support></property></emphasis> into a component that is needed an Ajax functionality.
+ Specify an event that will trigger an Ajax request and the components to be rerendered after a response from server.</para>
<para>
<emphasis role="bold">Example:</emphasis>
</para>
<programlisting role="XML"><![CDATA[<h:inputText value="#{bean.text}">
- <a4j:support event="onkeyup" reRender="repeater"/>
+ <a4j:support event="onkeyup" reRender="repeater"/>
</h:inputText>
<h:outputText id="repeater" value="#{bean.text}"/>]]></programlisting>
- <para>On every keyup event generated by an input field, a form is submitted on
- the server with the help of Ajax and on a response coming from the
- server, element with <code>repeater</code> id, founded in a DOM tree
- is redrawn according to a new data from the response.</para>
+
+ <para>On every key-up event occuring inside the input field the <emphasis role="bold"><property><a4j:support></property></emphasis> generates an Ajax request that submits the whole Form.
+ The value for the <code>bean.text</code> will be updated in the model and the component with the <code>repeater</code> ID will be redrawn according to a new data after server responce.
+ </para>
</section>
- <section>
+
+ <section>
<title>Creating the Component Dynamically Using Java</title>
- <para>In order to add <emphasis role="bold">
- <property><a4j:support></property>
- </emphasis> in Java code you should add it as <emphasis>
- <property>facet</property>
- </emphasis>, not children:</para>
+ <para>In order to add the <emphasis role="bold"><property><a4j:support></property></emphasis> in Java code you should add it as <emphasis><property>facet</property></emphasis>, not children:</para>
<para>
<emphasis role="bold">Example:</emphasis>
</para>
@@ -74,195 +68,150 @@
inputText.getFacets().put("a4jsupport", ajaxSupport);
]]></programlisting>
</section>
- <section>
- <title>Key attributes and ways of usage</title>
- <para><emphasis role="bold">
- <property><a4j:support></property>
- </emphasis> addition is very similar to correspondent event
- redefinition of a component, i.e. </para>
+
+ <section>
+ <title>Details of Usage</title>
+ <para>
+ The <emphasis role="bold"><property><a4j:support></property></emphasis> component created on a page as following
+ </para>
+
+ <programlisting role="XML"><![CDATA[<h:inputText value="#{bean.text}">
+ <a4j:support event="onkeyup" reRender="output" action="#{bean.action}"/>
+</h:inputText>]]></programlisting>
+
+ <para>is decoded in HTML as</para>
+
+ <programlisting role="XML"><![CDATA[<input onkeyup="A4J.AJAX.Submit( Some request parameters )"/>]]></programlisting>
+
+ <para>The <emphasis><property>"onkeyup"</property></emphasis> event calls an utility RichFaces method that submits Form by creating special marks for the RichFaces filter informing that it is an Ajax request.
+ Any quantity of supports that define component behavior could be added to a component.
+ </para>
+
+ <note>
+ <para>A lot of RichFaces components comes with built-in Ajax support (read the Guide to find out what exactly) and have no need in the <emphasis role="bold"><property><a4j:support></property></emphasis>.
+ </para>
+ </note>
+
+ <para>With the help of <emphasis><property>"onsubmit"</property></emphasis> and <emphasis><property>"oncomplete"</property></emphasis> attributes the component allows using JavaScript before
+ (for request sending conditions checking) and after an Ajax response processing termination (for performance of user-defined activities on the client).
+ </para>
+
+ <para>
+ <emphasis role="bold">Example:</emphasis></para><programlisting role="XML"><![CDATA[<h:selectOneMenu value="#{bean.text}">
+ <f:selectItem itemValue="First Item" itemLabel="First Item"/>
+ <f:selectItem itemValue=" Second Item" itemLabel="Second Item"/>
+ <f:selectItem itemValue=" Third Item" itemLabel="Third Item"/>
+ <a4j:support event="onblur" reRender="panel" onsubmit="if(!confirm('Are you sure to change the option ?')) {form.reset(); return false;}" oncomplete="alert('Value succesfully stored')"/>
+</h:selectOneMenu>]]></programlisting>
+
<para>
- <emphasis role="bold">Example:</emphasis>
+ In example there is the condition checking (confirm) is used before request sending and message printing after the request processing is over.
</para>
- <programlisting role="XML"><![CDATA[...
-<h:inputText value="#{bean.text}">
- <a4j:support event="onkeyup" reRender="output" action="#{bean.action}"/>
-</h:inputText>
-...]]></programlisting>
- <para>Is decoded on a page as:</para>
-
- <para>
- <emphasis role="bold">Example:</emphasis>
+
+ <para>The component allows different Ajax request managing ways for its various optimization in particular conditions such as:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">limitation of the submit area and updating area for the request</emphasis>
+ </para>
+ <para>
+ <emphasis><property>"ajaxSingle"</property></emphasis> is an attribute that allows submission on the server only component sending a request as if the component presented on a separate form;
+ </para>
+
+ <para>
+ <emphasis><property>"limitToList"</property></emphasis> is an attribute that allows to limit areas, which are updated after the responses;
+ only these components defined in the <emphasis><property>"reRender"</property></emphasis>attribute are updated;
+ </para>
+ </listitem>
+ </itemizedlist>
</para>
- <programlisting role="XML"><![CDATA[
-<input onkeyup="A4J.AJAX.Submit( Some request parameters )"/>
-]]></programlisting>
- <para>As you see from the code, the <emphasis>
- <property>"onkeyup"</property>
- </emphasis> event calls a utility RichFaces method that submit a form
- creating a special marks for a filter informing that it is an Ajax
- request. Thus, any supports quantity could be added to every
- component, the supports define component behavior on these events. </para>
- <note>
- <para>The components: <emphasis role="bold">
- <property><a4j:commandLink></property>
- </emphasis>, <emphasis role="bold">
- <property><a4j:commandButton></property>
- </emphasis>, <emphasis role="bold">
- <property><a4j:poll></property>
- </emphasis> and others from RichFaces library are already
- supplied with <emphasis role="bold">
- <property><a4j:support></property>
- </emphasis> functionality and there is no necessity to add
- the support to them. </para>
- </note>
- <para>With the help of <emphasis>
- <property>"onsubmit"</property>
- </emphasis> and <emphasis>
- <property>"oncomplete"</property>
- </emphasis> attributes the component allows using JavaScript before
- (for request sending conditions checking) and after an Ajax response
- processing termination (for performance of user-defined activities on
- the client) </para>
+
<para>
- <emphasis role="bold">Example:</emphasis>
- </para>
- <programlisting role="XML"><![CDATA[<h:selectOneMenu value="#{bean.text}">
- <f:selectItem itemValue="First Item" itemLabel="First Item"/>
- <f:selectItem itemValue=" Second Item" itemLabel="Second Item"/>
- <f:selectItem itemValue=" Third Item" itemLabel="Third Item"/>
- <a4j:support event="onblur" reRender="panel" onsubmit="if(!confirm('Are you sure to change the option ?')) {form.reset(); return false;}" oncomplete="alert('Value succesfully stored')"/>
-</h:selectOneMenu>]]></programlisting>
- <para>In example there is the condition checking (confirm) is used before
- request sending and message printing after the request processing is
- over. </para>
- <para>The components allows different Ajax request managing ways for its various
- optimization in particular conditions such as: <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">Limitation of the
- submit area and updating area
- for the request.</emphasis>
- </para>
- <para><emphasis>
- <property>"ajaxSingle"</property>
- </emphasis> is an attribute that allows
- submission on the server only component
- sending a request, as if the component
- presented on a separate form. </para>
- <para><emphasis>
- <property>"limitToList"</property>
- </emphasis> is an attribute that allows
- to limit areas, which are updated after
- the responses. Only these components
- defined in the <emphasis>
- <property>
- "reRender"
- </property>
- </emphasis>attribute are updated.
- </para>
- </listitem>
- </itemizedlist></para>
- <para>
<emphasis role="bold">Example 1:</emphasis>
</para>
<programlisting role="XML"><![CDATA[<h:form>
- <h:inputText value="#{person.name}">
- <a4j:support event="onkeyup" reRender="test" ajaxSingle="true"/>
- </h:inputText>
- <h:inputText value="#{person.middleName}"/>
+ <h:inputText value="#{person.name}">
+ <a4j:support event="onkeyup" reRender="test" ajaxSingle="true"/>
+ </h:inputText>
+ <h:inputText value="#{person.middleName}"/>
</form>]]></programlisting>
- <para>In this example the request contains only the input component causes the
- request generation, not all the components contained on a form,
- because of <code>ajaxSingle="true"</code> usage. </para>
+
<para>
+ In this example the request contains only the input component causes the request generation and not all the components contained on a form (because <code>ajaxSingle="true"</code>).
+ </para>
+
+ <para>
<emphasis role="bold">Example 2:</emphasis>
</para>
- <programlisting role="XML"><![CDATA[<h:form>
- <a4j:outputPanel ajaxRendered="true">
- <h:messages/>
- </a4j:outputPanel>
- <h:inputText value="#{person.name}">
- <a4j:support event="onkeyup" reRender="test" limitToList="true"/>
- </h:inputText>
- <h:outputText value="#{person.name}" id="test"/>
+ <programlisting role="XML"><![CDATA[<h:form>
+ <a4j:outputPanel ajaxRendered="true">
+ <h:messages/>
+ </a4j:outputPanel>
+ <h:inputText value="#{person.name}">
+ <a4j:support event="onkeyup" reRender="test" limitToList="true"/>
+ </h:inputText>
+ <h:outputText value="#{person.name}" id="test"/>
</form>]]></programlisting>
- <para>In this example the component <emphasis role="bold">
- <property><h:messages></property>
- </emphasis> is always updated (as it capturing all Ajax requests,
- located in ajaxRendered <emphasis role="bold">
- <property><a4j:outputPanel></property>
- </emphasis>), except the case when a response is sent from the input
- component from the example. On sending this component marks that
- updating area is limited to the defined in it components, it means
- that on its usage with
- <code>limitToList="true"</code> the only component
- updated is the one with <code>id="test"</code>.</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">Limitation of requests
- frequency and updates quantity after the
- responses. </emphasis>
- </para>
- <para><emphasis>
- <property>"requestDelay"</property>
- </emphasis> is an attribute that defines a time
- interval in seconds minimally permissible between
- responses. </para>
- <para><emphasis>
- <property>"eventsQueue"</property>
- </emphasis> is an attribute for naming of the
- queue where the next response is kept in till its
- processing, but if the next event comes in till
- this time is over, the waiting event is taken
- away, replacing with a new one. </para>
- <para><emphasis>
- <property>"ignoreDupResponces"</property>
- </emphasis> is an attribute that allows to disable
- any updates on the client after an Ajax request if
- another Ajax request is already sent. </para>
- <para><emphasis>
- <property>"timeout"</property>
- </emphasis> is an attribute that allows to set a
- time interval in millisecond to define a maximum
- time period of response wait time. In case of the
- interval interaction, a new request is sent and
- the previous one is canceled. Postprocessing of a
- response isn't performed. </para>
- <para>
- <emphasis role="bold">Example:</emphasis>
- </para>
- <programlisting role="XML"><![CDATA[<h:form>
- <h:inputText value="#{person.name}">
- <a4j:support event="onkeyup" reRender="test" requestDelay="1000" ignoreDupResponces="true" eventsQueue="myQueue"/>
- </h:inputText>
- <h:outputText value="#{person.name}" id="test"/>
+
+ <para>
+ In this example the component <emphasis role="bold"><property><h:messages></property></emphasis> is always updated (as it capturing all Ajax requests,
+ located in ajaxRendered <emphasis role="bold"><property><a4j:outputPanel></property></emphasis>), except the case when a response is sent from the input component from the example.
+ On sending this component marks that updating area is limited to the defined in it components,
+ it means that on its usage with <code>limitToList="true"</code> the only component updated is the one with <code>id="test"</code>.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">imitation of requests frequency and updates quantity after the responses</emphasis>
+ </para>
+
+ <para>
+ <emphasis><property>"requestDelay"</property></emphasis> is an attribute that defines a time interval in seconds minimally permissible between responses;
+ </para>
+
+ <para>
+ <emphasis><property>"eventsQueue"</property></emphasis> is an attribute for naming of the queue where the next response is kept in till its processing,
+ but if the next event comes in till this time is over, the waiting event is taken away, replacing with a new one;
+ </para>
+
+ <para>
+ <emphasis><property>"ignoreDupResponces"</property></emphasis> is an attribute that allows to disable any updates on the client after an Ajax request if another Ajax request is already sent;
+ </para>
+
+ <para>
+ <emphasis><property>"timeout"</property></emphasis> is an attribute that allows to set a time interval in millisecond to define a maximum time period of response wait time.
+ In case of the interval interaction, a new request is sent and the previous one is canceled.
+ Postprocessing of a response isn't performed.
+ </para>
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[<h:form>
+ <h:inputText value="#{person.name}">
+ <a4j:support event="onkeyup" reRender="test" requestDelay="1000" ignoreDupResponces="true" eventsQueue="myQueue"/>
+ </h:inputText>
+ <h:outputText value="#{person.name}" id="test"/>
</form>]]></programlisting>
- <para>This example clearly shows mentioned above attributes.
- If quick typing in a text field happens, every
- next requests sending is delayed for a second and
- requests quantity is reduced. The requests are
- kept in the queue till its the sending. Moreover,
- if the next request is already sent, the
- rerendering after the previous request is banned,
- and it helps to avoid unnecessary processing on
- the client.</para>
- </listitem>
- </itemizedlist>
- <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>Relevant resources links</title>
- <para>
- <ulink
- url="http://livedemo.exadel.com/richfaces-demo/richfaces/support.jsf?c=support"
- >On the component LiveDemo page</ulink> you can see the example of <emphasis
- role="bold">
- <property><a4j:support></property>
- </emphasis> usage and sources for the given example. </para>
- </section>
+
+ <para>This example clearly shows mentioned above attributes.
+ If quick typing in a text field happens, every next requests sending is delayed for a second and requests quantity is reduced.
+ The requests are kept in the queue till its the sending.
+ Moreover, if the next request is already sent, the rerendering after the previous request is banned, and it helps to avoid unnecessary processing on the client.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <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>Relevant resources links</title>
+ <para>
+ Visit <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/support.jsf?c=support"><a4j:support> demo page</ulink> at RichFaces live demo for examples of component usage and their sources.
+ </para>
+
+ </section>
</chapter>
More information about the richfaces-svn-commits
mailing list