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>&lt;a4j:support&gt;</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>&lt;a4j:support&gt;</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>&lt;a4j:support&gt;</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>&lt;a4j:support&gt;</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>&lt;a4j:support&gt;</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>&lt;a4j:support&gt;</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>&lt;a4j:support&gt;</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>&lt;a4j:support&gt;</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>&lt;a4j:support&gt;</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>&quot;onkeyup&quot;</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>&lt;a4j:support&gt;</property></emphasis>. + </para> + </note> + + <para>With the help of <emphasis><property>&quot;onsubmit&quot;</property></emphasis> and <emphasis><property>&quot;oncomplete&quot;</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>&quot;ajaxSingle&quot;</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>&quot;limitToList&quot;</property></emphasis> is an attribute that allows to limit areas, which are updated after the responses; + only these components defined in the <emphasis><property>&quot;reRender&quot;</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>&quot;onkeyup&quot;</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>&lt;a4j:commandLink&gt;</property> - </emphasis>, <emphasis role="bold"> - <property>&lt;a4j:commandButton&gt;</property> - </emphasis>, <emphasis role="bold"> - <property>&lt;a4j:poll&gt;</property> - </emphasis> and others from RichFaces library are already - supplied with <emphasis role="bold"> - <property>&lt;a4j:support&gt;</property> - </emphasis> functionality and there is no necessity to add - the support to them. </para> - </note> - <para>With the help of <emphasis> - <property>&quot;onsubmit&quot;</property> - </emphasis> and <emphasis> - <property>&quot;oncomplete&quot;</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>&quot;ajaxSingle&quot;</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>&quot;limitToList&quot;</property> - </emphasis> is an attribute that allows - to limit areas, which are updated after - the responses. Only these components - defined in the <emphasis> - <property> - &quot;reRender&quot; - </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=&quot;true&quot;</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=&quot;true&quot;</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>&lt;h:messages&gt;</property> - </emphasis> is always updated (as it capturing all Ajax requests, - located in ajaxRendered <emphasis role="bold"> - <property>&lt;a4j:outputPanel&gt;</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=&quot;true&quot;</code> the only component - updated is the one with <code>id=&quot;test&quot;</code>.</para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">Limitation of requests - frequency and updates quantity after the - responses. </emphasis> - </para> - <para><emphasis> - <property>&quot;requestDelay&quot;</property> - </emphasis> is an attribute that defines a time - interval in seconds minimally permissible between - responses. </para> - <para><emphasis> - <property>&quot;eventsQueue&quot;</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>&quot;ignoreDupResponces&quot;</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>&quot;timeout&quot;</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>&lt;h:messages&gt;</property></emphasis> is always updated (as it capturing all Ajax requests, + located in ajaxRendered <emphasis role="bold"><property>&lt;a4j:outputPanel&gt;</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=&quot;true&quot;</code> the only component updated is the one with <code>id=&quot;test&quot;</code>. + </para> + + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">imitation of requests frequency and updates quantity after the responses</emphasis> + </para> + + <para> + <emphasis><property>&quot;requestDelay&quot;</property></emphasis> is an attribute that defines a time interval in seconds minimally permissible between responses; + </para> + + <para> + <emphasis><property>&quot;eventsQueue&quot;</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>&quot;ignoreDupResponces&quot;</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>&quot;timeout&quot;</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>&quot;process&quot;</property> - </emphasis> attribute usage you can find in the - <link linkend="process"> &quot;Decide what to process&quot; </link> guide section. </para> - </section> - - <section> - <title>Relevant resources links</title> - <para> - <ulink - url="http://livedemo.exadel.com/richfaces-demo/richfaces/support.jsf... - >On the component LiveDemo page</ulink> you can see the example of <emphasis - role="bold"> - <property>&lt;a4j:support&gt;</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>&quot;process&quot;</property></emphasis> attribute usage you can find in the &quot;<link linkend="process">Decide what to process</link>&quot; guide section. + </para> + </section> + + <section> + <title>Relevant resources links</title> + <para> + Visit <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/support.jsf... demo page</ulink> at RichFaces live demo for examples of component usage and their sources. + </para> + + </section> </chapter>