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

richfaces-svn-commits at lists.jboss.org richfaces-svn-commits at lists.jboss.org
Sat Jan 12 08:40:00 EST 2008


Author: artdaw
Date: 2008-01-12 08:39:59 -0500 (Sat, 12 Jan 2008)
New Revision: 5327

Modified:
   trunk/docs/userguide/en/src/main/docbook/included/comboBox.xml
Log:
http://jira.jboss.com/jira/browse/RF-1702 - add Details of Usage, JavaScript API, Look-and-Feel Customization, Skin Parameters Redefinition, Definition of Custom Style Classes sections

Modified: trunk/docs/userguide/en/src/main/docbook/included/comboBox.xml
===================================================================
--- trunk/docs/userguide/en/src/main/docbook/included/comboBox.xml	2008-01-12 13:12:55 UTC (rev 5326)
+++ trunk/docs/userguide/en/src/main/docbook/included/comboBox.xml	2008-01-12 13:39:59 UTC (rev 5327)
@@ -44,14 +44,13 @@
     <section>
         <title>Creating the Component with a Page Tag</title>
         <para>Here is a simple example as it could be used on a page: </para>
-        
         <para>
             <emphasis role="bold">Example:</emphasis>
         </para>
         <programlisting role="XML"><![CDATA[...
-<rich:comboBox value="#{bean.state}" valueChangeListener="#{bean.selectionChanged}"  suggestionValues="#{bean.suggestions}">
+<rich:comboBox value="#{bean.state}" valueChangeListener="#{bean.selectionChanged}" >
         <f:selectItems  value="#{bean.selectItems}"/>
-<rich:comboBox>
+</rich:comboBox>
 ...]]></programlisting>
     </section>
     <section>
@@ -64,4 +63,213 @@
 HtmlComboBox myComboBox = new HtmlComboBox();
 ...]]></programlisting>
     </section>
