[richfaces-svn-commits] JBoss Rich Faces SVN: r7946 - trunk/docs/userguide/en/src/main/docbook/modules.

Author: vsukhov Date: 2008-04-18 12:42:01 -0400 (Fri, 18 Apr 2008) New Revision: 7946 Modified: trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml Log: http://jira.jboss.com/jira/browse/RF-2908 I've replaced "reRender" attribute by: "rendered" attribute in section 5.4.1 of the Reference Manual Modified: trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml 2008-04-18 15:57:36 UTC (rev 7945) +++ trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml 2008-04-18 16:42:01 UTC (rev 7946) @@ -25,12 +25,13 @@ <para>Next Figure shows how it works:</para> <figure> <title>Request Processing flow</title> - </figure> + <mediaobject> <imageobject> <imagedata fileref="images/newpic1.png" scalefit="1"/> </imageobject> </mediaobject> + </figure> <para><property>RichFaces</property> allows to define (by means of JSF tags) different parts of a JSF page you wish to update with an Ajax request and provide a few options to send Ajax requests to the server. Also JSF page doesn&apos;t change from a @@ -44,12 +45,13 @@ framework</para> <figure> <title>Core Ajax component structure</title> - </figure> + <mediaobject> <imageobject> <imagedata fileref="images/newpic2.png"/> </imageobject> </mediaobject> + </figure> <formalpara> <title>Ajax Filter.</title> <para>To get all benefits of <property>RichFaces</property>, you should register a Filter in @@ -65,12 +67,13 @@ <para>Have a look at the next picture to understand these two ways:</para> <figure> <title>Request Processing sequence diagram</title> - </figure> + <mediaobject> <imageobject> <imagedata fileref="images/newpic3.png" scalefit="1"/> </imageobject> </mediaobject> + </figure> <para>In both cases, the information about required static or dynamic resources that your application requests is registered in the ResourseBuilder class.</para> <para>When a request for a resource comes (Figure 4), the RichFaces filter checks the Resource @@ -81,12 +84,13 @@ <para>Next Figure shows the ways of resource request processing.</para> <figure> <title>Resource request sequence diagram</title> - </figure> + <mediaobject> <imageobject> <imagedata fileref="images/newpic4.png" scalefit="1"/> </imageobject> </mediaobject> + </figure> <formalpara> <title>AJAX Action Components</title> <para> There are Ajax Action Components: AjaxCommandButton, AjaxCommandLink, AjaxPoll and @@ -110,22 +114,22 @@ <title>Limitations and Rules</title> <para>In order to create RichFaces applications properly, keep the following points in mind:</para> <itemizedlist> - <listitem> Any Ajax framework should not append or delete, but only replace elements on the + <listitem><para> Any Ajax framework should not append or delete, but only replace elements on the page. For successful updates, an element with the same ID as in the response must exist on the page. If you&apos;d like to append any code to a page, put in a placeholder for it (any empty element). For the same reason, it&apos;s recommended to place messages in the<emphasis> <property>&quot;AjaxOutput&quot;</property> - </emphasis> component (as no messages is also a message). </listitem> - <listitem> Don&apos;t use <emphasis role="bold"> + </emphasis> component (as no messages is also a message). </para></listitem> + <listitem><para> Don&apos;t use <emphasis role="bold"> <property>&lt;f:verbatim&gt;</property> </emphasis> for self-rendered containers, since this component is transient and not saved in - the tree. </listitem> - <listitem> Ajax requests are made by XMLHttpRequest functions in XML format, but this XML + the tree. </para></listitem> + <listitem><para> Ajax requests are made by XMLHttpRequest functions in XML format, but this XML bypasses most validations and the corrections that might be made in a browser. Thus, create only a strict standards-compliant code for HTML and XHTML, without skipping any required elements or attributes. Any necessary XML corrections are automatically made by the XML filter on the server, but lot&apos;s of unexpected effects can be produced by an - incorrect HTML code. </listitem> + incorrect HTML code. </para></listitem> </itemizedlist> </section> @@ -218,7 +222,7 @@ what should be re-rendered on any previous phase during the Ajax request processing.</para> <para>Most common problem with using reRender is pointing it to the component that has a <emphasis> - <property>&quot;reRender&quot;</property> + <property>&quot;rendered&quot;</property> </emphasis> attribute. Note, that JSF does not mark the place in the browser DOM where the outcome of the component should be placed in case the <emphasis> <property>&quot;rendered&quot;</property> @@ -424,7 +428,7 @@ RichFaces starts to work in "Ajax request generates Non-Ajax Response" mode. This mode might be helpful in two major cases:</para> <itemizedlist> - <listitem>RichFaces allows to organize a page flow inside the <emphasis role="bold"> + <listitem><para>RichFaces allows to organize a page flow inside the <emphasis role="bold"> <property>&lt;a4j:include&gt;</property> </emphasis> component. This is a typical scenario for Wizard like behavior. The new content is rendered inside the <emphasis role="bold"> @@ -438,8 +442,8 @@ inside the <emphasis role="bold"> <property>&lt;a4j:include&gt;</property> </emphasis> to navigate between the wizard pages. Otherwize, the whole page update will be - performed.</listitem> - <listitem>If you want to involve the server side validators and navigate to the next page + performed.</para></listitem> + <listitem><para>If you want to involve the server side validators and navigate to the next page only if the Validation phase is passed successfully, you can replace <emphasis role="bold"> <property>&lt;h:commandButton&gt;</property> </emphasis> with <emphasis role="bold"> @@ -447,7 +451,7 @@ </emphasis> and point to the action method that navigates to the next page. If Validation process fails, the partial page update will occur and you will see an error message. Otherwize, the application proceeds to the next page. Make sure, you define - &lt;redirect/&gt; option for the navigation rule to avoid memory leaks.</listitem> + &lt;redirect/&gt; option for the navigation rule to avoid memory leaks.</para></listitem> </itemizedlist> <para> </para> </section> @@ -520,9 +524,9 @@ </emphasis>.</para> <para>There is a number of useful functions which can be used in JavaScript:</para> <itemizedlist> - <listitem>rich:clientId('id') - returns client id by short id or null if the component with the id specified hasn't been found </listitem> - <listitem>rich:element('id') - is a shortcut for document.getElementById(#{rich:clientId('id')}) </listitem> - <listitem>rich:component('id') - is a shortcut for #{rich:clientId('id')}.component</listitem> + <listitem><para>rich:clientId('id') - returns client id by short id or null if the component with the id specified hasn't been found </para></listitem> + <listitem><para>rich:element('id') - is a shortcut for document.getElementById(#{rich:clientId('id')}) </para></listitem> + <listitem><para>rich:component('id') - is a shortcut for #{rich:clientId('id')}.component</para></listitem> </itemizedlist> </section> @@ -760,10 +764,10 @@ <property>&lt;f:verbatim/&gt;</property> </emphasis> tag and content of other panel&apos;s child tags could be updated on Ajax response. There are two ways to control this: <itemizedlist> - <listitem> By setting the &quot;ajaxRendered&quot; attribute value to - &quot;true&quot;. </listitem> - <listitem> By setting the &quot;reRender&quot; attribute value of an Action - Component to the output panel ID. </listitem> + <listitem><para> By setting the &quot;ajaxRendered&quot; attribute value to + &quot;true&quot;. </para></listitem> + <listitem><para> By setting the &quot;reRender&quot; attribute value of an Action + Component to the output panel ID. </para></listitem> </itemizedlist> </para> <section id="process"> @@ -778,12 +782,12 @@ </para> <para>The <emphasis><property>&quot;process&quot;</property></emphasis> attribute has two limitations:</para> <itemizedlist> - <listitem> + <listitem><para> it works only if <emphasis><property>&quot;ajaxSingle&quot;</property></emphasis> equals to "true" for given command component - </listitem> - <listitem> + </para></listitem> + <listitem><para> you do not have to point this attribute to one of the own parent components to avoid processing of command component twice - </listitem> + </para></listitem> </itemizedlist> <para><emphasis role="bold">Example:</emphasis></para> <programlisting role="XML"><![CDATA[... @@ -1016,9 +1020,9 @@ };]]></programlisting> <para>The function defined this way accepts as parameters:</para> <itemizedlist> - <listitem>req - a params string of a request that calls an error</listitem> - <listitem>status - the number of an error returned by the server</listitem> - <listitem>message - a default message for the given error</listitem> + <listitem><para>req - a params string of a request that calls an error</para></listitem> + <listitem><para>status - the number of an error returned by the server</para></listitem> + <listitem><para>message - a default message for the given error</para></listitem> </itemizedlist> <para>Thus, it&apos;s possible to create your own handler that is called on timeouts, inner server errors, and etc.</para> @@ -1043,10 +1047,10 @@ <para>Here the function receives in params:</para> <itemizedlist> - <listitem>loc - URL of the current page (on demand can be updated) </listitem> - <listitem>expiredMsg - a default message on <emphasis> + <listitem><para>loc - URL of the current page (on demand can be updated) </para></listitem> + <listitem><para>expiredMsg - a default message on <emphasis> <property>&quot;Session Expiration&quot;</property> - </emphasis>event.</listitem> + </emphasis>event.</para></listitem> </itemizedlist> <!--note> <title>Note:</title> @@ -1234,23 +1238,23 @@ common customization:</para> <itemizedlist> - <listitem> DEFAULT </listitem> + <listitem><para> DEFAULT </para></listitem> - <listitem> plain </listitem> + <listitem><para> plain </para></listitem> - <listitem> emeraldTown </listitem> + <listitem><para> emeraldTown </para></listitem> - <listitem> blueSky </listitem> + <listitem><para> blueSky </para></listitem> - <listitem> wine </listitem> + <listitem><para> wine </para></listitem> - <listitem> japanCherry </listitem> + <listitem><para> japanCherry </para></listitem> - <listitem> ruby </listitem> + <listitem><para> ruby </para></listitem> - <listitem> classic </listitem> + <listitem><para> classic </para></listitem> - <listitem> deepMarine </listitem> + <listitem><para> deepMarine </para></listitem> </itemizedlist> <para>To plug one in, it&apos;s necessary to specify a skin name in the <emphasis> @@ -1562,15 +1566,15 @@ JSF components built with the help of RichFaces. </para> <para>To find out more on <property>skinnability</property> possibilities, follow these steps:</para> <itemizedlist> - <listitem> Create a custom render kit and register it in the faces-config.xml like this: <programlisting role="XML"><![CDATA[<render-kit> + <listitem><para> Create a custom render kit and register it in the faces-config.xml like this: </para><programlisting role="XML"><![CDATA[<render-kit> <render-kit-id>NEW_SKIN</render-kit-id> <render-kit-class> org.ajax4jsf.framework.renderer.ChameleonRenderKitImpl </render-kit-class> </render-kit>]]></programlisting> </listitem> - <listitem> Then you need to create and register custom renderers for the component based on - the look-and-feel predefined variables: <programlisting role="XML"><![CDATA[<renderer> + <listitem><para> Then you need to create and register custom renderers for the component based on + the look-and-feel predefined variables: </para><programlisting role="XML"><![CDATA[<renderer> <component-family>javax.faces.Command</component-family> <renderer-type>javax.faces.Link</renderer-type> <renderer-class> @@ -1578,15 +1582,15 @@ </renderer-class> </renderer>]]></programlisting> </listitem> - <listitem> Finally, you need to place a properties file with skin parameters into the class - path root. There are two requirements for the properties file: <itemizedlist> - <listitem> The file must be named <emphasis role="bold"> + <listitem><para> Finally, you need to place a properties file with skin parameters into the class + path root. There are two requirements for the properties file: </para><itemizedlist> + <listitem><para> The file must be named <emphasis role="bold"> <property>&lt;skinName&gt;</property> </emphasis>.skin.properties, in this case, it would be called - <filename>newskin.skin.properties</filename>. </listitem> - <listitem> The first line in this file should be render.kit= <emphasis role="bold" + <filename>newskin.skin.properties</filename>. </para></listitem> + <listitem><para> The first line in this file should be render.kit= <emphasis role="bold" - would be called render.kit=NEW_SKIN. </listitem> + would be called render.kit=NEW_SKIN. </para></listitem> </itemizedlist> </listitem> </itemizedlist> @@ -1615,31 +1619,31 @@ <itemizedlist> <listitem> <para> - <property><emphasis><property>Basic</property></emphasis></property> provides customization only basic style properties. + <emphasis><property>Basic</property></emphasis> provides customization only basic style properties. </para> <para> To the following browsers Basic level of skinning is applied: </para> <itemizedlist> - <listitem>Internet Explorer 6 </listitem> - <listitem>Internet Explorer 7 in BackCompat mode (see <ulink url="http://msdn2.microsoft.com/en-us/library/ms533687(VS.85).aspx&q... property in MSDN</ulink>) </listitem> - <listitem>Opera </listitem> - <listitem>Safari</listitem> + <listitem><para>Internet Explorer 6 </para></listitem> + <listitem><para>Internet Explorer 7 in BackCompat mode (see <ulink url="http://msdn2.microsoft.com/en-us/library/ms533687(VS.85).aspx&q... property in MSDN</ulink>) </para></listitem> + <listitem><para>Opera </para></listitem> + <listitem><para>Safari</para></listitem> </itemizedlist> </listitem> <listitem> <para> - <property> - <emphasis><property>Advanced</property></emphasis></property> extends basic level introducing broader + + <emphasis><property>Advanced</property></emphasis> extends basic level introducing broader number of style properties and is applied to browsers with rich visual styling capability of controls </para> <para> The following browsers support Advanced level of skinning: </para> <itemizedlist> - <listitem>Mozilla Firefox</listitem> - <listitem>Internet Explorer 7 in Standards-compliant mode (CSS1Compat mode)</listitem> + <listitem><para>Mozilla Firefox</para></listitem> + <listitem><para>Internet Explorer 7 in Standards-compliant mode (CSS1Compat mode)</para></listitem> </itemizedlist> </listitem> @@ -1651,15 +1655,15 @@ These are the elements that affected by skinning: </para> <itemizedlist> - <listitem><property>input</property></listitem> - <listitem><property>select</property></listitem> - <listitem><property>textarea</property></listitem> - <listitem><property>keygen</property></listitem> - <listitem><property>isindex</property></listitem> - <listitem><property>legend</property></listitem> - <listitem><property>fieldset</property></listitem> - <listitem><property>hr</property></listitem> - <listitem><property>a (together with a:hover, a:visited &quot;pseudo&quot;-elements)</property></listitem> + <listitem><para><property>input</property></para></listitem> + <listitem><para><property>select</property></para></listitem> + <listitem><para><property>textarea</property></para></listitem> + <listitem><para><property>keygen</property></para></listitem> + <listitem><para><property>isindex</property></para></listitem> + <listitem><para><property>legend</property></para></listitem> + <listitem><para><property>fieldset</property></para></listitem> + <listitem><para><property>hr</property></para></listitem> + <listitem><para><property>a (together with a:hover, a:visited &quot;pseudo&quot;-elements)</property></para></listitem> </itemizedlist>