[richfaces-svn-commits] JBoss Rich Faces SVN: r6126 - in trunk/docs/userguide: en/src/main/docbook and 2 other directories.

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>&lt;rich:panel&gt;</property> with redefined header and body text style</title> + <property>&lt;rich:panel&gt;</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>&lt;rich:pickList&gt;</property> + </emphasis> is a component for ordering items in a list. This component provides possibilities similar to <emphasis role="bold"><property>&lt;rich:orderingList&gt;</property></emphasis>, except sorting items on the client side. + <emphasis role="bold"> + <property>&lt;rich:pickList&gt;</property></emphasis> doesn't have this possibility. + </para> + <figure> + <title><emphasis role="bold"> + <property>&lt;rich:pickList&gt;</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>&lt;rich:pickList&gt;</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> &quot;value&quot;</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>&lt;rich:pickList&gt;</property></emphasis> component with the main attributes + and the <emphasis role="bold"> + <property>&lt;h:panelGrid&gt;</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>&lt;rich:pickList&gt;</property></emphasis> + component provides changing &quot;height&quot; and &quot;width&quot; parameters of lists by using such attributes as: + <itemizedlist> + <listitem> + <emphasis> + <property> &quot;listsHeight&quot;</property></emphasis> that defines height of the list in &quot;px&quot;. + + </listitem> + <listitem> + <emphasis> + <property> &quot;targetListWidth&quot;</property></emphasis> that defines width of a target list in &quot;px&quot;. + + </listitem> + <listitem> + <emphasis> + <property> &quot;sourceListWidth&quot;</property></emphasis> that defines width of a source list in &quot;px&quot;. + + </listitem> + </itemizedlist> + </para> +<para> + The <emphasis role="bold"> + <property>&lt;rich:pickList&gt;</property></emphasis> component has performance to change the &quot;Button labels&quot; with the help of such attributes as: + <itemizedlist> + <listitem> + <emphasis> + <property> &quot;copyAllControlLabel&quot;</property></emphasis> defines label for &quot;Copy all&quot; button. + + </listitem> + <listitem> + <emphasis> + <property> &quot;copyControlLabel&quot;</property></emphasis> defines label for &quot;Copy&quot; button. + + </listitem> + <listitem> + <emphasis> + <property> &quot;removeControlLabel&quot;</property></emphasis> defines label for &quot;Remove&quot; button. + + </listitem> + <listitem> + <emphasis> + <property> &quot;removeAllControlLabel&quot;</property></emphasis> defines label for &quot;Remove all&quot; button. + + </listitem> + </itemizedlist> +</para> + <para> + The + <emphasis> + <property> &quot;value&quot;</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>&lt;rich:pickList&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:pickList&gt;</property> + </emphasis> component</listitem> + </itemizedlist> + </para> + </section> + + <section> + <title>Skin Parameters Redefinition</title> + + <table> + <title>Skin parameters redefinition for a wrapper &lt;div&gt; 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>&lt;rich:pickList&gt;</property> + </emphasis> components on a page using CSS, it&apos;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>&lt;rich:orderingList&gt;</property></emphasis> component. In this case you should create own style classes and use them in corresponding <emphasis role="bold" + ><property>&lt;rich:orderingList&gt;</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>&quot;rowClasses&quot;</property></emphasis> attribute for <emphasis role="bold" + ><property>&lt;rich:orderingList&gt;</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.js... + >Here</ulink> you can see an example of <emphasis role="bold"> + <property>&lt;rich:pickList&gt;</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>