+    <section>
+        <title>Details of Usage</title>
+        <para>The <emphasis role="bold">
+            <property>&lt;rich:comboBox&gt;</property>
+        </emphasis> component consists of an <property>input field</property>, the <property>button</property> and the <property>popup list</property> of suggestions 
+            attached to input. 
+            The component could be in two states:
+            
+            <!-- NEED DESCRIPTION "HOW TO MANAGE THIS"-->
+           
+            <itemizedlist>
+                <listitem>Default - only input and button is shown</listitem>
+                <listitem>Input, button and popup list of suggestions attached to input is shown</listitem>
+            </itemizedlist>
+        </para>
+        <para>
+            There are two ways to get values for the popup list of suggestions:
+            <itemizedlist>
+                <listitem>Using the <emphasis><property>&quot;suggestionValues&quot;</property></emphasis> attribute, that defines the suggestion collection
+                    <para>
+                        <emphasis role="bold">Example:</emphasis>
+                    </para>
+                    <programlisting role="XML">
+<![CDATA[...
+<rich:comboBox value="#{bean.state}" valueChangeListener="#{bean.selectionChanged}"  suggestionValues="#{bean.suggestions}" />    
+...]]></programlisting>            
+                </listitem>
+                <listitem>Using the <emphasis role="bold"><property>&lt;f:selectItem /&gt;</property></emphasis> or <emphasis role="bold">
+                    <property>&lt;f:selectItems /&gt;</property></emphasis> components
+                    <para>
+                        <emphasis role="bold">Example:</emphasis>
+                    </para>
+                    <programlisting role="XML">
+<![CDATA[...
+<rich:comboBox value="#{bean.state}" valueChangeListener="#{bean.selectionChanged}">
+        <f:selectItems  value="#{bean.selectItems}"/>
+        <f:selectItem itemValue="Oregon"/>			  
+        <f:selectItem itemValue="Pennsylvania"/>
+        <f:selectItem itemValue="Rhode Island"/>
+        <f:selectItem itemValue="South Carolina"/>
+</rich:comboBox>            
+...]]></programlisting>      
+                </listitem>
+            </itemizedlist>
+            Popup list content loads at page render time. No additional requests could be performed on the popup calling.
+        </para>
+        <para>
+            The <emphasis><property> &quot;value&quot;</property></emphasis> attribute stores value from input after submit. 
+        </para>
+        <para>
+            The <emphasis><property> &quot;directInputSuggestions&quot;</property></emphasis> attribute defines, how the first value from the suggested appears in input field. 
+            If it&apos;s &quot;true&quot; the first value appears with untyped part highlighted. 
+            
+            <!--ADD SCREENSHOT FOR  directInputSuggestions-->
+            
+        </para>
+        
+        <para>
+        The <emphasis><property> &quot;selectFirstOnUpdate&quot;</property></emphasis> attribute defines if the first value from suggested is selected in popup list. 
+        If it&apos;s &quot;false&quot; nothing is selected in the list before user hovered some item via mouse. Also nothing could be selected after mouse out the list. 
+            
+            <!--ADD SCREENSHOT FOR  selectFirstOnUpdate-->
+        
+        </para>
+        
+        <para>
+            The <emphasis><property> &quot;filterNewValues&quot;</property></emphasis> attribute defines the appearance of values in the list.
+            If it&apos;s &quot;true&quot; only the part of list, which satisfies the prefix entered, could appears in popup list.
+            If it&apos;s &quot;false&quot; all values appear in the popup list. But the list could be scrolled to the first value that satisfies the prefix.            
+        </para>
+        
+        <para>
+            The <emphasis role="bold"><property>&lt;rich:comboBox&gt;</property></emphasis> component provides to use sizes attributes:
+            <itemizedlist>
+                <listitem>
+                    <emphasis><property> &quot;listWidth&quot;</property></emphasis> and <emphasis><property> &quot;listHeight&quot;</property></emphasis> attributes
+                    specify popup list sizes with values in pixels
+                </listitem>
+                <listitem>
+                    <emphasis><property> &quot;inputSize&quot;</property></emphasis> attribute customizes the size of input element with values in symbols as for standard input field.
+                </listitem>
+            </itemizedlist>  
+        </para>
+        <para>
+            The <emphasis><property> &quot;defaultLabel&quot;</property></emphasis> attribute defines the default label of the input element.
+        </para>
+
+      
+    </section>
+    <section>
+        <title>JavaScript API</title>
+        <table>
+            <title>JavaScript API</title>
+            <tgroup cols="2">
+                <thead>
+                    <row>
+                        <entry>Function</entry>
+                        <entry>Description</entry>
+                    </row>
+                </thead>
+                <tbody>
+                    <row>
+                        <entry>showList()</entry>
+                        <entry></entry>
+                    </row>
+                    <row>
+                        <entry>hideList()</entry>
+                        <entry></entry>
+                    </row>
+                    <row>
+                        <entry>Enable()</entry>
+                        <entry></entry>
+                    </row>
+                    <row>
+                        <entry>Disable()</entry>
+                        <entry></entry>
+                    </row>`
+                </tbody>
+            </tgroup>
+        </table>
+    </section>
+    
+    <section>
+        <title>Look-and-Feel Customization</title>
+        <para>For skinnability implementation, the components use a <emphasis>
+            <property>style class redefinition method.</property>
+        </emphasis> Default style classes are mapped on <emphasis>
+            <property>skin parameters.</property>
+        </emphasis></para>
+        <para>There are two ways to redefine the appearance of all <emphasis role="bold">
+            <property>&lt;rich:comboBox&gt;</property>
+        </emphasis> components at once: <itemizedlist>
+            <listitem>Redefine the corresponding skin parameters</listitem>
+            <listitem> Add to your style sheets style classes used by a <emphasis role="bold">
+                <property>&lt;rich:comboBox&gt;</property>
+            </emphasis> component</listitem>
+        </itemizedlist>
+        </para>
+    </section>
+    <section>
+        <title>Skin Parameters Redefinition</title>
+        
+        <table>
+            <title>Skin parameters redefinition for </title>
+            <tgroup cols="2">
+                <thead>
+                    <row>
+                        <entry>Skin parameters</entry>
+                        <entry>CSS properties</entry>
+                    </row>
+                </thead>
+                <tbody>
+                    <row>
+                        <entry></entry>
+                        <entry></entry>
+                    </row>
+                    <row>
+                        <entry></entry>
+                        <entry></entry>
+                    </row>
+                </tbody>
+            </tgroup>
+        </table>
+    </section>
+    <section>
+        <title>Definition of Custom Style Classes</title>
+        
+        <para>On the screenshot there are classes names that define styles for component elements.</para>
+
+        <figure>
+            <title>Classes names</title>
+            <mediaobject>
+                <imageobject>
+                    <imagedata fileref=""/>
+                </imageobject>
+            </mediaobject>
+        </figure>
+        
+        <table>
+            <title>Classes names that define </title>
+            <tgroup cols="2">
+                <thead>
+                    <row>
+                        <entry>Class name</entry>
+                        <entry>Description</entry>
+                    </row>
+                </thead>
+                <tbody>
+                    <row>
+                        <entry></entry>
+                        <entry></entry>
+                    </row>
+                </tbody>
+            </tgroup>
+        </table>
+        <para>In order to redefine styles for all <emphasis role="bold"><property>&lt;rich:comboBox&gt;</property></emphasis> components on a page using CSS, 
+            it's enough to create classes with the same names and define necessary properties in them. 
+        </para>
+        <para>To change styles of particular <emphasis role="bold"><property>&lt;rich:comboBox&gt;</property></emphasis> components, 
+            define your own style classes in the corresponding <emphasis role="bold"><property>&lt;rich:comboBox&gt;</property></emphasis> component attributes.
+        </para>
+    </section>
+    <section>
+        <title>Relevant Resources Links</title>
+        <para>
+            <ulink url="">Here</ulink> you can see an example of <emphasis role="bold"><property>&lt;rich:comboBox&gt;</property></emphasis> usage 
+            and sources for the given example. 
+        </para>
+    </section>
 </section>
\ No newline at end of file




More information about the richfaces-svn-commits mailing list