[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><rich:comboBox></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>"suggestionValues"</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><f:selectItem /></property></emphasis> or <emphasis role="bold">
+ <property><f:selectItems /></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> "value"</property></emphasis> attribute stores value from input after submit.
+ </para>
+ <para>
+ The <emphasis><property> "directInputSuggestions"</property></emphasis> attribute defines, how the first value from the suggested appears in input field.
+ If it's "true" the first value appears with untyped part highlighted.
+
+ <!--ADD SCREENSHOT FOR directInputSuggestions-->
+
+ </para>
+
+ <para>
+ The <emphasis><property> "selectFirstOnUpdate"</property></emphasis> attribute defines if the first value from suggested is selected in popup list.
+ If it's "false" 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> "filterNewValues"</property></emphasis> attribute defines the appearance of values in the list.
+ If it's "true" only the part of list, which satisfies the prefix entered, could appears in popup list.
+ If it's "false" 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><rich:comboBox></property></emphasis> component provides to use sizes attributes:
+ <itemizedlist>
+ <listitem>
+ <emphasis><property> "listWidth"</property></emphasis> and <emphasis><property> "listHeight"</property></emphasis> attributes
+ specify popup list sizes with values in pixels
+ </listitem>
+ <listitem>
+ <emphasis><property> "inputSize"</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> "defaultLabel"</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><rich:comboBox></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><rich:comboBox></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><rich:comboBox></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><rich:comboBox></property></emphasis> components,
+ define your own style classes in the corresponding <emphasis role="bold"><property><rich:comboBox></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><rich:comboBox></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