Author: SeanRogers
Date: 2010-11-18 02:24:59 -0500 (Thu, 18 Nov 2010)
New Revision: 20082
Added:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richselect-Selection_items-0.xml_sample
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richselect-Selection_items-1.xml_sample
Removed:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richselect-Selection_items.xml_sample
Modified:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Tables_and_grids.xml
Log:
Re-draft of rich:select based on tech review
Modified:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml
===================================================================
---
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml 2010-11-18
02:05:03 UTC (rev 20081)
+++
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml 2010-11-18
07:24:59 UTC (rev 20082)
@@ -822,7 +822,7 @@
<section id="sect-Component_Reference-Rich_inputs-richselect">
<title><sgmltag><rich:select></sgmltag></title>
<para>
- The <sgmltag><rich:select></sgmltag> component provides a
drop-down list box for selecting a single value from multiple options. The component
supports keyboard navigation and can optionally accept typed input as a combo-box.
+ The <sgmltag><rich:select></sgmltag> component provides a
drop-down list box for selecting a single value from multiple options. The component
supports keyboard navigation and can optionally accept typed input. The
<sgmltag><rich:select></sgmltag> component functions similarly
to the JavaServer Faces <sgmltag><h:selectOneMenu></sgmltag>
component.
</para>
<figure id="figu-Component_Reference-richselect-richselect">
@@ -833,7 +833,7 @@
</imageobject>
<textobject>
<para>
- A <sgmltag><rich:select></sgmltag> component used as a
combo-box.
+ A <sgmltag><rich:select></sgmltag> component.
</para>
</textobject>
</mediaobject>
@@ -842,28 +842,54 @@
<section id="sect-Component_Reference-richselect-Basic_usage">
<title>Basic usage</title>
<para>
- Simple usage of the <sgmltag><rich:select></sgmltag>
component does not need any attributes declared, but child tags to manage the list of
selections are required. An <sgmltag><f:selectItem></sgmltag>
tag manages the currently selected value, while an
<sgmltag><f:selectItems></sgmltag> tag points to the list of
selection items.
+ Simple usage of the <sgmltag><rich:select></sgmltag>
component does not need any attributes declared, but child tags to manage the list of
selections are required. The child tags can either be a number of
<sgmltag><f:selectItem></sgmltag> tags or a
<sgmltag><f:selectItems></sgmltag> tag which points to a data
model containing a list of selection items. The <varname>value</varname>
attribute is used to store the current selection.
</para>
<example id="exam-Component_Reference-richselect-Selection_items">
<title>Selection items</title>
- <programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Component_Reference-richselect-Selection_items.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <variablelist>
+ <varlistentry>
+ <term>Using multiple
<sgmltag><f:selectItem></sgmltag> tags</term>
+ <listitem>
+ <programlisting language="XML"
role="XML"><xi:include parse="text"
href="extras/exam-Component_Reference-richselect-Selection_items-0.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Using a single
<sgmltag><f:selectItems></sgmltag> tag</term>
+ <listitem>
+ <programlisting language="XML"
role="XML"><xi:include parse="text"
href="extras/exam-Component_Reference-richselect-Selection_items-1.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</example>
<para>
- The arrow keys on a keyboard can be used to highlight different items in the list,
even if the list is closed with the control still focused. If the control loses focus or
the <keycap function="enter">Enter</keycap> key is pressed, the
highlighted option is chosen as the value and the list is closed. Pressing the <keycap
function="escape">Esc</keycap> key will close the list but not change
the value.
+ The arrow keys on a keyboard can be used to highlight different items in the list. If
the control loses focus or the <keycap
function="enter">Enter</keycap> key is pressed, the highlighted option
is chosen as the value and the list is closed. Pressing the <keycap
function="escape">Esc</keycap> key will close the list but not change
the value.
</para>
</section>
- <section
id="sect-Component_Reference-richselect-Using_richselect_as_a_combo-box">
- <title>Using <sgmltag><rich:select></sgmltag> as a
combo-box</title>
+ <section id="sect-Component_Reference-richselect-Advanced_options">
+ <title>Advanced options</title>
<para>
- Combo-boxes are drop-down lists that allow the user to type into a text field to
scroll through or filter the list. By default, the
<sgmltag><rich:select></sgmltag> component functions as a
drop-down list. To add keyboard support to make it function like a combo-box, set
<code>enableManualInput="true"</code>.
+ Use the <varname>defaultLabel</varname> attribute to set a place-holder
label, such as <code>defaultLabel="select an option"</code>.
</para>
<para>
+ Server-side processing occurs in the same manner as for an
<sgmltag><h:selectOneMenu></sgmltag> component. As such, custom
objects used for selection items should use the same converters as for an
<sgmltag><h:selectOneMenu></sgmltag> component.
+ </para>
+ </section>
+
+ <section id="sect-Component_Reference-richselect-Using_manual_input">
+ <title>Using manual input</title>
+ <para>
+ Selection lists can allow the user to type into a text field to scroll through or
filter the list. By default, the
<sgmltag><rich:select></sgmltag> component functions as a
drop-down list with no manual input. To add keyboard support for manual input, set
<code>enableManualInput="true"</code>.
+ </para>
+ <para>
Once the user begins typing, the first available matching option is highlighted. If
the typed text does not match any values in the list, no value is chosen and the drop-down
list displays as empty. Other keyboard interaction remains the same as the basic drop-down
list.
</para>
+ <!-- TODO: not in M4 -->
+ <!--
<para>
- Typing text into a combo-box causes the list to scroll to the relevant item by
default. This behavior can be changed so that the typed text filters the contents of the
list instead, showing only those items that begin with the typed text. To use typed text
as a filter for combo-box lists, set
<code>filterOnUpdates="true"</code>.
+ Typing text into the text box causes the list to scroll to the relevant item by
default. This behavior can be changed so that the typed text filters the contents of the
list instead, showing only those items that begin with the typed text. To use typed text
as a filter for manual-input lists, set
<code>filterOnUpdates="true"</code>.
</para>
+ -->
</section>
<section id="sect-Component_Reference-richselect-Reference_data">
Modified:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Tables_and_grids.xml
===================================================================
---
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Tables_and_grids.xml 2010-11-18
02:05:03 UTC (rev 20081)
+++
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Tables_and_grids.xml 2010-11-18
07:24:59 UTC (rev 20082)
@@ -1265,18 +1265,18 @@
<para>
Tables entries can be sorted by the user through either the basic method built in to
the <sgmltag><rich:column></sgmltag> component, or by defining
external sorting algorithms. Refer to <xref
linkend="sect-Component_Reference-Tables_and_grids-richcolumn" /> for details
on using the <sgmltag><rich:column></sgmltag> component in
tables.
</para>
+ <note>
+ <title>Sorting non-English tables</title>
+ <para>
+ To sort a table whose contents are not in English, add the
<literal>org.richfaces.datatableUsesViewLocale</literal> context parameter to
the project's <filename>web.xml</filename> settings file. Set the value of
the context parameter to <literal>true</literal>.
+ </para>
+ </note>
<section id="sect-Component_Reference-Tables_and_grids-Basic_sorting">
<title>Basic sorting</title>
<para>
The built-in sorting functionality of the
<sgmltag><rich:column></sgmltag> component allows a user to
click the header of a column to sort it in ascending or descending order.
</para>
- <note>
- <title>Sorting non-English tables</title>
- <para>
- To sort a table whose contents are not in English, add the
<literal>org.richfaces.datatableUsesViewLocale</literal> context parameter to
the project's <filename>web.xml</filename> settings file. Set the value of
the context parameter to <literal>true</literal>.
- </para>
- </note>
<para>
Set the <varname>sortBy</varname> attribute to indicate which value to
use when sorting the column. Expressions in the <varname>sortBy</varname>
attribute must refer to the variable declared in the table's
<varname>var</varname> attribute, which is used to fill the contents of the
table.
</para>
Copied:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richselect-Selection_items-0.xml_sample
(from rev 20081,
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richselect-Selection_items.xml_sample)
===================================================================
---
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richselect-Selection_items-0.xml_sample
(rev 0)
+++
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richselect-Selection_items-0.xml_sample 2010-11-18
07:24:59 UTC (rev 20082)
@@ -0,0 +1,7 @@
+<rich:select>
+ <f:selectItem itemValue="0" itemLabel="Option 1" />
+ <f:selectItem itemValue="1" itemLabel="Option 2" />
+ <f:selectItem itemValue="2" itemLabel="Option 3" />
+ <f:selectItem itemValue="3" itemLabel="Option 4" />
+ <f:selectItem itemValue="4" itemLabel="Option 5" />
+</rich:select>
Added:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richselect-Selection_items-1.xml_sample
===================================================================
---
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richselect-Selection_items-1.xml_sample
(rev 0)
+++
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richselect-Selection_items-1.xml_sample 2010-11-18
07:24:59 UTC (rev 20082)
@@ -0,0 +1,3 @@
+<rich:select>
+ <f:selectItems value="#{bean.options}" />
+</rich:select>
Deleted:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richselect-Selection_items.xml_sample
===================================================================
---
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richselect-Selection_items.xml_sample 2010-11-18
02:05:03 UTC (rev 20081)
+++
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richselect-Selection_items.xml_sample 2010-11-18
07:24:59 UTC (rev 20082)
@@ -1,4 +0,0 @@
-<rich:select>
- <f:selectItem itemLabel="constantOption" itemValue="0">
- <f:selectItems="#{bean.items}">
-</rich:select>