Author: atsebro Date: 2009-06-04 13:28:01 -0400 (Thu, 04 Jun 2009) New Revision: 14511 Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/region.desc.xml branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/region.xml Log: RF-7303: Verifying the Description of the <a4j:region> component Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/region.desc.xml =================================================================== --- branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/region.desc.xml 2009-06-04 17:27:01 UTC (rev 14510) +++ branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/region.desc.xml 2009-06-04 17:28:01 UTC (rev 14511) @@ -1,18 +1,19 @@ <?xml version='1.0' encoding='UTF-8'?> -<root> <section> - <sectioninfo> - <keywordset> - <keyword>a4j:region</keyword> - <keyword>component</keyword> - </keywordset> - </sectioninfo> - -<title>Description</title> - <para> -The <emphasis role="bold"> -<property>&lt;a4j:region&gt;</property> -</emphasis> component defines an area that is decoded on the server after Ajax submission. -</para> + <sectioninfo> + <keywordset> + <keyword>a4j:region</keyword> + <keyword>component</keyword> + </keywordset> + </sectioninfo> + + <section> + <title>Description</title> + <para> + The <emphasis role="bold"><property>&lt;a4j:region&gt;</property></emphasis> component specifies the part of the component tree to be processed on server. + If no <emphasis role="bold"><property>&lt;a4j:region&gt;</property></emphasis> is defined the whole View functions as a region. + </para> + </section> + </section> -</root> + Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/region.xml =================================================================== --- branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/region.xml 2009-06-04 17:27:01 UTC (rev 14510) +++ branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/region.xml 2009-06-04 17:28:01 UTC (rev 14511) @@ -1,11 +1,12 @@ <?xml version='1.0' encoding='UTF-8'?> -<chapter> - <chapterinfo> - <keywordset> - <keyword>a4j:region</keyword> - </keywordset> - </chapterinfo> - <table> +<section> + <chapterinfo> + <keywordset> + <keyword>a4j:region</keyword> + </keywordset> + </chapterinfo> + + <table> <title>Component identification parameters </title> <tgroup cols="2"> <thead> @@ -35,31 +36,56 @@ </tgroup> </table> - <section> - <title>Creating on a page</title> - <para>Here is an example of the region decoding on a page. </para> - <programlisting role="XML"><![CDATA[<a4j:region> - <h:inputText value="#{userBean.name}"> - <a4j:support event="onkeyup" reRender="outname" /> - </h:inputText> + <section> + <title>Creating the Component with a Page Tag</title> + <para>To create the simplest variant of the <emphasis role="bold"><property>&lt;a4j:region&gt;</property></emphasis> component on a page use the following syntax:</para> + <programlisting role="XML"><![CDATA[<a4j:region> + ... </a4j:region>]]></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.HtmlAjaxRegion; + </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.HtmlAjaxRegion; ... HtmlAjaxRegion newRegion = new HtmlAjaxRegion(); ...]]></programlisting> - </section> - <section> - <title>Key attributes and ways of usage</title> - <para>The region is a component used for manipulation with components sent to the server. It sets particular processing parameters for an area on the server, i.e. the region deals with data input on the server and has no direct impact on output. To read more on the components responsible for out, see <ulink url="http://java.sun.com/javaee/javaserverfaces/reference/index.html... official documentation</ulink>. -</para> - <para>The region marks an area page that is decoded on the server. In most cases it is not necessary to use the region, as ViewRoot is a default region. This component helps to reduce data quantity processed by the server, but the region doesn&apos;t influence on the standard submission rules. It means that:<itemizedlist> + </section> + + <section> + <title>Details of Usage</title> + <para> + The <emphasis role="bold"><property>&lt;a4j:region&gt;</property></emphasis> component specifies the part of the component tree to be processed on server. + The processing includes data handling during decoding, conversion, validation and model update. + Note that the whole Form is still submitted but only part taken into region will be processed. + + </para> + + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="XML"><![CDATA[<h:form> + ... + <a4j:region> + <a4j:commandLink/> + </a4j:region> + ... +<h:form>]]></programlisting> + + <para>The whole Form on the schematic listing above will be submitted by request invoked with the <emphasis role="bold"><property>&lt;a4j:commandLink&gt;</property></emphasis>. + The only part that is going to be processed on the server is enclosed with <emphasis role="bold"><property>&lt;a4j:region&gt;</property></emphasis> and <emphasis role="bold"><property>&lt;/a4j:region&gt;</property></emphasis> tags. + If no <emphasis role="bold"><property>&lt;a4j:region&gt;</property></emphasis> is defined the whole View functions as a region. + </para> + + <!-- <para>The region is a component used for manipulation with components sent to the server. + It sets particular processing parameters for an area on the server, i.e. the region deals with data input on the server and has no direct impact on output. + To read more on the components responsible for out, see <ulink url="http://java.sun.com/javaee/javaserverfaces/reference/index.html... official documentation</ulink>. + </para> + + <para>The region marks an area page that is decoded on the server. This component helps to reduce data quantity processed by the server, but the region doesn&apos;t influence on the standard submission rules. It means that:<itemizedlist> <listitem><para> The area that is to be submitted onto the server should be embedded in <emphasis role="bold"> <property>&lt;h:form&gt;</property>/<property>&lt;a4j:form&gt;</property> @@ -69,86 +95,112 @@ The whole form is submitted on Ajax response and not a region that request is performed from. </para></listitem> </itemizedlist></para> + --> + + <para>The regions could be nested. Server picks out and decodes only the region, which contains the component that initiates the request.</para> <para><emphasis role="bold">Example:</emphasis></para> - <programlisting role="XML"><![CDATA[<h:form id="form1"> + <programlisting role="XML"><![CDATA[<h:form> + ... <a4j:region> - <a4j:commandLink reRender="someID" value="Link" id="link1"/> - <!--..Some content that will be decoded on server after Ajax request.--> - </a4j:region> + <a4j:commandLink value="Link 1" id="link1"/> + <a4j:region> + <a4j:commandLink value="Link 2" id="link2"/> + </a4j:region > + </a4j:region> + ... <h:form>]]></programlisting> - <para>Hence, the <emphasis role="bold"> - <property>&lt;a4j:commandLink&gt;</property> - </emphasis> request generation causes full <code>form1</code> form submission onto the server, the only difference is that a component tree part decoded on the serve is the part included into the region.</para> - <para>The regions could be nested in any order, the server picks out and decodes only the region, which contains a particular component that sends a request.</para> - <para><emphasis role="bold">Example:</emphasis></para> - <programlisting role="XML"><![CDATA[<a4j:region> - <a4j:commandLink reRender="someID" value="Link" id="link1"/> - <a4j:region> - <a4j:commandLink reRender="someID" value="Link" id="link2"/> - <!--..Some content that will be decoded on server after Ajax request.--> - </a4j:region > - <!--..Some content that will be decoded on server after Ajax request.--> -</a4j:region >]]></programlisting> - <para>Therefore, the external region is decoded for the <code>&quot;link1&quot;</code> and the internal one is decoded for the <code>&quot;link2&quot;</code>.</para> - <para>RichFaces allows setting Ajax responses rendering directly basing on component tree nodes without referring to the JSP (XHTML) page code. It could be defined by<emphasis><property> &quot;selfRendered&quot; </property></emphasis>attribute setting to &quot;true&quot; on <emphasis role="bold"> - <property>&lt;a4j:region&gt;</property> - </emphasis> and could help considerably speed up a response output. However, this rapid processing could cause missing of transient components that present on view and don&apos;t come into a component tree as well as omitting of <emphasis role="bold"> - <property>&lt;a4j:outputPanel&gt;</property> - </emphasis> usage described below. + <para> + The external region is decoded for <code>link1</code> and the internal one is decoded for <code>link2</code>. + </para> + + <para> + The <emphasis><property>&quot;renderRegionOnly&quot;</property></emphasis> attribute is used when it is necessary to exclude all the components from the outside of the region from updating on the page during Renderer Response phase. + Such manipulation allows region to be passed straight into Encode and reduces performance time. + This optimization should be implemented carefully because it doesn&apos;t allow data from the outside of active region to be updated. + </para> + + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="XML"><![CDATA[<h:form> + ... + <a4j:region renderRegionOnly="true"> + <a4j:commandLink value="Link 1" id="link1"/> + </a4j:region> + ... + <a4j:region renderRegionOnly="false"> + <a4j:commandLink value="Link 2" id="link2"/> + </a4j:region> + ... +</h:form>]]></programlisting> + <para> + On the example above the first region only will be updated if <code>link1</code> initiates a request. + When a request is initiated by <code>link2</code> both regions will be updated. + In this case search for components to include them into Renderer Response will be performed on the whole component tree. + </para> + + + <para> + <property>RichFaces</property> allows setting Ajax responses rendering basing on component tree nodes directly, without referring to the JSP (XHTML) code. + This speeds up a response output considerably and could be done by setting the <emphasis role="bold"><property>&lt;a4j:region&gt;</property></emphasis> <emphasis><property>&quot;selfRendered&quot;</property></emphasis> attribute to &quot;true&quot;. + However, this rapid processing could cause missing of transient components that present on view and don&apos;t come into a component tree as well as omitting of <emphasis role="bold"><property>&lt;a4j:outputPanel&gt;</property></emphasis> usage described below. </para> - <para><emphasis role="bold">Example:</emphasis></para> + <para> + <emphasis role="bold">Example:</emphasis> + </para> <programlisting role="XML"><![CDATA[<a4j:region selfRendered ="true"> - <a4j:commandLink reRender="someID" value="Link" id="link1"/> - <!--..Some content with HTML used ("br","h1" and other tags used)--> -</a4j:region >]]></programlisting> - <para>In this case, the processing is quicker and going on without referring to a page code, but the HTML code that isn&apos;t saved in a component tree could be lost. Thus, this optimization should be very carefully performed and a usage of the additional components RichFaces (<emphasis role="bold"><property>&lt;a4j:outputPanel&gt;</property></emphasis>) is required. </para> - <para>The processing could be also accelerated if a region decoded for the processing passes straight away into Encode. But to update some data out of the region or on another region, use the <emphasis > - <property>&quot;renderRegionOnly&quot;</property> - </emphasis> - attribute set to &quot;false&quot; (&quot;true&quot; on default) to change this behaviour.</para> - <para><emphasis role="bold">Example:</emphasis></para> - <programlisting role="XML"><![CDATA[<a4j:region renderRegionOnly="true"> - <a4j:commandLink reRender="someID2" value="Link1" id="link1"/> - <h:panelGroup id="someId1" /> -</a4j:region> -<a4j:region renderRegionOnly="false"> - <a4j:commandLink reRender="someID1" value="Link2" id="link2"/> - <h:panelGroup id="someId1" /> + <a4j:commandLink value="Link" id="link"/> + <!--Some HTML content--> </a4j:region>]]></programlisting> - <para>This example shows that one of the regions is decoded when a link is used inside. Nevertheless, - if after processing the <code>&quot;link1&quot;</code> is clicked, the first region passes into Encode as a root - region and encode performance time is reduced. This optimization doesn&apos;t allow data update out of the - region and should be implemented very carefully. The data out of the region described with <code>renderRegionOnly=&quot;false&quot;</code> is updated successfully. - </para> + <para>In this case the processing is quicker and going on without referring to the page code. + The HTML code is not saved in a component tree and could be lost. + Thus, such optimization should be performed carefully and additional <property>RichFaces</property> components usage (e.g. <emphasis role="bold"><property>&lt;a4j:outputPanel&gt;</property></emphasis>) is required.</para> + + + <para> - Starting from version 3.2.0 <emphasis role="bold"><property>&lt;a4j:region&gt;</property></emphasis> can be used inside any iterative component - (e.g. <emphasis role="bold"><property>&lt;rich:column&gt;</property></emphasis>, <emphasis role="bold"><property>&lt;rich:scrollableDataTable&gt;</property></emphasis>) - and just re-render the components from the same row without updating the whole table - and without any additional listeners. + Starting from <property>RichFaces 3.2.0</property> the <emphasis role="bold"><property>&lt;a4j:region&gt;</property></emphasis> can be used together with iterative components (e.g. <emphasis role="bold"><property>&lt;rich:column&gt;</property></emphasis> or <emphasis role="bold"><property>&lt;rich:scrollableDataTable&gt;</property></emphasis>, etc.). + It became possible to re-render a particular row in a table without updating the whole table and without any additional listeners. </para> <para><emphasis role="bold">Example:</emphasis></para> <programlisting role="XML"><![CDATA[<rich:column> - <a4j:region> - <a4j:commandLink reRender="out"/> - </a4j:region> + <a4j:region> + <a4j:commandLink reRender="out"/> + </a4j:region> </rich:column> <rich:column> - <h:outputText id="out"> + <h:outputText id="out"> </rich:column>]]></programlisting> - </section> + + <para> + In most cases there is no need to use the <emphasis role="bold"><property>&lt;a4j:region&gt;</property></emphasis> as <code>ViewRoot</code> is a default one. + </para> + + + </section> + + + + <section> <title>Relevant resources links</title> <para>Visit <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/region.jsf?... demo page</ulink> at RichFaces live demo for examples of component usage and their sources. </para> - <para>Useful articles:</para> + <para>Useful articles and examples:</para> <itemizedlist> <listitem> <para> - <ulink url="http://www.jboss.org/community/docs/DOC-11866">&lt;... and two &lt;h:inputTexts&gt;</ulink> - in RichFaces cookbook at JBoss portal. + <ulink url="http://www.jboss.org/community/docs/DOC-11866">&lt;... and two &lt;h:inputTexts&gt;</ulink> in RichFaces cookbook at JBoss portal; </para> </listitem> + <listitem> + <para> + &quot;<ulink url="http://ishabalov.blogspot.com/2007/08/sad-story-about-uiinput.h... sad story about UIInput</ulink>&quot; at personal blog of I.Shabalov and <ulink url="http://livedemo.exadel.com/richfaces-local-value-demo/pages/loc... example</ulink> of solving the problem with the help of <emphasis role="bold"><property>&lt;a4j:region&gt;</property></emphasis>. + </para> + </listitem> + </itemizedlist> </section> -</chapter> + + </section>