9:45 a.m.
Author: artdaw
Date: 2008-03-29 10:45:28 -0400 (Sat, 29 Mar 2008)
New Revision: 7408
Modified:
trunk/docs/userguide/en/src/main/docbook/included/column.xml
Log:
http://jira.jboss.com/jira/browse/RF-1740 - sorting feature reviewed.
Modified: trunk/docs/userguide/en/src/main/docbook/included/column.xml
===================================================================
--- trunk/docs/userguide/en/src/main/docbook/included/column.xml 2008-03-29 14:44:14 UTC
(rev 7407)
+++ trunk/docs/userguide/en/src/main/docbook/included/column.xml 2008-03-29 14:45:28 UTC
(rev 7408)
@@ -187,9 +187,11 @@
<title>Sorting and Filtering</title>
<section>
<title>Sorting</title>
- <para>In order to sort the columns you could use
<emphasis><property>"sortBy"</property></emphasis>
attribute which defines a bean property which is used for sorting of a
column.</para>
- <para>In order to sort the data in descending order, you should
double-click on the header of column, which you want to sort.</para>
<para>
+ In order to sort the columns you could use
<emphasis><property>"sortBy"</property></emphasis>
attribute
+ which defines a bean property which is used for sorting of a column. See
the following example.
+ </para>
+ <para>
<emphasis role="bold">Example:</emphasis>
</para>
<programlisting role="XML"><![CDATA[...
@@ -200,13 +202,13 @@
</f:facet>
<rich:column sortBy="#{cap.state}">
<f:facet name="header">
- <h:outputText value="State Name"></h:outputText>
+ <h:outputText value="State Name"/>
</f:facet>
- <h:outputText value="#{cap.state}"></h:outputText>
+ <h:outputText value="#{cap.state}"/>
</rich:column>
<rich:column sortBy="#{cap.name}">
<f:facet name="header">
- <h:outputText value="State
Capital"></h:outputText>
+ <h:outputText value="State Capital"/>
</f:facet>
<h:outputText value="#{cap.name}"/>
</rich:column>
@@ -215,7 +217,9 @@
...]]></programlisting>
<para>This is result:</para>
<figure>
- <title>Example sorting first column in ascending</title>
+ <title>
+ <emphasis
role="bold"><property><rich:column></property></emphasis>
with
<emphasis><property>"sortBy"</property></emphasis>
attribute
+ </title>
<mediaobject>
<imageobject>
<imagedata fileref="images/columnsort1.png"/>
@@ -223,20 +227,28 @@
</mediaobject>
</figure>
- <para>If you don't use
<emphasis><property>"sortOrder"</property></emphasis>
attribute then the first column will be sorted in ascending.</para>
- <para>Possible values:</para>
+ <para>
+ In order to change sort order you could use
<emphasis><property>"sortOrder"</property></emphasis>
attribute.
+ </para>
+ <para>Possible values are:</para>
<itemizedlist>
<listitem>
- "ASCENDING" - column will be sorted in ascending
+ "ASCENDING" - column is sorted in ascending
</listitem>
<listitem>
- "DESCENDING" - column will be sorted in descending
+ "DESCENDING" - column is sorted in descending
</listitem>
<listitem>
- "UNSORTED" - column won't be sorted
+ "UNSORTED" - column isn't sorted
</listitem>
</itemizedlist>
<para>
+ If you don't use
<emphasis><property>"sortOrder"</property></emphasis>
attribute then the first column is sorted in ascending.
+ </para>
+ <para>
+ In order to change the sort order, you could double-click on the header
of column, which you want to sort.
+ </para>
+ <para>
<emphasis role="bold">Example:</emphasis>
</para>
<programlisting role="XML"><![CDATA[...
@@ -260,10 +272,9 @@
</rich:dataTable>
</h:form>
...]]></programlisting>
- <para>Below you can see result:</para>
-
+ <para>Below you can see the result:</para>
<figure>
- <title>Sorting using the example of the
<emphasis><property>"sortOrder"</property></emphasis>
attribute</title>
+ <title><emphasis
role="bold"><property><rich:column></property></emphasis>
with
<emphasis><property>"sortOrder"</property></emphasis>
attribute</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/columnsort2.png"/>
@@ -271,9 +282,21 @@
</mediaobject>
</figure>
-
<para><emphasis><property>"sortPriority"</property></emphasis>
attribute is defined in the <emphasis
role="bold"><property>rich:dataTable</property></emphasis>
component which should be defined as set of column ids in the order the columns should be
set.</para>
- <para>If the columns sort order changed externally – sort priorities
should be used to define which columns will be sorted first.</para>
<para>
+ In the example above the first column is sorted in descending order. But
if recurring rows appear in the table the relative second column are sorted in ascending
order.
+ </para>
+ <para>
+ The
<emphasis><property>"sortPriority"</property></emphasis>
attribute
+ defines a set of column <property>ids</property> in the order
the columns could be set.
+ </para>
+ <para>
+ If the columns sort order changed externally sort priorities could be
used to define which columns will be sorted first.
+ </para>
+ <!--para>
+ Note that
<emphasis><property>"sortPriority"</property></emphasis>
attribute is defined in
+ the <emphasis
role="bold"><property><rich:dataTable></property></emphasis>
component!
+ </para-->
+ <para>
<emphasis role="bold">Example:</emphasis>
</para>
<programlisting role="XML"><![CDATA[...
@@ -297,88 +320,97 @@
</rich:dataTable>
</h:form>
...]]></programlisting>
-
<para><emphasis><property>"selfSorted"</property></emphasis>
attribute will manage if it's header will be clickable, icons rendered and sorting
will be fired after click on the header.
- So, developer will be able to define the
<emphasis><property>sortBy</property></emphasis> property and
conditionally use internal sorting.</para>
- <para>The default attribute is set to
<emphasis><property>"true"</property></emphasis>.</para>
<para>
- <emphasis role="bold">Example:</emphasis>
+ You could manage if the header of the column is clickable, icons rendered
and sorting is fired after click on the header
+ with the help of the following attributes:
</para>
- <programlisting role="XML"><![CDATA[...
-<h:form>
- <rich:dataTable value="#{capitalsBean.capitals}" var="cap"
width="300px" columnClasses="center">
- <f:facet name="header">
- <h:outputText value="Sorting Example"/>
- </f:facet>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The
<emphasis><property>"selfSorted"</property></emphasis>
attribute
+ which is defined in <emphasis
role="bold"><property><rich:dataTable></property></emphasis>
component.
+ Default value is "true". In the example
below the second column is unavailable for sorting.
+ </para>
+ <para>
+ <emphasis
role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[...
+<rich:dataTable value="#{capitalsBean.capitals}" var="cap">
<rich:column>
- <f:facet name="header">
- <h:outputText value="State Flag"></h:outputText>
- </f:facet>
- <h:graphicImage value="#{cap.stateFlag}"/>
+ <f:facet name="header">
+ <h:outputText value="State Flag"/>
+ </f:facet>
+ <h:graphicImage value="#{cap.stateFlag}"/>
</rich:column>
<rich:column sortBy="#{cap.state}" selfSorted="false">
- <f:facet name="header">
- <h:outputText value="State Name"></h:outputText>
- </f:facet>
- <h:outputText value="#{cap.state}"></h:outputText>
+ <f:facet name="header">
+ <h:outputText value="State Name"/>
+ </f:facet>
+ <h:outputText value="#{cap.state}"/>
</rich:column>
- <rich:column sortBy="#{cap.name}">
- <f:facet name="header">
- <h:outputText value="State Capital"></h:outputText>
- </f:facet>
- <h:outputText value="#{cap.name}"/>
- </rich:column>
- </rich:dataTable>
-</h:form>
-...
-]]></programlisting>
- <para>As a result, the second column will be unavailable for
sorting.</para>
-
<para><emphasis><property>"sortable"</property></emphasis>
attribute is used with <emphasis
role="bold"><property><rich:scrollableDataTable></property></emphasis>
component.</para>
- <para>Below you can find example code of usage and
result:</para>
- <para>
- <emphasis role="bold">Example:</emphasis>
- </para>
- <programlisting role="XML"><![CDATA[...
-<h:form>
- <rich:spacer height="30" />
- <rich:scrollableDataTable rowKeyVar="rkv"
frozenColCount="1"
- height="250px" width="300px" id="carList"
columnClasses="col"
- value="#{dataTableScrollerBean.allCars}" var="category"
rows="10"
+</rich:dataTable>
+...]]></programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ The
<emphasis><property>"sortable"</property></emphasis>
attribute which is used
+ with <emphasis
role="bold"><property><rich:scrollableDataTable></property></emphasis>
component.
+ In the following example only the first column could be
sorted.
+ </para>
+ <para>
+ <emphasis
role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[...
+<rich:scrollableDataTable rowKeyVar="rkv" frozenColCount="1"
+ id="carList" columnClasses="col"
value="#{dataTableScrollerBean.allCars}" var="category"
sortMode="single" binding="#{dataTableScrollerBean.table}"
selection="#{dataTableScrollerBean.selection}">
- <rich:column id="make" sortable="true">
+ <rich:column id="make" sortable="true">
<f:facet name="header">
- <h:outputText styleClass="headerText" value="Make" />
- </f:facet>
+ <h:outputText styleClass="headerText"
value="Make" />
+ </f:facet>
<h:outputText value="#{category.make}" />
- </rich:column>
- <rich:column id="model">
- <f:facet name="header">
- <h:outputText styleClass="headerText" value="Model" />
- </f:facet>
- <h:outputText value="#{category.model}" />
- </rich:column>
- <rich:column id="price">
- <f:facet name="header">
- <h:outputText styleClass="headerText" value="Price" />
- </f:facet>
- <h:outputText value="#{category.price}" />
- </rich:column>
- </rich:scrollableDataTable>
- <rich:spacer height="10px" />
-</h:form>
+ </rich:column>
+ <rich:column id="model">
+ <f:facet name="header">
+ <h:outputText styleClass="headerText"
value="Model" />
+ </f:facet>
+ <h:outputText value="#{category.model}" />
+ </rich:column>
+ <rich:column id="price">
+ <f:facet name="header">
+ <h:outputText styleClass="headerText"
value="Price" />
+ </f:facet>
+ <h:outputText value="#{category.price}" />
+ </rich:column>
+</rich:scrollableDataTable>
...]]></programlisting>
- <para>As a result, only the first column can be sorted.</para>
- <figure>
- <title>Sorting using the example of the
<emphasis><property>"sortable"</property></emphasis>
attribute</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/columnsort3.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
<para><emphasis><property>"sortExpression"</property></emphasis>
attribute defines a bean property which is used for sorting of a column. Usage of this
attribute is not recommendable.</para>
- <para>Sorting can't be used together with
pagination.</para>
+ <figure>
+ <title>The
<emphasis><property>"sortable"</property></emphasis>
attribute usage</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/columnsort3.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </listitem>
+ </itemizedlist>
+
+ <note>
+ <title>Note:</title>
+ <para>
+ The
<emphasis><property>"sortExpression"</property></emphasis>
attribute that defines
+ sorting property is deprecated! You could use the
<emphasis><property>"sortBy"</property></emphasis>
attribute
+ for the same purpose.
+ </para>
+ </note>
+
+ <para>
+ Sorting could not be used together with pagination.
+ Only row that currently on the client could be sorted.
+ </para>
</section>
+
<section>
<title>Filtering</title>
<para>In order to filter the column value, in accordance with the
entered value, it is necessary to use a
<emphasis><property>"filterBy"</property></emphasis>
attribute.</para>