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

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