Author: bleathem
Date: 2011-11-08 15:00:36 -0500 (Tue, 08 Nov 2011)
New Revision: 22910
Added:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richpickList-ItemLabel_use.xml_sample
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richpickList-richcolumn_use.xml_sample
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-richpickList-richpickList.png
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/skinning/tabl-richpickList.xml
Modified:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml
Log:
RFPL-1575: Documented the pickList
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 2011-11-08
16:14:18 UTC (rev 22909)
+++
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml 2011-11-08
20:00:36 UTC (rev 22910)
@@ -2260,7 +2260,7 @@
<section id="sect-Component_Reference-Rich_inputs-richorderingList">
<title><sgmltag><rich:orderingList></sgmltag></title>
<para>
- The <sgmltag><rich:orderingList></sgmltag> is a
component for ordering items in a list. This component allows one to reorder a list and
sort it on the client side.
+ The <sgmltag><rich:orderingList></sgmltag> is a
component for ordering items in a list (client-side).
</para>
<figure
id="figu-Component_Reference-richorderingList-richorderingList">
@@ -2280,7 +2280,7 @@
<section id="sect-Component_Reference-richorderingList-Basic_usage">
<title>Basic usage</title>
<para>
- To use the <sgmltag><rich:orderingList></sgmltag> bind the
<varname>value</varname> attribute to the list to be ordered. This
<varname>var</varname> attribute specifies a variable to use when iterating
through the list values. The <varname>var</varname> attribute is used within
the <varname>itemLabel</varname> to assign the object value to be displayed.
Similarly, the <varname>var</varname> attribute is used within the
<varname>itemValue</varname> attribute to specify the object value mapped by
the display value. If the itemValue is not of type
<classname>String</classname>, a converter must be specified for this
itemValue using either the <varname>converter</varname> attribute, or a nested
<sgmltag><f:converter></sgmltag> tag.
+ To use the <sgmltag><rich:orderingList></sgmltag> bind the
<varname>value</varname> attribute to the list to be ordered. The
<varname>var</varname> attribute specifies a variable to use when iterating
through the list values. The <varname>var</varname> attribute is used within
the <varname>itemLabel</varname> to assign the object value to be displayed.
Similarly, the <varname>var</varname> attribute is used within the
<varname>itemValue</varname> attribute to specify the object value mapped by
the display value. If the itemValue is not of type
<classname>String</classname>, a converter must be specified for this
itemValue using either the <varname>converter</varname> attribute, or a nested
<sgmltag><f:converter></sgmltag> tag.
</para>
<example
id="exam-Component_Reference-richorderingList-ItemLabel_use">
<title>ItemLabel/ItemValue use</title>
@@ -2294,14 +2294,14 @@
</variablelist>
</example>
<para>
- The arrow keys on a keyboard can be used to highlight different items in the list.
Pressing <keycap>ctrl</keycap> modifier with the arrow keys will move the
selected item up or down within the list.
+ The arrow keys on a keyboard can be used to highlight different items in the list.
Pressing the <keycap>ctrl</keycap> modifier with the arrow keys will move the
selected item up or down within the list.
</para>
</section>
<section id="sect-Component_Reference-richorderingList-Column_layout">
<title>Column Layout</title>
<para>
- In addition to the above simple itemLabel display, the
<sgmltag><rich:orderingList></sgmltag> supports a columnar
layout of the itemValues to be sorted. This is achieved by nesting
<sgmltag><rich:column></sgmltag> tags within the ordering list,
and referencing the <varname>var</varname> attribute from within the
<sgmltag><rich:column></sgmltag> EL.
+ In addition to the above simple itemLabel display, the
<sgmltag><rich:orderingList></sgmltag> supports a columnar
layout of the itemValues to be sorted. This is achieved by nesting
<sgmltag><rich:column></sgmltag> tags within the orderingList,
and referencing the <varname>var</varname> attribute from within the
<sgmltag><rich:column></sgmltag> EL.
</para>
<example id="exam-Component_Reference-richorderingList-richcolumn">
<title>Nested <sgmltag><rich:column></sgmltag>
tags</title>
@@ -2407,6 +2407,163 @@
<xi:include href="skinning/tabl-richorderingList.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
</section>
</section>
+
+ <!-- <rich:pickList> -->
+ <section id="sect-Component_Reference-Rich_inputs-pickList">
+ <title><sgmltag><rich:pickList></sgmltag></title>
+ <para>
+ The <sgmltag><rich:pickList></sgmltag> is a
component for selecting items from a list. Additionally, it allows for the selected items
to be ordered (client-side). From the client side perspective, items are added/removed
from the source list, and removed/added to the target list. However it is important to
note that the server-side source of items is never modified, and always represents the
list of all items available for selection. If the list of unselected items is required,
it can be determined by subtracting the collection of all selected items from the
collection of all available items.
+ </para>
+ <figure id="figu-Component_Reference-richpickList-richpickList">
+ <title><sgmltag><rich:select></sgmltag></title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/figu-Component_Reference-richpickList-richpickList.png"
format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>
+ A <sgmltag><rich:pickList></sgmltag> component.
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+
+ <section id="sect-Component_Reference-richpickList-Basic_usage">
+ <title>Basic usage</title>
+ <para>
+ To use the <sgmltag><rich:pickList></sgmltag> bind the
<varname>value</varname> attribute to the target list, where the selected
items will be stored. The list of source items is provided by nesting a
<classname>SelectItem</classname> source, such as a
<sgmltag><f:selectItems></sgmltag> tag, or a list of
<sgmltag><f:selectItem></sgmltag> tags. If the itemValue of the
<classname>SelectItem</classname> is not of type
<classname>String</classname>, a converter must be specified for this
itemValue using either the <varname>converter</varname> attribute, or a nested
<sgmltag><f:converter></sgmltag> tag.
+ </para>
+ <example id="exam-Component_Reference-richpickList-ItemLabel_use">
+ <title>Simple pickList use</title>
+ <variablelist>
+ <varlistentry>
+ <term>Using the default <classname>SelectItem</classname>
itemLabel to generate the pickList source and target items.</term>
+ <listitem>
+ <programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Component_Reference-richpickList-ItemLabel_use.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </example>
+ <para>
+ The items in the target list can be ordered client-side by setting the
<varname>orderable</varname> attribute of the
<sgmltag><rich:pickList></sgmltag> tag to
<code>true</code>. The arrow keys on a keyboard can then be used to highlight
different items in the target list, and pressing the <keycap>ctrl</keycap>
modifier with the arrow keys will move the selected item up or down within the target
list.
+ </para>
+ </section>
+
+ <section id="sect-Component_Reference-richpickList-Column_layout">
+ <title>Column Layout</title>
+ <para>
+ In addition to the above simple <classname>SelectItem</classname>
itemLabel display, the <sgmltag><rich:pickList></sgmltag>
supports a columnar layout of the items to be selected. This is achieved by adding a
<varname>var</varname> attribute used to represent the collection of nested
<classname>SelectItems</classname>, and nesting
<sgmltag><rich:column></sgmltag> tags within the pickList. The
<varname>var</varname> attribute of the
<sgmltag><f:selectItem></sgmltag> is then referenced from within
the <sgmltag><rich:column></sgmltag> EL.
+ </para>
+ <example id="exam-Component_Reference-richpickList-richcolumn">
+ <title>Nested <sgmltag><rich:column></sgmltag>
tags</title>
+ <variablelist>
+ <varlistentry>
+ <term>Using <sgmltag><rich:column></sgmltag> tags
nested within the
<sgmltag><rich:pickList></sgmltag></term>
+ <listitem>
+ <programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Component_Reference-richpickList-richcolumn_use.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </example>
+ </section>
+
+ <section
id="sect-Component_Reference-richpickList-JavaScript_API">
+ <title>JavaScript API</title>
+ <para>
+ The <sgmltag><rich:pickList></sgmltag> component can be
controlled through the JavaScript API. The JavaScript API provides the following
functions:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><function>getSourceList()</function></term>
+ <listitem>
+ <para>
+ Returns the javascript list object backing the
<sgmltag><rich:pickList></sgmltag> source list. This list can
be used to select/unselect item(s).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>getTargetList()</function></term>
+ <listitem>
+ <para>
+ Returns the javascript list object backing the
<sgmltag><rich:pickList></sgmltag> target list. This list can
be used to select/unselect item(s).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>add()</function></term>
+ <listitem>
+ <para>
+ Add the currently selected items to the target list, removing them from
the source list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>addAll()</function></term>
+ <listitem>
+ <para>
+ Add all the source items to the target list, removing them from the
source list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>remove()</function></term>
+ <listitem>
+ <para>
+ Remove the currently selected items from the target list, adding them to
the source list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>removeAll()</function></term>
+ <listitem>
+ <para>
+ Remove all the source items from the target list, adding them to the
source list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>toggleButtons()</function></term>
+ <listitem>
+ <para>
+ Activate/de-activate the pickList buttons based on the current component
item state.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section
id="sect-Component_Reference-richpickList-Reference_data">
+ <title>Reference data</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <parameter>component-type</parameter>:
<classname>org.richfaces.PickList</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-class</parameter>:
<classname>org.richfaces.component.UIPickList</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-family</parameter>:
<classname>org.richfaces.SelectMany</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>renderer-type</parameter>:
<classname>org.richfaces.PickListRenderer</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section
id="sect-Component_Reference-richpickList-Style_classes_and_skin_parameters">
+ <title>Style classes and skin parameters</title>
+ <xi:include href="skinning/tabl-richpickList.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </section>
+ </section>
+
</chapter>
Added:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richpickList-ItemLabel_use.xml_sample
===================================================================
---
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richpickList-ItemLabel_use.xml_sample
(rev 0)
+++
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richpickList-ItemLabel_use.xml_sample 2011-11-08
20:00:36 UTC (rev 22910)
@@ -0,0 +1,7 @@
+<rich:pickList value="#{listSelectBean.selectedCapitals}"
+ sourceCaption="Available cities" targetCaption="Selected
cities"
+ listWidth="170px" listHeight="100px"
+ orderable="true">
+ <f:selectItems value="#{listSelectBean.capitals}"
var="capital" itemValue="#{capital}"
itemLabel="#{capital.name}" />
+ <f:converter converterId="CapitalsConverter" />
+</rich:pickList>
\ No newline at end of file
Added:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richpickList-richcolumn_use.xml_sample
===================================================================
---
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richpickList-richcolumn_use.xml_sample
(rev 0)
+++
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richpickList-richcolumn_use.xml_sample 2011-11-08
20:00:36 UTC (rev 22910)
@@ -0,0 +1,16 @@
+<rich:pickList value="#{listSelectBean.selectedCapitals}"
var="capital" listHeight="200px">
+ <f:selectItems value="#{listSelectBean.capitals}" />
+ <f:converter converterId="CapitalsConverter" />
+ <rich:column>
+ <f:facet name="header">Flag</f:facet>
+ <h:graphicImage value="#{capital.stateFlag}" alt="flag"
width="33"/>
+ </rich:column>
+ <rich:column>
+ <f:facet name="header">Name</f:facet>
+ #{capital.name}
+ </rich:column>
+ <rich:column>
+ <f:facet name="header">State</f:facet>
+ #{capital.state}
+ </rich:column>
+</rich:pickList>
\ No newline at end of file
Added:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-richpickList-richpickList.png
===================================================================
(Binary files differ)
Property changes on:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-richpickList-richpickList.png
___________________________________________________________________
Added: svn:mime-type
+ application/octet-stream
Added:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/skinning/tabl-richpickList.xml
===================================================================
---
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/skinning/tabl-richpickList.xml
(rev 0)
+++
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/skinning/tabl-richpickList.xml 2011-11-08
20:00:36 UTC (rev 22910)
@@ -0,0 +1,244 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE table PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<table
id="tabl-richpickList-Style_classes_and_corresponding_skin_parameters">
+ <title>Style classes (selectors) and corresponding skin parameters</title>
+ <tgroup cols="3">
+ <colspec colname="class"/>
+ <colspec colname="skin"/>
+ <colspec colname="css"/>
+ <spanspec spanname="noskin" namest="skin"
nameend="css"/>
+ <thead>
+ <row>
+ <entry>Class (selector)</entry>
+ <entry>Skin Parameters</entry>
+ <entry>Mapped <acronym>CSS</acronym> properties</entry>
+ </row>
+ </thead>
+ <tbody>
+
+ <row>
+ <entry>
+ <variablelist>
+ <varlistentry>
+ <term><classname>.rf-pick</classname></term>
+ <listitem>
+ <para>
+ This class defines styles for the pickList control itself.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </entry>
+ <entry spanname="noskin">No skin parameters.</entry>
+ </row>
+
+ <row>
+ <entry>
+ <variablelist>
+ <varlistentry>
+ <term><classname>.rf-pick-cntr</classname></term>
+ <listitem>
+ <para>
+ This class defines styles for the container of the pickList control.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </entry>
+ <entry spanname="noskin">No skin
parameters.</entry>
+ </row>
+
+ <row>
+ <entry morerows="3">
+ <variablelist>
+ <varlistentry>
+ <term><classname>.rf-pick-src-cptn,
.rf-pick-tgt-cptn</classname></term>
+ <listitem>
+ <para>
+ These classes define styles for the source and target
captions of the pickList control.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </entry>
+
<entry><para><parameter>headerTextColor</parameter></para></entry>
+
<entry><para><property>color</property></para></entry>
+ </row>
+ <row>
+
<entry><para><parameter>headerSizeFont</parameter></para></entry>
+
<entry><para><property>font-size</property></para></entry>
+ </row>
+ <row>
+
<entry><para><parameter>headerFamilyFont</parameter></para></entry>
+
<entry><para><property>font-family</property></para></entry>
+ </row>
+ <row>
+
<entry><para><parameter>headerWeightFont</parameter></para></entry>
+
<entry><para><property>font-weight</property></para></entry>
+ </row>
+
+ <row>
+ <entry>
+ <variablelist>
+ <varlistentry>
+ <term><classname>.rf-pick-lst</classname></term>
+ <listitem>
+ <para>
+ This class defines styles for the items list of the pickList control.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </entry>
+ <entry spanname="noskin">No skin
parameters.</entry>
+ </row>
+
+ <row>
+ <entry morerows="4">
+ <variablelist>
+ <varlistentry>
+ <term><classname>.rf-pick-hdr</classname></term>
+ <listitem>
+ <para>
+ This class defines styles for the header of the items list.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </entry>
+
<entry><para><parameter>headerBackgroundColor</parameter></para></entry>
+ <entry><para><property>background-color</property></para></entry>
+ </row>
+ <row>
+
<entry><para><parameter>headerTextColor</parameter></para></entry>
+ <entry><para><property>color</property></para></entry>
+ </row>
+ <row>
+ <entry><para><parameter>headerSizeFont</parameter></para></entry>
+ <entry><para><property>font-size</property></para></entry>
+ </row>
+ <row>
+ <entry><para><parameter>headerFamilyFont</parameter></para></entry>
+ <entry><para><property>font-family</property></para></entry>
+ </row>
+ <row>
+ <entry><para><parameter>headerWeightFont</parameter></para></entry>
+ <entry><para><property>font-weight</property></para></entry>
+ </row>
+
+ <row>
+ <entry morerows="2">
+ <variablelist>
+ <varlistentry>
+ <term><classname>.rf-pick-opt</classname></term>
+ <listitem>
+ <para>
+ This class defines styles for an option in the pickList control.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </entry>
+ <entry><para><parameter>generalTextColor</parameter></para></entry>
+ <entry><para><property>color</property></para></entry>
+ </row>
+ <row>
+ <entry><para><parameter>generalSizeFont</parameter></para></entry>
+ <entry><para><property>font-size</property></para></entry>
+ </row>
+ <row>
+ <entry><para><parameter>generalFamilyFont</parameter></para></entry>
+ <entry><para><property>font-family</property></para></entry>
+ </row>
+
+ <row>
+ <entry>
+ <variablelist>
+ <varlistentry>
+ <term><classname>.rf-pick-sel</classname></term>
+ <listitem>
+ <para>
+ This class defines styles for the selected option of the pickList control.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </entry>
+ <entry><para><parameter>generalTextColor</parameter></para></entry>
+ <entry><para><property>border-color</property></para></entry>
+ </row>
+
+ <row>
+ <entry>
+ <variablelist>
+ <varlistentry>
+ <term><classname>.rf-pick-dflt-lbl</classname></term>
+ <listitem>
+ <para>
+ This class defines styles for the default label of the pickList control.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </entry>
+ <entry spanname="noskin">No skin parameters.</entry>
+ </row>
+
+ <row>
+ <entry morerows="1">
+ <variablelist>
+ <varlistentry>
+ <term><classname>.rf-pick-btn</classname></term>
+ <listitem>
+ <para>
+ This class defines styles for the button of the pickList control.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </entry>
+ <entry><para><parameter>headerBackgroundColor</parameter></para></entry>
+ <entry><para><property>background-color</property></para></entry>
+ </row>
+ <row>
+ <entry><para><parameter>panelBorderColor</parameter></para></entry>
+ <entry><para><property>border-left-color</property></para></entry>
+ </row>
+
+ <row>
+ <entry>
+ <variablelist>
+ <varlistentry>
+ <term><classname>.rf-pick-btn-dis</classname></term>
+ <listitem>
+ <para>
+ This class defines styles for the button of the pickList control when it is
disabled.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </entry>
+ <entry spanname="noskin">No skin parameters.</entry>
+ </row>
+
+ <row>
+ <entry>
+ <variablelist>
+ <varlistentry>
+ <term><classname>.rf-pick-lst-scrl</classname></term>
+ <listitem>
+ <para>
+ This class defines styles for the list scrollbar.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </entry>
+ <entry spanname="noskin">No skin parameters.</entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+</table>