Author: artdaw Date: 2008-08-01 11:52:49 -0400 (Fri, 01 Aug 2008) New Revision: 9867 Modified: trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml Log: https://jira.jboss.org/jira/browse/RF-3892 - State Manager API section creation Modified: trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml 2008-08-01 15:24:19 UTC (rev 9866) +++ trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml 2008-08-01 15:52:49 UTC (rev 9867) @@ -2378,7 +2378,7 @@ </listitem> </itemizedlist> </section> - <section> + <section id="BiuldInSkinnability"> <title>Built-in skinnability in RichFaces</title> <para> RichFaces gives an opportunity to incorporate @@ -2495,8 +2495,6 @@ classes to particular elements or to container of elements that nests controls. </para> - - <para> Standard controls skinning feature provides 2 levels of skinning - standard and extended, while skinning is @@ -2539,10 +2537,8 @@ </listitem> </itemizedlist> </listitem> - <listitem> <para> - <emphasis> <property>Extended</property> </emphasis> @@ -2569,10 +2565,7 @@ </listitem> </itemizedlist> - - <para> - These are the elements that affected by skinning: </para> <itemizedlist> @@ -2624,10 +2617,7 @@ </property> </para> </listitem> - </itemizedlist> - - <para>Skinning can be initialized in two ways:</para> <itemizedlist> <listitem> @@ -2662,14 +2652,12 @@ </para> </listitem> </itemizedlist> - <para> By setting <code>org.richfaces.CONTROL_SKINNING_CLASSES</code> to &quot;enable&quot; you are provided with style classes applicable to: </para> - <itemizedlist> <listitem> <para> @@ -2716,15 +2704,10 @@ &quot;link&quot; and pseudo class name, e.g.: rich-link, rich-link-hover, rich-link-visited - - - </para> </note> </listitem> </itemizedlist> - - <para> Additionally, the predefined rich CSS classes that we provide can be used not only as classes for basic HTML @@ -2734,8 +2717,6 @@ <para> There is a snippet with some of them for example: </para> - - <programlisting role="XML"><![CDATA[... <u:selector name=".rich-box-bgcolor-header"> <u:style name="background-color" skin="headerBackgroundColor" /> @@ -2761,20 +2742,14 @@ <u:style name="background-repeat" value="repeat-x" /> </u:selector> ...]]></programlisting> - - <para> To get a better idea of standard component skinning we recommend to explore CSS files located in ui/core/src/main/resources/org/richfaces/ folder of RichFaces svn. </para> - - - <section id="Standard"> - <?dbhtml filename="BasicLevel.html"?> + <section id="Standard" role="NotInToc"> <title>Standard level</title> - <table> <title> Html Elements Skin Bindings for input, select, @@ -2788,7 +2763,6 @@ </row> </thead> <tbody> - <row> <entry>font-size</entry> <entry>generalSizeFont</entry> @@ -2804,8 +2778,6 @@ </tbody> </tgroup> </table> - - <table> <title> Html Elements Skin Bindings for fieldset @@ -2818,8 +2790,6 @@ </row> </thead> <tbody> - - <row> <entry>border-color</entry> <entry>panelBorderColor</entry> @@ -2827,9 +2797,6 @@ </tbody> </tgroup> </table> - - - <table> <title>Html Elements Skin Bindings for hr</title> <tgroup cols="2"> @@ -2840,7 +2807,6 @@ </row> </thead> <tbody> - <row> <entry>border-color</entry> <entry>panelBorderColor</entry> @@ -2848,7 +2814,6 @@ </tbody> </tgroup> </table> - <table> <title>Html Elements Skin Bindings for a</title> <tgroup cols="2"> @@ -2859,18 +2824,13 @@ </row> </thead> <tbody> - - - <row> <entry>color</entry> <entry>generalLinkColor</entry> </row> - </tbody> </tgroup> </table> - <table> <title> Html Elements Skin Bindings for a:hover @@ -2883,7 +2843,6 @@ </row> </thead> <tbody> - <row> <entry>color</entry> <entry> @@ -2893,8 +2852,6 @@ </tbody> </tgroup> </table> - - <table> <title> Html Elements Skin Bindings for a:visited @@ -2907,7 +2864,6 @@ </row> </thead> <tbody> - <row> <entry>color</entry> <entry>visitedLinkColor</entry> @@ -2915,10 +2871,6 @@ </tbody> </tgroup> </table> - - - - <table> <title> Rich Elements Skin Bindings for .rich-input, @@ -2934,7 +2886,6 @@ </row> </thead> <tbody> - <row> <entry>font-size</entry> <entry>generalSizeFont</entry> @@ -2950,10 +2901,6 @@ </tbody> </tgroup> </table> - - - - <table> <title> Rich Elements Skin Bindings for .rich-fieldset @@ -2973,8 +2920,6 @@ </tbody> </tgroup> </table> - - <table> <title> Rich Elements Skin Bindings for .rich-hr @@ -2987,19 +2932,14 @@ </row> </thead> <tbody> - <row> <entry>border-color</entry> <entry>panelBorderColor</entry> </row> - - - <row> <entry>border-width</entry> <entry>1px</entry> </row> - <row> <entry>border-style</entry> <entry>solid</entry> @@ -3007,8 +2947,6 @@ </tbody> </tgroup> </table> - - <table> <title> Rich Elements Skin Bindings for .rich-link @@ -3021,7 +2959,6 @@ </row> </thead> <tbody> - <row> <entry>color</entry> <entry>generalLinkColor</entry> @@ -3029,10 +2966,6 @@ </tbody> </tgroup> </table> - - - - <table> <title> Rich Elements Skin Bindings for .rich-link:hover @@ -3045,18 +2978,13 @@ </row> </thead> <tbody> - <row> <entry>color</entry> <entry>hoverLinkColor</entry> </row> - </tbody> </tgroup> </table> - - - <table> <title> Rich Elements Skin Bindings for @@ -3070,17 +2998,13 @@ </row> </thead> <tbody> - - <row> <entry>color</entry> <entry>visitedLinkColor</entry> </row> - </tbody> </tgroup> </table> - <table> <title> Rich Elements Skin Bindings for @@ -3456,12 +3380,10 @@ </section> - <section id="AdvancedLevel"> + <section id="AdvancedLevel" role="NotInToc"> <?dbhtml filename="AdvancedLevel.html"?> <title>Extended level</title> - <table> - <title> Html Elements Skin Bindings for input, select, textarea, button, keygen, isindex @@ -3486,15 +3408,9 @@ <entry>color</entry> <entry>controlTextColor</entry> </row> - - - - </tbody> </tgroup> </table> - - <table> <title> Html Elements Skin Bindings for *|button @@ -3507,47 +3423,35 @@ </row> </thead> <tbody> - - <row> <entry>border-color</entry> <entry>panelBorderColor</entry> </row> - <row> <entry>font-size</entry> <entry>generalSizeFont</entry> </row> - <row> <entry>font-family</entry> <entry>generalFamilyFont</entry> </row> - <row> <entry>color</entry> <entry>headerTextColor</entry> </row> - <row> <entry>background-color</entry> <entry>headerBackgroundColor</entry> </row> - <row> <entry>background-image</entry> <entry> org.richfaces.renderkit.html.images.ButtonBackgroundImage </entry> </row> - - </tbody> </tgroup> </table> - - - <table> <title> Html Elements Skin Bindings for @@ -3563,35 +3467,26 @@ </row> </thead> <tbody> - <row> <entry>border-color</entry> <entry>panelBorderColor</entry> </row> - <row> <entry>font-size</entry> <entry>generalSizeFont</entry> </row> - - - <row> <entry>font-family</entry> <entry>generalFamilyFont</entry> </row> - <row> <entry>color</entry> <entry>headerTextColor</entry> </row> - - <row> <entry>background-color</entry> <entry>headerBackgroundColor</entry> </row> - <row> <entry>background-image</entry> <entry> @@ -3601,8 +3496,6 @@ </tbody> </tgroup> </table> - - <table> <title> Html Elements Skin Bindings for @@ -3617,40 +3510,31 @@ </row> </thead> <tbody> - <row> <entry>color</entry> <entry>tabDisabledTextColor</entry> </row> - <row> <entry>border-color</entry> <entry> tableFooterBackgroundColor </entry> </row> - <row> <entry>background-color</entry> <entry> tableFooterBackgroundColor </entry> </row> - <row> <entry>background-image</entry> <entry> org.richfaces.renderkit.html.images.ButtonDisabledBackgroundImage </entry> </row> - </tbody> </tgroup> </table> - - - - <table> <title> Html Elements Skin Bindings for @@ -3676,43 +3560,31 @@ </row> </thead> <tbody> - <row> <entry>color</entry> <entry>tabDisabledTextColor</entry> </row> - <row> <entry>background-color</entry> <entry> tableFooterBackgroundColor </entry> </row> - <row> <entry>border-color</entry> <entry> tableFooterBackgroundColor </entry> </row> - - <row> <entry>background-image</entry> <entry> org.richfaces.renderkit.html.images.ButtonDisabledBackgroundImage </entry> </row> - </tbody> </tgroup> </table> - - - - - - <table> <title> Html Elements Skin Bindings for @@ -3731,45 +3603,25 @@ </row> </thead> <tbody> - - <row> <entry>color</entry> <entry>tabDisabledTextColor</entry> </row> - <row> <entry>border-color</entry> <entry> tableFooterBackgroundColor </entry> </row> - <row> <entry>background-color</entry> <entry> tableFooterBackgroundColor </entry> </row> - - </tbody> </tgroup> </table> - - - - - - - - - - - - - - <table> <title> Html Elements Skin Bindings for *|textarea @@ -3782,36 +3634,26 @@ </row> </thead> <tbody> - <row> <entry>border-color</entry> <entry>panelBorderColor</entry> </row> - <row> <entry>font-size</entry> <entry>generalSizeFont</entry> </row> - <row> <entry>font-family</entry> <entry>generalFamilyFont</entry> </row> - - - <row> <entry>color</entry> <entry>controlTextColor</entry> </row> - <row> <entry>background-color</entry> <entry>controlBackgroundColor</entry> </row> - - - <row> <entry>background-image</entry> <entry> @@ -3821,7 +3663,6 @@ </tbody> </tgroup> </table> - <table> <title> Html Elements Skin Bindings for @@ -3840,44 +3681,31 @@ <entry>border-color</entry> <entry>panelBorderColor</entry> </row> - <row> <entry>font-size</entry> <entry>generalSizeFont</entry> </row> - - - - <row> <entry>font-family</entry> <entry>generalFamilyFont</entry> </row> - <row> <entry>color</entry> <entry>controlTextColor</entry> </row> - - - - <row> <entry>background-color</entry> <entry>controlBackgroundColor</entry> </row> - <row> <entry>background-image</entry> <entry> org.richfaces.renderkit.html.images.InputBackgroundImage </entry> </row> - </tbody> </tgroup> </table> - <table> <title> Html Elements Skin Bindings for @@ -3892,18 +3720,13 @@ </row> </thead> <tbody> - <row> <entry>color</entry> <entry>tableBorderColor</entry> </row> - </tbody> </tgroup> </table> - - - <table> <title> textarea[type=&quot;textarea&quot;][disabled], @@ -3918,21 +3741,13 @@ </row> </thead> <tbody> - <row> <entry>color</entry> <entry>tableBorderColor</entry> </row> - </tbody> </tgroup> </table> - - - - - - <table> <title> textarea[type=&quot;textarea&quot;][disabled], @@ -3947,27 +3762,19 @@ </row> </thead> <tbody> - <row> <entry>color</entry> <entry>tableBorderColor</entry> </row> - </tbody> </tgroup> </table> - - - - </section> </section> - <section id="XCSSfileformat"> <title>XCSS file format</title> - <para> XCSS files are the core of RichFaces components skinnability. @@ -3976,18 +3783,12 @@ XCSS is an XML formatted CSS that adds extra functionality to the skinning process </para> - - <para> XCSS extends skinning possibilities by parsing the XCSS file that contains all look-and-feel parameters of a particular component into a standard CSS file that a web browser can recognize. </para> - - - - <para> XCSS file contains CSS properties and skin parameters mappings. Mapping of a CSS selector to a skin parameter @@ -4020,7 +3821,6 @@ } ... ]]></programlisting> - <para> The <emphasis><property>&quot;name&quot;</property></emphasis> @@ -4037,8 +3837,6 @@ tag can also be used to assign a value to a CSS property. </para> - - <para> CSS selectors with identical skinning properties can be set as a comma separated list. @@ -4049,10 +3847,10 @@ </u:selector> ... ]]></programlisting> - </section> - <section id="StPlug-n-Skin" role="new"> + <section id="PlugnSkin" role="new"> + <?dbhtml filename="PlugnSkin.html"?> <title>Plug-n-Skin</title> <para> @@ -4582,4 +4380,121 @@ </section> </section> + <section id="statemanagerapi"> + <title>State Manager API</title> + <para> + JSF has an advanced navigation mechanism that allows you to define navigation from view to view. + Navigation happens in a Web Application when a user tries to switch from one page to another page + either by clicking a button, a hyperlink, or another command component. + But there is no switch mechanism between some states/views inside a page. + For example in <property>Login/Register dialog</property> an existing user signs in with his user name and password, + but if a new user registers an additional field &quot;Confirm&quot; is displayed when the user clicks &quot;To register&quot; link: + </para> + <figure> + <title> + Login Dialog + </title> + <mediaobject> + <imageobject> + <imagedata fileref="images/stateapi1.png"/> + </imageobject> + </mediaobject> + </figure> + <figure> + <title> + Register Dialog + </title> + <mediaobject> + <imageobject> + <imagedata fileref="images/stateapi2.png"/> + </imageobject> + </mediaobject> + </figure> + <para> + <property>RichFaces State API</property> allows easily define some set of states for the pages and any properties for this states. + </para> + <para> + You could imagine one State as a set of named value bindings, method bindings, and some additional properties + that are used after the state activation. + So you could define input fields values, controls labels, actions, rendering conditions, etc. + using the same state variables which have different values for every State. + </para> + <para> + Actually States is a <property>map</property> where the entry key is name of the State and the value is a State map. + Concrete State map has entries with some names as keys and any objects as values. + So any values, method bindings, or just simple state constants could be saved in the State map. + </para> + <para> + One of the most convenience features of the <property>RichFaces State API</property> is a navigation between states. + The <property>RichFaces State API</property> implements states change as the standard JSF navigation. + Action component just returns outcome and the <property>RichFaces State API</property> extension for the JSF navigation handler + checks if this outcome registered as a <property>state change outcome</property>. + If the <property>state change outcome</property> is found corresponding state is activated. + Otherwise the standard navigation handling is called. + </para> + <para> + In order to use <property>RichFaces State API</property> you should perform next steps: + </para> + <itemizedlist> + <listitem> + <para> + Register State Manager EL resolver and navigation handler in the <property>faces-config.xml</property>: + </para> + <programlisting role="XML"><![CDATA[... +<application> + <navigation-handler>org.richfaces.ui.application.StateNavigationHandler</navigation-handler> + <el-resolver>org.richfaces.el.StateELResolver</el-resolver> +</application> +...]]></programlisting> + </listitem> + <listitem> + <para> + Register an additional application factory in the <property>faces-config.xml</property>: + </para> + <programlisting role="XML"><![CDATA[... +<factory> + <application-factory>org.richfaces.ui.application.StateApplicationFactory</application-factory> +</factory> +...]]></programlisting> + </listitem> + <listitem> + <para> + Register two managed beans in the <property>faces-config.xml</property>: + </para> + <programlisting role="XML"><![CDATA[... +<managed-bean> + <managed-bean-name>state</managed-bean-name> + <managed-bean-class>org.richfaces.ui.model.States</managed-bean-class> + <managed-bean-scope>request</managed-bean-scope> + <managed-property> + <property-name>states</property-name> + <property-class>org.richfaces.ui.model.States</property-class> + <value>#{config.states}</value> + </managed-property> +</managed-bean> +<managed-bean> + <managed-bean-name>config</managed-bean-name> + <managed-bean-class>org.richfaces.demo.stateApi.Config</managed-bean-class> + <managed-bean-scope>none</managed-bean-scope> +</managed-bean> +...]]></programlisting> + <para> + One bean (<code>org.richfaces.demo.stateApi.Config</code>) defines and stores states. + </para> + <para> + The other bean (<code>org.richfaces.ui.model.States</code>) with the type <code>org.richfaces.ui.model.States</code> has + the &quot;states&quot; managed property that is bound to the &quot;config&quot; bean which defines states. + </para> + </listitem> + <listitem> + <para> + Use <property>state</property> bindings on the pages. + </para> + </listitem> + </itemizedlist> + <para> + <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/stateAPI.js... + you could find the <property>Login/Register dialog</property> example and sources for the given example. + </para> + </section> </chapter>