[richfaces-svn-commits] JBoss Rich Faces SVN: r6126 - in trunk/docs/userguide: en/src/main/docbook and 2 other directories.
richfaces-svn-commits at lists.jboss.org
richfaces-svn-commits at lists.jboss.org
Sat Feb 16 11:03:58 EST 2008
Author: vsukhov
Date: 2008-02-16 11:03:58 -0500 (Sat, 16 Feb 2008)
New Revision: 6126
Added:
trunk/docs/userguide/en/src/main/docbook/included/pickList.desc.xml
trunk/docs/userguide/en/src/main/docbook/included/pickList.xml
trunk/docs/userguide/en/src/main/resources/images/pickList1.png
Modified:
trunk/docs/userguide/en/src/main/docbook/included/panel.xml
trunk/docs/userguide/en/src/main/docbook/master.xml
trunk/docs/userguide/pom.xml
Log:
http://jira.jboss.com/jira/browse/RF-2174 pickList component added to guide. Description done.
Done Key Features, Creating the Component Dynamically Using Java, Details of Usage, JavaScript API sections.
Modified: trunk/docs/userguide/en/src/main/docbook/included/panel.xml
===================================================================
--- trunk/docs/userguide/en/src/main/docbook/included/panel.xml 2008-02-16 15:38:36 UTC (rev 6125)
+++ trunk/docs/userguide/en/src/main/docbook/included/panel.xml 2008-02-16 16:03:58 UTC (rev 6126)
@@ -339,7 +339,7 @@
header redefined color and a text style in body is got.</para>
<figure>
<title><emphasis role="bold">
- <property><rich:panel></property> with redefined header and body text style</title>
+ <property><rich:panel></property></emphasis> with redefined header and body text style</title>
<mediaobject>
<imageobject>
Added: trunk/docs/userguide/en/src/main/docbook/included/pickList.desc.xml
===================================================================
--- trunk/docs/userguide/en/src/main/docbook/included/pickList.desc.xml (rev 0)
+++ trunk/docs/userguide/en/src/main/docbook/included/pickList.desc.xml 2008-02-16 16:03:58 UTC (rev 6126)
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section>
+ <sectioninfo>
+ <keywordset>
+ <keyword>pickList</keyword>
+ </keywordset>
+ </sectioninfo>
+ <section>
+ <title>Description</title>
+ <para>The <emphasis role="bold">
+ <property><rich:pickList></property>
+ </emphasis> is a component for ordering items in a list. This component provides possibilities similar to <emphasis role="bold"><property><rich:orderingList></property></emphasis>, except sorting items on the client side.
+ <emphasis role="bold">
+ <property><rich:pickList></property></emphasis> doesn't have this possibility.
+ </para>
+ <figure>
+ <title><emphasis role="bold">
+ <property><rich:pickList></property>
+ </emphasis> component</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/pickList1.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ </section>
+<section>
+ <title>Key Features</title>
+ <itemizedlist>
+ <listitem>Highly customizable look and feel</listitem>
+ <!--listitem>Customizable component layout (captions, headers, list items and ordering control set)</listitem-->
+ <!--listitem>Disabled/enabled ordering controls</listitem-->
+ <listitem>Multiple selection of list items</listitem>
+ <listitem>Keyboard support</listitem>
+ <!--listitem>Possibility to manage selection from
+ <itemizedlist>
+ <listitem>Keyboard</listitem>
+ <listitem>Server side</listitem>
+ </itemizedlist>
+ </listitem-->
+ </itemizedlist>
+</section>
+</section>
+
\ No newline at end of file
Added: trunk/docs/userguide/en/src/main/docbook/included/pickList.xml
===================================================================
--- trunk/docs/userguide/en/src/main/docbook/included/pickList.xml (rev 0)
+++ trunk/docs/userguide/en/src/main/docbook/included/pickList.xml 2008-02-16 16:03:58 UTC (rev 6126)
@@ -0,0 +1,438 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section>
+ <sectioninfo>
+ <keywordset>
+ <keyword>rich:pickList</keyword>
+ <keyword>pickList</keyword>
+ </keywordset>
+ </sectioninfo>
+ <table>
+ <title>Component identification parameters</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Name</entry>
+
+ <entry>Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>component-type</entry>
+
+ <entry>org.richfaces.PickList</entry>
+ </row>
+ <row>
+ <entry>component-class</entry>
+
+ <entry>org.richfaces.component.html.HtmlPickList</entry>
+ </row>
+ <row>
+ <entry>component-family</entry>
+
+ <entry>org.richfaces.PickList</entry>
+ </row>
+ <row>
+ <entry>renderer-type</entry>
+
+ <entry>org.richfaces.PickListRenderer</entry>
+ </row>
+ <row>
+ <entry>tag-class</entry>
+
+ <entry>org.richfaces.taglib.PickListTagHandler</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <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[...<pickList:pickList
+ copyControlLabel = "#{pickBean.copyLabel}"
+ value="#{pickBean.listValues}">
+ <f:selectItems value="#{pickBean.testList}"/>
+</pickList:pickList>
+...]]></programlisting>
+ </section>
+ <section>
+ <title>Creating the Component Dynamically Using Java</title>
+
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="JAVA"><![CDATA[import org.richfaces.component.html.HtmlPickList;
+...
+HtmlPickList myPickList = new HtmlPickList();
+...]]></programlisting>
+ </section>
+ <section>
+ <title>Details of Usage</title>
+
+ <!--maintenance of component orderingList-->
+
+ <para>The <emphasis role="bold">
+ <property><rich:pickList></property>
+ </emphasis> component consists of <itemizedlist>
+ <listitem><property>Item list</property> element that displays a list of items. It
+ has three different representations for a single element: common, selected,
+ active. Combination of these states is possible.</listitem>
+ <listitem>
+ <property>Ordering controls set</property>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <!-- attributes of component orderingList -->
+
+ <para>The <emphasis>
+ <property> "value"</property>
+ </emphasis>
+ attribute is used to access the values of a list. </para>
+
+ <para> In the example
+ below after submitting the form you can see the <emphasis role="bold">
+ <property><rich:pickList></property></emphasis> component with the main attributes
+ and the <emphasis role="bold">
+ <property><h:panelGrid></property></emphasis> where you can set the values.</para>
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[...
+<h:form>
+ <h:panelGrid columns="2">
+ <h:outputText value="set target list width: "></h:outputText>
+ <h:inputText value="#{pickBean.targetListWidth}"></h:inputText>
+ <h:outputText value="set source list width: "></h:outputText>
+ <h:inputText value="#{pickBean.sourceListWidth}"></h:inputText>
+ <h:outputText value="set list heights: "></h:outputText>
+ <h:inputText value="#{pickBean.listsHeight}"></h:inputText>
+ <h:outputText value="set 'CopyAll' control label: "></h:outputText>
+ <h:inputText value="#{pickBean.copyAllLabel}"></h:inputText>
+ <h:outputText value="set 'Copy' control label: "></h:outputText>
+ <h:inputText value="#{pickBean.copyLabel}"></h:inputText>
+ <h:outputText value="set 'Remove' control label: "></h:outputText>
+ <h:inputText value="#{pickBean.removeLabel}"></h:inputText>
+ <h:outputText value="set 'RemoveAll' control label: "></h:outputText>
+ <h:inputText value="#{pickBean.removeAllLabel}"></h:inputText>
+ </h:panelGrid>
+ <pickList:pickList valueChangeListener="#{pickBean.selectionChanged}" listsHeight="#{pickBean.listsHeight}"
+sourceListWidth="#{pickBean.sourceListWidth}" targetListWidth="#{pickBean.targetListWidth}" copyAllControlLabel = "#{pickBean.copyAllLabel}"
+copyControlLabel = "#{pickBean.copyLabel}" removeControlLabel = "#{pickBean.removeLabel}"
+removeAllControlLabel ="#{pickBean.removeAllLabel}" value="#{pickBean.listValues}">
+ <f:selectItem itemValue="cat" itemLabel="cat"/>
+ <f:selectItem itemValue="dog" itemLabel="dog"/>
+ <f:selectItems value="#{pickBean.testList}"/>
+ </pickList:pickList>
+ <h:commandButton value="Submit" action="none"/>
+</h:form>
+...]]></programlisting>
+
+ <!-- ordering control set-->
+ <para>
+ The <emphasis role="bold">
+ <property><rich:pickList></property></emphasis>
+ component provides changing "height" and "width" parameters of lists by using such attributes as:
+ <itemizedlist>
+ <listitem>
+ <emphasis>
+ <property> "listsHeight"</property></emphasis> that defines height of the list in "px".
+
+ </listitem>
+ <listitem>
+ <emphasis>
+ <property> "targetListWidth"</property></emphasis> that defines width of a target list in "px".
+
+ </listitem>
+ <listitem>
+ <emphasis>
+ <property> "sourceListWidth"</property></emphasis> that defines width of a source list in "px".
+
+ </listitem>
+ </itemizedlist>
+ </para>
+<para>
+ The <emphasis role="bold">
+ <property><rich:pickList></property></emphasis> component has performance to change the "Button labels" with the help of such attributes as:
+ <itemizedlist>
+ <listitem>
+ <emphasis>
+ <property> "copyAllControlLabel"</property></emphasis> defines label for "Copy all" button.
+
+ </listitem>
+ <listitem>
+ <emphasis>
+ <property> "copyControlLabel"</property></emphasis> defines label for "Copy" button.
+
+ </listitem>
+ <listitem>
+ <emphasis>
+ <property> "removeControlLabel"</property></emphasis> defines label for "Remove" button.
+
+ </listitem>
+ <listitem>
+ <emphasis>
+ <property> "removeAllControlLabel"</property></emphasis> defines label for "Remove all" button.
+
+ </listitem>
+ </itemizedlist>
+</para>
+ <para>
+ The
+ <emphasis>
+ <property> "value"</property></emphasis> attribute defines array of items to be shown in a list.
+ With the help of this attribute you can input the list of items.
+ </para>
+
+ <table>
+ <title>Keyboard usage for elements selection</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Keys and combinations </entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <!--Sorting API -->
+ <row>
+ <entry>CTRL+click</entry>
+ <entry>Inverts selection for an item</entry>
+ </row>
+ <row>
+ <entry>SHIFT+click</entry>
+ <entry>Selects all rows from active one to a clicked row if they differ,
+ else select the active row. All other selections are cleared</entry>
+ </row>
+ <row>
+ <entry>D</entry>
+ <entry>Selects all elements inside the list if some active element is
+ already present in a list</entry>
+ </row>
+ <row>
+ <entry>Up, Down arrows</entry>
+ <entry>Changes the active and selected elements to the next or previous in a list</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </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>
+ <!--Sorting API -->
+ <!--
+ <row>
+ <entry>SortAscending()</entry>
+ <entry>Sorts items in the list ascending</entry>
+ </row>
+ <row>
+ <entry>SortDescending()</entry>
+ <entry>Sorts items in the list descending</entry>
+ </row>
+ <row>
+ <entry>Sort()</entry>
+ <entry>Inverts current sorting</entry>
+ </row>
+ -->
+
+ <!--Controls common API -->
+ <row>
+ <entry>Hide()</entry>
+ <entry>Hides ordering control</entry>
+ </row>
+ <row>
+ <entry>Show()</entry>
+ <entry>Shows ordering control</entry>
+ </row>
+ <row>
+ <entry>isShown()</entry>
+ <entry>Checks if current control is shown</entry>
+ </row>
+ <row>
+ <entry>Enable()</entry>
+ <entry>Enables ordering control</entry>
+ </row>
+ <row>
+ <entry>Disable()</entry>
+ <entry>Disables ordering control</entry>
+ </row>
+ <row>
+ <entry>isEnabled()</entry>
+ <entry>Checksif current control is enabled</entry>
+ </row>
+ <!--List managing API -->
+ <row>
+ <entry>getSelection()</entry>
+ <entry>Returns currently selected item</entry>
+ </row>
+ <row>
+ <entry>getItems()</entry>
+ <entry>Returns the collection of all items</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:pickList></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:pickList></property>
+ </emphasis> component</listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section>
+ <title>Skin Parameters Redefinition</title>
+
+ <table>
+ <title>Skin parameters redefinition for a wrapper <div> element of a list</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Skin parameters</entry>
+ <entry>CSS properties</entry>
+ </row>
+ </thead>
+ <tbody>
+
+ </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="images/orderingList_classes_1.png"/>
+ </imageobject>
+ </mediaobject-->
+
+ </figure>
+
+ <!--table id="OrderLC">
+ <title>Classes names that define a list representation</title>
+ <tgroup cols="2">
+ <thead>
+
+ </thead>
+ <tbody>
+
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </tbody>
+ </tgroup>
+ </table>
+ <para>In order to redefine styles for all <emphasis role="bold">
+ <property><rich:pickList></property>
+ </emphasis> components on a page using CSS, it's enough to create classes with the
+ same names (possible classes could be found in the tables <link linkend="OrderL"> above</link>) and define necessary properties in them. </para>
+
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="CSS"><![CDATA[...
+.rich-ordering-list-table-header-cell{
+ font-weight:bold;
+}
+...]]></programlisting>
+
+ <para>This is a result:</para>
+
+ <figure>
+ <title>Redefinition styles with predefined classes</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/orderinListClass.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>In the example the font weight for header text was changed.</para>
+
+ <para>Also it’s possible to change styles of particular <emphasis role="bold"
+ ><property><rich:orderingList></property></emphasis> component. In this case you should create own style classes and use them in corresponding <emphasis role="bold"
+ ><property><rich:orderingList></property></emphasis> <property>styleClass</property> attributes. An example is placed below:</para>
+
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="CSS"><![CDATA[...
+.myClass{
+ font-style:italic;
+}
+...]]></programlisting>
+ <para>The <emphasis><property>"rowClasses"</property></emphasis> attribute for <emphasis role="bold"
+ ><property><rich:orderingList></property></emphasis> is defined as it’s shown in the example below:</para>
+
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="CSS"><![CDATA[<rich:orderingList ... rowClasses="myClass"/>
+]]></programlisting>
+
+ <para>This is a result:</para>
+
+ <figure>
+ <title>Redefinition styles with own classes and <emphasis><property>styleClass</property></emphasis> attributes</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/orderinListStyle.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>As it could be seen on the picture above, the font style for rows was changed.</para-->
+
+ </section>
+
+ <section>
+ <title>Relevant Resources Links</title>
+ <para><ulink
+ url="http://livedemo.exadel.com/richfaces-demo/richfaces/pickList.jsf?c=pickList"
+ >Here</ulink> you can see an example of <emphasis role="bold">
+ <property><rich:pickList></property>
+ </emphasis> usage and sources for the given example. </para>
+ </section>
+
+</section>
Modified: trunk/docs/userguide/en/src/main/docbook/master.xml
===================================================================
--- trunk/docs/userguide/en/src/main/docbook/master.xml 2008-02-16 15:38:36 UTC (rev 6125)
+++ trunk/docs/userguide/en/src/main/docbook/master.xml 2008-02-16 16:03:58 UTC (rev 6126)
@@ -53,6 +53,7 @@
<!ENTITY componentControl_table SYSTEM "../../../target/generated/componentControl.xml">
<!ENTITY columns_table SYSTEM "../../../target/generated/columns.xml">
<!ENTITY comboBox_table SYSTEM "../../../target/generated/comboBox.xml">
+<!ENTITY pickList_table SYSTEM "../../../target/generated/pickList.xml">
<!ENTITY coreComponents_table SYSTEM "../../../target/generated/a4j.xml">
@@ -111,6 +112,7 @@
&panel_table;
&panelBar_table;
&panelMenu_table;
+&pickList_table;
&scrollableDataTable_table;
&separator_table;
&simpleTogglePanel_table;
Added: trunk/docs/userguide/en/src/main/resources/images/pickList1.png
===================================================================
(Binary files differ)
Property changes on: trunk/docs/userguide/en/src/main/resources/images/pickList1.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Modified: trunk/docs/userguide/pom.xml
===================================================================
--- trunk/docs/userguide/pom.xml 2008-02-16 15:38:36 UTC (rev 6125)
+++ trunk/docs/userguide/pom.xml 2008-02-16 16:03:58 UTC (rev 6126)
@@ -86,12 +86,24 @@
${project.version}
</version>
</artifactItem>
-
+
<artifactItem>
<groupId>
org.richfaces.ui
</groupId>
<artifactId>
+ pickList
+ </artifactId>
+ <version>
+ ${project.version}
+ </version>
+ </artifactItem>
+
+ <artifactItem>
+ <groupId>
+ org.richfaces.ui
+ </groupId>
+ <artifactId>
componentControl
</artifactId>
<version>
@@ -674,7 +686,7 @@
<imagePathSettingRequired>
true
</imagePathSettingRequired>
- </format>
+ </format >
<format>
<formatName>html</formatName>
<stylesheetResource>
More information about the richfaces-svn-commits
mailing list