Chapter 9. Tables and grids

This chapter covers all components related to the display of tables and grids.

9.1. `<a4j:repeat>`

The <a4j:repeat> component is used to iterate changes through a repeated collection of components. It allows specific rows of items to be updated without sending Ajax requests for the entire collection. The <a4j:repeat> component forms the basis for many of the tabular components detailed in Chapter 9, Tables and grids.

9.1.1. Basic usage

The contents of the collection are determined using Expression Language (EL). The data model for the contents is specified with the value attribute. The var attribute names the object to use when iterating through the collection. This object is then referenced in the relevant child components. Example 9.1, “<a4j:repeat> example” shows how to use <a4j:repeat> to maintain a simple table.

Example 9.1. <a4j:repeat> example


<table>

    <tbody>

        <a4j:repeat value="#{repeatBean.items}" var="item">

            <tr>

                <td><h:outputText value="#{item.code}" id="item1" /></td>

                <td><h:outputText value="#{item.price}" id="item2" /></td>

            </tr>

        </a4j:repeat>

    </tbody>

</table>

Each row of a table contains two cells: one showing the item code, and the other showing the item price. The table is generated by iterating through items in the repeatBeans.items data model.

9.1.2. Limited views and partial updates

The <a4j:repeat> component uses other attributes common to iteration components, such as the first attribute for specifying the first item for iteration, and the rows attribute for specifying the number of rows of items to display.

Specific cells, rows, and columns can be updated without sending Ajax requests for the entire collection. Components that cause the change can specify which part of the table to update through the render attribute. The render attribute specifies which part of a table to update:

render=cellId

Update the cell with an identifier of cellId within the row that contains the current component.

Instead of a specific identifier, the cellId reference could be a variable: render=#{bean.cellToUpdate}.

render=tableId:rowId

Update the row with an identifier of rowId within the table with an identifier of tableId. Alternatively, if the current component is contained within the table, use render=rowId.

Instead of a specific identifier, the tableId of rowId references could be variables: render=tableId:#{bean.rowToUpdate}.

render=tableId:rowId:cellId

Update the cell with an identifier of cellId, within the row with and identifier of rowId, within the table with an identifier of tableId.

Instead of a specific identifier, any of the references could be variables: render=tableId:#{bean.rowToUpdate}:cellId.

Alternatively, keywords can be used with the render attribute:

render=@column: Update the column that contains the current component.
render=@row: Update the row that contains the current component.
render=tableId:@body: Update the body of the table with the identifier of tableId. Alternatively, if the current component is contained within the table, use render=@body instead.
render=tableId:@header: Update the header of the table with the identifier of tableId. Alternatively, if the current component is contained within the table, use render=@header instead.
render=tableId:@footer: Update the footer of the table with the identifier of tableId. Alternatively, if the current component is contained within the table, use render=@footer instead.

9.1.3. Reference data

component-type: org.ajax4jsf.Repeat
component-class: org.ajax4jsf.component.html.HtmlAjaxRepeat
component-family: javax.faces.Data
renderer-type: org.ajax4jsf.components.RepeatRenderer

9.2. `<rich:dataTable>`

The <rich:dataTable> component is used to render a table, including the table's header and footer. It works in conjunction with the <rich:column> and <rich:columnGroup> components to list the contents of a data model.

<rich:extendedDataTable>

The <rich:dataTable> component does not include extended table features, such as data scrolling, row selection, and column reordering. These features are available as part of the <rich:extendedDataTable> component; refer to Section 9.6, “<rich:extendedDataTable>” for further details.

9.2.1. Basic usage

The value attribute points to the data model, and the var attribute specifies a variable to use when iterating through the data model.

9.2.2. Customizing the table

The first attribute specifies which item in the data model to start from, and the rows attribute specifies the number of items to list. The header, footer, and caption facets can be used to display text, and to customize the appearance of the table through skinning. demonstrates a simple table implementation.

Example 9.2. <rich:dataTable> example


<rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5">

    <f:facet name="caption">

        <h:outputText value="United States Capitals" />

    </f:facet>

    <f:facet name="header">

        <h:outputText value="Capitals and States Table" />

    </f:facet>

    <rich:column>

        <f:facet name="header">State Flag</f:facet>

            <h:graphicImage value="#{cap.stateFlag}"/>

        <f:facet name="footer">State Flag</f:facet>

    </rich:column>

    <rich:column>

        <f:facet name="header">State Name</f:facet>

            <h:outputText value="#{cap.state}"/>

        <f:facet name="footer">State Name</f:facet>

    </rich:column>

    <rich:column >

        <f:facet name="header">State Capital</f:facet>

            <h:outputText value="#{cap.name}"/>

        <f:facet name="footer">State Capital</f:facet>

    </rich:column>

    <rich:column>

        <f:facet name="header">Time Zone</f:facet>

            <h:outputText value="#{cap.timeZone}"/>

        <f:facet name="footer">Time Zone</f:facet>

    </rich:column>

    <f:facet name="footer">

        <h:outputText value="Capitals and States Table" />

    </f:facet>

</rich:dataTable>

[D]
Figure 9.1. <rich:dataTable> example

For details on filtering and sorting data tables, refer to Section 9.10, “Table filtering” and Section 9.11, “Table sorting”.

9.2.6. Style classes and skin parameters

Table 9.1. Style classes (selectors) and corresponding skin parameters

Class (selector)	Skin Parameters	Mapped CSS properties
`.rf-dt` This class defines styles for the table.	`tableBackgroundColor`	background-color
	`tableBorderWidth`	border-left-width, border-top-width
	`tableBorderColor`	border-left-color, border-top-color
`.rf-dt-cap` This class defines styles for the table caption.	No skin parameters.
`.rf-dt-r` This class defines styles for a table row.	No skin parameters.
`.rf-dt-fst-r` This class defines styles for the first row in a table.	No skin parameters.
`.rf-dt-c` This class defines styles for a table cell.	`tableBackgroundColor`	background-color
	`tableBorderWidth`	border-bottom-width, border-right-width
	`tableBorderColor`	border-bottom-color, border-right-color
	`generalTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
`.rf-dt-nd` This class defines styles for a node.	`tableBorderWidth`	border-bottom-width, border-right-width
	`tableBorderColor`	border-bottom-color, border-right-color
	`generalTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
`.rf-dt-hdr` This class defines styles for a table header.	No skin parameters.
`.rf-dt-hdr-fst` This class defines styles for the first header.	No skin parameters.
`.rf-dt-hdr-c` This class defines styles for a header cell.	`tableHeaderBackgroundColor`	background-color
	`tableBorderWidth`	border-bottom-width, border-right-width
	`tableBorderColor`	border-bottom-color, border-right-color
	`tableHeaderTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
`.rf-dt-shdr` This class defines styles for a table sub-header.	No skin parameters.
`.rf-dt-shdr-fst` This class defines styles for the first sub-header.	No skin parameters.
`.rf-dt-shdr-c` This class defines styles for a sub-header cell.	`tableHeaderBackgroundColor`	background-color
	`tableBorderWidth`	border-bottom-width, border-right-width
	`tableBorderColor`	border-bottom-color, border-right-color
	`tableHeaderTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
`.rf-dt-ftr` This class defines styles for a table footer.	No skin parameters.
`.rf-dt-ftr-fst` This class defines styles for the first footer.	No skin parameters.
`.rf-dt-ftr-c` This class defines styles for a footer cell.	`tableFooterBackgroundColor`	background-color
	`tableBorderWidth`	border-bottom-width, border-right-width
	`tableBorderColor`	border-bottom-color, border-right-color
	`generalTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
`.rf-dt-sftr` This class defines styles for a table sub-footer.	No skin parameters.
`.rf-dt-sftr-fst` This class defines styles for the first sub-footer.	No skin parameters.
`.rf-dt-sftr-c` This class defines styles for a sub-footer cell.	`tableFooterBackgroundColor`	background-color
	`tableBorderWidth`	border-bottom-width, border-right-width
	`tableBorderColor`	border-bottom-color, border-right-color
	`generalTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size

9.3. `<rich:column>`

The <rich:column> component facilitates columns in a table. It supports merging columns and rows, sorting, filtering, and customized skinning.

9.3.2. Spanning columns

Columns can be merged by using the colspan attribute to specify how many normal columns to span. The colspan attribute is used in conjunction with the breakBefore attribute on the next column to determine how the merged columns are laid out. Example 9.4, “Column spanning example”.

Example 9.4. Column spanning example


<rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5"> 

    <rich:column colspan="3">

        <h:graphicImage value="#{cap.stateFlag}"/>

    </rich:column>

    <rich:column breakBefore="true"> 

        <h:outputText value="#{cap.state}"/>

    </rich:column>

    <rich:column >

        <h:outputText value="#{cap.name}"/>

    </rich:column>

    <rich:column>

        <h:outputText value="#{cap.timeZone}"/>

    </rich:column>

</rich:dataTable>

[D]
Figure 9.3. Column spanning example

9.3.3. Spanning rows

Example 9.5. Row spanning example


<rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5"> 

    <rich:column rowspan="3">

        <f:facet name="header">State Flag</f:facet>

        <h:graphicImage value="#{cap.stateFlag}"/>

    </rich:column>

    <rich:column> 

        <f:facet name="header">State Info</f:facet>

        <h:outputText value="#{cap.state}"/>

    </rich:column>

    <rich:column breakBefore="true">

        <h:outputText value="#{cap.name}"/>

    </rich:column>

    <rich:column breakBefore="true">

        <h:outputText value="#{cap.timeZone}"/>

    </rich:column>

</rich:dataTable>

[D]
Figure 9.4. Row spanning example

For details on filtering and sorting columns, refer to Section 9.10, “Table filtering” and Section 9.11, “Table sorting”.

9.3.4. Reference data

component-type: org.richfaces.Column
component-class: org.richfaces.component.html.HtmlColumn
component-family: org.richfaces.Column
renderer-type: org.richfaces.renderkit.CellRenderer
tag-class: org.richfaces.taglib.ColumnTag

9.4. `<rich:columnGroup>`

The <rich:columnGroup> component combines multiple columns in a single row to organize complex parts of a table. The resulting effect is similar to using the breakBefore attribute of the <rich:column> component, but is clearer and easier to follow in the source code.

9.4.1. Complex headers

The <rich:columnGroup> can also be used to create complex headers in a table. Example 9.6, “Complex headers using column groups” and the resulting Figure 9.5, “Complex headers using column groups” demonstrate how complex headers can be achieved.

Example 9.6. Complex headers using column groups


<rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5" id="sublist"> 

    <f:facet name="header">

        <rich:columnGroup>

            <rich:column rowspan="2">

                <h:outputText value="State Flag"/>

            </rich:column>

            <rich:column colspan="3">

                <h:outputText value="State Info"/>

            </rich:column>

            <rich:column breakBefore="true">

                <h:outputText value="State Name"/>

            </rich:column>

            <rich:column>

                <h:outputText value="State Capital"/>

            </rich:column>

            <rich:column>

                <h:outputText value="Time Zone"/>

            </rich:column>

        </rich:columnGroup>

    </f:facet>

    <rich:column>

        <h:graphicImage value="#{cap.stateFlag}"/>

    </rich:column>

    <rich:column>

        <h:outputText value="#{cap.state}"/>

    </rich:column>

    <rich:column>

        <h:outputText value="#{cap.name}"/>

    </rich:column>

    <rich:column>

        <h:outputText value="#{cap.timeZone}"/>

    </rich:column>

</rich:dataTable>

[D]
Figure 9.5. Complex headers using column groups

9.4.2. Reference data

component-type: org.richfaces.ColumnGroup
component-class: org.richfaces.component.html.HtmlColumnGroup
component-family: org.richfaces.ColumnGroup
renderer-type: org.richfaces.ColumnGroupRenderer
tag-class: org.richfaces.taglib.ColumnGroupTag

9.5. `<rich:collapsibleSubTable>`

The <rich:collapsibleSubTable> component acts as a child element to a <rich:dataTable> component. It allows sections of a table to be grouped into collapsible sections. The <rich:collapsibleSubTable> component works with the <rich:collapsibleSubTableToggler> component, which allows the user to expand and collapse the sub tables.

9.5.1. Basic usage

The <rich:collapsibleSubTable> component requires the same basic attributes as the <rich:dataTable> component. The value attribute points to the collection, and the var attribute specifies a variable to use when iterating through the collection.

In addition, the <rich:collapsibleSubTable> component typically needs a corresponding <rich:collapsibleSubTableToggler> component to allow expanding and collapsing. Declare the id identifier on the <rich:collapsibleSubTable> element so that the <rich:collapsibleSubTableToggler> component can reference it. Refer to Section 9.5.5, “<rich:collapsibleSubTableToggler>” for details on the <rich:collapsibleSubTableToggler> component.

Example 9.7. Basic usage


<rich:dataTable value="#{carsBean.inventoryVendorLists}" var="list">

   <f:facet name="header">

      <rich:columnGroup>

         <rich:column colspan="6">

            <h:outputText value="Cars marketplace" />

         </rich:column>

         <rich:column breakRowBefore="true">

            <h:outputText value="Model" />

         </rich:column>

         <rich:column>

            <h:outputText value="Price" />

         </rich:column>

         <rich:column>

            <h:outputText value="Mileage" />

         </rich:column>

         <rich:column>

            <h:outputText value="VIN Code" />

         </rich:column>

         <rich:column>

            <h:outputText value="Items stock" />

         </rich:column>

         <rich:column>

            <h:outputText value="Days Live" />

         </rich:column>

      </rich:columnGroup>

   </f:facet>

   <rich:column colspan="6">

      <rich:collapsibleSubTableToggler for="sbtbl" />

      <h:outputText value="#{list.vendor}" />

   </rich:column>

   <rich:collapsibleSubTable value="#{list.vendorItems}" var="item" id="sbtbl"

      expandMode="client">

      <rich:column>

         <h:outputText value="#{item.model}" />

      </rich:column>

      <rich:column>

         <h:outputText value="#{item.price}" />

      </rich:column>

      <rich:column>

         <h:outputText value="#{item.mileage}" />

      </rich:column>

      <rich:column>

         <h:outputText value="#{item.vin}" />

      </rich:column>

      <rich:column>

         <h:outputText value="#{item.stock}" />

      </rich:column>

      <rich:column>

         <h:outputText value="#{item.daysLive}" />

      </rich:column>

      <f:facet name="footer">

         <h:outputText value="Total of #{list.vendor} Cars: #{list.count}" />

      </f:facet>

   </rich:collapsibleSubTable>

</rich:dataTable>

The resulting tables contains multiple sub-tables, grouping the list of cars by vendor. Each sub-table can be expanded or collapsed using the toggle with the vendor's name. The screenshot shows all sub-tables collapsed except for the sub-table for Ford cars.

[D]

9.5.2. Expanding and collapsing the sub-table

Use the boolean expanded attribute to control the current state of the sub-table.

The switching mode for performing submissions is determined by the expandMode attribute, which can have one of the following three values:

server: The default setting. Expansion of the <rich:collapsibleSubTable> component performs a common submission, completely re-rendering the page.
ajax: Expansion of the <rich:collapsibleSubTable> component performs an Ajax form submission, and the content of the data table is rendered.
client: Expansion of the <rich:collapsibleSubTable> component updates the data table on the client side.

9.5.3. Reference data

component-type: org.richfaces.CollapsibleSubTable
component-class: org.richfaces.component.html.HtmlCollapsibleSubTable
component-family: org.richfaces.CollapsibleSubTable
renderer-type: org.richfaces.CollapsibleSubTable
tag-class: org.richfaces.taglib.CollapsibleSubTableTag

9.5.4. Style classes

Table 9.2. Style classes (selectors) and corresponding skin parameters

Class (selector)	Skin Parameters	Mapped CSS properties
`.rf-cst` This class defines styles for the table.	No skin parameters.
`.rf-cst-r` This class defines styles for a table row.	No skin parameters.
`.rf-cst-fst-r` This class defines styles for the first row in a table.	No skin parameters.
`.rf-cst-c` This class defines styles for a table cell.	`tableBackgroundColor`	background-color
	`tableBorderWidth`	border-bottom-width, border-right-width
	`tableBorderColor`	border-bottom-color, border-right-color
	`generalTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
`.rf-cst-hdr` This class defines styles for a table header.	No skin parameters.
`.rf-cst-hdr-fst` This class defines styles for the first header.	No skin parameters.
`.rf-cst-hdr-fst-r` This class defines styles for the first row in the header.	No skin parameters.
`.rf-cst-hdr-c` This class defines styles for a header cell.	`tableSubHeaderBackgroundColor`	background-color
	`tableBorderWidth`	border-bottom-width, border-right-width
	`tableBorderColor`	border-bottom-color, border-right-color
	`generalTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
`.rf-cst-shdr` This class defines styles for a table sub-header.	No skin parameters.
`.rf-cst-shdr-fst` This class defines styles for the first sub-header.	No skin parameters.
`.rf-cst-shdr-c` This class defines styles for a sub-header cell.	`tableSubHeaderBackgroundColor`	background-color
	`tableBorderWidth`	border-bottom-width, border-right-width
	`tableBorderColor`	border-bottom-color, border-right-color
	`generalTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
`.rf-cst-ftr` This class defines styles for a table footer.	No skin parameters.
`.rf-cst-ftr-fst` This class defines styles for the first footer.	No skin parameters.
`.rf-cst-ftr-c` This class defines styles for a footer cell.	`tableSubFooterBackgroundColor`	background-color
	`tableBorderWidth`	border-bottom-width, border-right-width
	`tableBorderColor`	border-bottom-color, border-right-color
	`generalTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
`.rf-cst-sftr` This class defines styles for a table sub-footer.	No skin parameters.
`.rf-cst-sftr-fst` This class defines styles for the first sub-footer.	No skin parameters.
`.rf-cst-sftr-c` This class defines styles for a sub-footer cell.	`tableSubFooterBackgroundColor`	background-color
	`tableBorderWidth`	border-bottom-width, border-right-width
	`tableBorderColor`	border-bottom-color, border-right-color
	`generalTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size

9.5.5. `<rich:collapsibleSubTableToggler>`

The <rich:collapsibleSubTableToggler> component provides a toggle control for the user to expand and collapse sub-tables.

9.5.5.1. Basic usage

The <rich:collapsibleSubTableToggler> component requires the for attribute. The for attribute references the id identifier of the <rich:collapsibleSubTable> component to control.

Refer to Example 9.7, “Basic usage” for an example using the <rich:collapsibleSubTable> component. In the example, the toggle control is placed in a column that spans the width of the table. Output text next to the toggle control displays the car vendor's name for that sub-table.

9.5.5.2. Reference data

component-type: org.richfaces.CollapsibleSubTableToggler
component-class: org.richfaces.component.html.HtmlCollapsibleSubTableToggler
component-family: org.richfaces.CollapsibleSubTableToggler
renderer-type: org.richfaces.CollapsibleSubTableToggler
tag-class: org.richfaces.taglib.CollapsibleSubTableTogglerTag

9.5.5.3. Style classes and skin parameters

Style classes (selectors)

.rf-csttg: This class defines styles for a toggle control.
.rf-csttg-exp: This class defines styles for a toggle control which expands the sub-table.
.rf-csttg-colps: This class defines styles for a toggle control which collapses the sub-table.

9.6. `<rich:extendedDataTable>`

The <rich:extendedDataTable> component builds on the functionality of the <rich:dataTable> component, adding features such as data scrolling, row and column selection, and rearranging of columns.

The <rich:extendedDataTable> component includes the following main attributes not included in the <rich:dataTable> component:

clientRows
frozenColumns
height
onselectionchange
selectedClass
selection
selectionMode

The <rich:extendedDataTable> component does not include the following attributes available with the <rich:dataTable> component:

breakBefore
columnGroup
colSpan
rowSpan

Complex sub-tables

Due to the complex mark-up involved in the <rich:extendedDataTable> component, it does not support the use of the <rich:collapsibleSubTable> component. The <rich:collapsibleSubTable> component is only available with the <rich:dataTable> component.

9.6.1. Basic usage

Basic use of the <rich:extendedDataTable> component requires the value and var attributes, the same as with the <rich:dataTable> component. Refer to Section 9.2, “<rich:dataTable>” for details.

9.6.2. Table appearance

The height attribute defines the height of the table on the page. This is set to 100% by default. The width of the table can be set by using the width attribute. As with the <rich:dataTable> component, the look of the <rich:extendedDataTable> component can be customized and skinned using the header and footer facets.

9.6.3. Extended features

Example 9.8. <rich:extendedDataTable> example

This example <rich:extendedDataTable> component demonstrates horizontal and vertical scrolling and frozen columns. Each feature is detailed in this section.


<rich:extendedDataTable value="#{carsBean.allInventoryItems}"

                        var="car" id="table" frozenColumns="2"

                        style="height:300px; width:500px;" selectionMode="none">

   <f:facet name="header">

      <h:outputText value="Cars marketplace" />

   </f:facet>

   <rich:column>

      <f:facet name="header">

         <h:outputText value="vendor" />

      </f:facet>

      <h:outputText value="#{car.vendor}" />

   </rich:column>

   <rich:column>

      <f:facet name="header">

         <h:outputText value="Model" />

      </f:facet>

      <h:outputText value="#{car.model}" />

   </rich:column>

   <rich:column>

      <f:facet name="header">

         <h:outputText value="Price" />

      </f:facet>

      <h:outputText value="#{car.price}" />

   </rich:column>

   <rich:column>

      <f:facet name="header">

         <h:outputText value="Mileage" />

      </f:facet>

      <h:outputText value="#{car.mileage}" />

   </rich:column>

   <rich:column>

      <f:facet name="header">

         <h:outputText value="VIN Code" />

      </f:facet>

      <h:outputText value="#{car.vin}" />

   </rich:column>

   <rich:column>

      <f:facet name="header">

         <h:outputText value="Items stock" />

      </f:facet>

      <h:outputText value="#{car.stock}" />

   </rich:column>

   <rich:column>

      <f:facet name="header">

         <h:outputText value="Days Live" />

      </f:facet>

      <h:outputText value="#{car.daysLive}" />

   </rich:column>

</rich:extendedDataTable>

[D]

9.6.3.1. Scrolling

The example table shown in Example 9.8, “<rich:extendedDataTable> example” features both horizontal and vertical scrolling. Scrolling occurs automatically when the contents of the table exceed the dimensions specified with the height and width attributes. Headers and footers remain in place and visible when the table is scrolled.

Large tables can use Ajax "lazy" loading to cache data on the client during scrolling. Use the clientRows attribute to specify the number of rows to load. The specified number of rows are loaded on the initial rendering and with every vertical scroll. If the clientRows attribute is not specified, all the rows are loaded on the client without the use of Ajax.

In addition to Ajax scrolling, the <rich:extendedDataTable> component can also be used with the <rich:dataScroller> component in the same way as a regular <rich:dataTable> component. Refer to Section 9.9, “<rich:dataScroller>” for full details on using the <rich:dataScroller> component.

9.6.3.2. Frozen columns

The example table shown in Example 9.8, “<rich:extendedDataTable> example” has the first two columns frozen so that they remain visible if the user scrolls horizontally through the table. Note that the horizontal scrollbar does not encompass these frozen columns. To freeze columns, use the frozenColumns attribute to specify the number of columns on the left-hand side of the table to freeze.

9.6.3.3. Row selection

Row selection is determined by the selectionMode attribute. Setting the attribute to none allows for no row selection capability. The example table shown in Example 9.8, “<rich:extendedDataTable> example” does not allow row selection.

Setting the selectionMode attribute to single allows the user to select a single row at a time using the mouse. With the selectionMode attribute set to multiple, the user can select multiple rows. Holding down the Ctrl key while clicking selects additional rows with each click. Holding down the Shift key while clicking selects all the rows in a range.

The selection attribute points to a collection of objects. It holds the rowKey identifiers to track which rows are selected. Example 9.9, “Selecting multiple rows” shows how to implement multiple row selection in the same table from Example 9.8, “<rich:extendedDataTable> example”.

Example 9.9. Selecting multiple rows


<rich:extendedDataTable value="#{extTableSelectionBean.inventoryItems}" 

                        var="car" selection="#{extTableSelectionBean.selection}"

                        id="table" frozenColumns="2" 

                        style="height:300px; width:500px;" selectionMode="multiple">

   ...

The accompanying ExtSelectionBean bean handles which rows are selected. The rows are identified by their rowKey identifiers.

package org.richfaces.demo.tables;


import java.io.Serializable;

import java.util.ArrayList;

import java.util.Collection;

import java.util.List;


import javax.faces.bean.ManagedBean;

import javax.faces.bean.ManagedProperty;

import javax.faces.bean.SessionScoped;

import javax.faces.event.AjaxBehaviorEvent;


import org.richfaces.component.UIExtendedDataTable;

import org.richfaces.demo.tables.model.cars.InventoryItem;


@ManagedBean

@SessionScoped


public class ExtTableSelectionBean implements Serializable{


   private Collection<Object> selection;

   @ManagedProperty(value = "#{carsBean.allInventoryItems}")

   private List<InventoryItem> inventoryItems;

   private List<InventoryItem> selectionItems = new ArrayList<InventoryItem>();


   public void selectionListener(AjaxBehaviorEvent event){

      UIExtendedDataTable dataTable = (UIExtendedDataTable)event.getComponent();

      Object originalKey = dataTable.getRowKey();

      selectionItems.clear();

      for (Object selectionKey: selection) {

         dataTable.setRowKey(selectionKey);

         if (dataTable.isRowAvailable()){

            selectionItems.add((InventoryItem)dataTable.getRowData());

         }

      }

      dataTable.setRowKey(originalKey);

   }


   public Collection<Object> getSelection() {

      return selection;

   }


   public void setSelection(Collection<Object> selection) {

      this.selection = selection;

   }


   public List<InventoryItem> getInventoryItems() {

      return inventoryItems;

   }


   public void setInventoryItems(List<InventoryItem> inventoryItems) {

      this.inventoryItems = inventoryItems;

   }


   public List<InventoryItem> getSelectionItems() {

      return selectionItems;

   }


   public void setSelectionItems(List<InventoryItem> selectionItems) {

      this.selectionItems = selectionItems;

   }

}

[D]

9.6.3.4. Rearranging columns

Columns in a <rich:extendedDataTable> component can be rearranged by the user by dragging each column to a different position. A graphical representation of the column is displayed during dragging. Figure 9.6, “Dragging columns” illustrates the Price column being dragged to a new location. The small blue arrow indicates where the column will be moved to if it is dropped in the current position. Figure 9.7, “Rearranged columns” shows the result of dragging the Price column.

[D]

Figure 9.6. Dragging columns

[D]

Figure 9.7. Rearranged columns

9.6.3.5. Filtering and sorting

The <rich:extendedDataTable> component can include filtering and sorting in the same way as a regular <rich:dataTable> component. For full details on filtering tables, refer to Section 9.10, “Table filtering”. For full details on sorting tables, refer to Section 9.11, “Table sorting”.

9.6.4. JavaScript API

The <rich:extendedDataTable> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:

sort(): Sort the data table.
filter(): Filter the data table.
clearSorting(): Clear any sorting that is currently applied to the table.
clearFiltering(): Clear any filtering that is currently applied to the table.
selectRow(index): Select the row specified by the index parameter.
selectRows([startIndex, stopIndex]): Select all the rows in the table. Optionally, select only those rows between the indexes specified with the startIndex and stopIndex parameters.
deselectRow: Deselect the row that is currently selected.
setActiveRow(index): Set the active row to that specified by the index parameter.

9.6.5. Reference data

component-type: org.richfaces.ExtendedDataTable
component-class: org.richfaces.component.html.HtmlExtendedDataTable
component-family: org.richfaces.ExtendedDataTable
renderer-type: org.richfaces.ExtendedDataTableRenderer
tag-class: org.richfaces.taglib.ExtendedDataTableTag

9.6.6. Style classes and skin parameters

Table 9.3. Style classes (selectors) and corresponding skin parameters

Class (selector)	Skin Parameters	Mapped CSS properties
`.rf-edt` This class defines styles for the table.	`tableBorderWidth`, `tableBorderColor`	border
`.rf-edt` This class defines styles for the table.	`tableBackgroundColor`	background-color
`.rich-edt-cnt` This class defines styles for the table content.	No skin parameters.
`.rf-edt-c` This class defines styles for a table cell.	`tableBorderWidth`, `tableBorderColor`	border-bottom
`.rf-edt-c` This class defines styles for a table cell.	`tableBorderWidth`, `tableBorderColor`	border-right
`.rf-edt-c-cnt` This class defines styles for the contents of a cell.	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
`.rf-edt-tbl-hdr` This class defines styles for the table header.	`tableBorderWidth`, `tableBorderColor`	border-bottom
	`tableHeaderTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
	`tableHeaderTextColor`	color
`.rich-edt-hdr` This class defines styles for a header.	No skin parameters.
`.rf-edt-hdr-c` This class defines styles for a table header cell.	`tableBorderWidth`, `tableBorderColor`	border-bottom
	`tableBorderWidth`, `tableBorderColor`	border-right
`.rf-edt-hdr-c-cnt` This class defines styles for the contents of a header cell.	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
	`tableHeaderTextColor`	color
`.rf-edt-tbl-ftr` This class defines styles for the table footer.	`tableBorderWidth`, `tableBorderColor`	border-top
	`tableFooterBackgroundColor`	background-color
`.rich-edt-ftr` This class defines styles for a footer.	`tableBorderWidth`, `tableBorderColor`	border-top
`.rich-edt-ftr` This class defines styles for a footer.	`tableFooterBackgroundColor`	background-color
`.rich-edt-ftr-cnt` This class defines styles for the content of a footer.	No skin parameters.
`.rf-edt-ftr-c` This class defines styles for a table footer cell.	`tableBorderWidth`, `tableBorderColor`	border-bottom
	`tableBorderWidth`, `tableBorderColor`	border-right
`.rf-edt-ftr-c-cnt` This class defines styles for the contents of a footer cell.	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
	`generalTextColor`	color
`.rf-edt-ftr-emp` This class defines styles for an empty footer cell.	`tableBorderWidth`, `tableBorderColor`	border-right
`.rich-edt-ftr-fzn` This class defines styles for a frozen footer.	No skin parameters.
`.rich-edt-b` This class defines styles for the body of the table.	No skin parameters.
`.rf-edt-r-sel` This class defines styles for the selected row.	`tableBorderWidth`, `tableBorderColor`	border-right
`.rich-edt-r-act` This class defines styles for the active row.	No skin parameters.
`.rich-edt-rsz` This class defines styles for the table resizer.	No skin parameters.
`.rich-edt-rsz-cntr` This class defines styles for the resize container.	No skin parameters.
`.rich-edt-rsz-mkr` This class defines styles for the resize marker.	`generalTextColor`	border-left
`.rf-edt-rord` This class defines styles for the re-order functionality.	`tableBorderWidth`, `tableBorderColor`	border
	`tableHeaderBackgroundColor` / `tableBackgroundColor`	background-color
`.rich-edt-rord-mkr` This class defines styles for the re-order marker.	No skin parameters.
`.rich-edt-spcr` This class defines a spacer for Internet Explorer 7 compatibility.	No skin parameters.

9.7. `<rich:dataGrid>`

The <rich:dataGrid> component is used to arrange data objects in a grid. Values in the grid can be updated dynamically from the data model, and Ajax updates can be limited to specific rows. The component supports header, footer, and caption facets.

The <rich:dataGrid> component is similar in function to the JavaServer Faces <h:panelGrid> component. However, the <rich:dataGrid> component additionally allows iteration through the data model rather than just aligning child components in a grid layout.

[D]

Figure 9.8. The <rich:dataGrid> component

9.7.1. Basic usage

The <rich:dataGrid> component requires the value attribute, which points to the data model, and the var attribute, which holds the current variable for the collection of data.

9.7.2. Customizing the grid

The number of columns for the grid is specifed with the columns attribute, and the number of elements to layout among the columns is determined with the elements attribute. The first attribute references the zero-based element in the data model from which the grid starts.

Example 9.10. <rich:dataGrid> example


<rich:panel style="width:150px;height:200px;">

  <h:form>

    <rich:dataGrid value="#{dataTableScrollerBean.allCars}" var="car" columns="2" elements="4" first="1">

        <f:facet name="header">

          <h:outputText value="Car Store"></h:outputText>

      </f:facet>

      <rich:panel>

          <f:facet name="header">

            <h:outputText value="#{car.make} #{car.model}"></h:outputText>

          </f:facet>

          <h:panelGrid columns="2">

            <h:outputText value="Price:" styleClass="label"></h:outputText>

            <h:outputText value="#{car.price}"/>

            <h:outputText value="Mileage:" styleClass="label"></h:outputText>

            <h:outputText value="#{car.mileage}"/>

          </h:panelGrid>

      </rich:panel>

      <f:facet name="footer">

          <rich:datascroller></rich:datascroller>

      </f:facet>

    </rich:dataGrid>

  </h:form>

</rich:panel>

[D]
Figure 9.9. <rich:dataGrid> example

9.7.3. Partial updates

As <rich:dataGrid> the component is based on the <a4j:repeat> component, it can be partially updated with Ajax. Refer to Section 9.1.2, “Limited views and partial updates” for details on partially updating the <rich:dataGrid> component.

9.7.4. Reference data

component-type: org.richfaces.DataGrid
component-class: org.richfaces.component.html.HtmlDataGrid
component-family: org.richfaces.DataGrid
renderer-type: org.richfaces.DataGridRenderer
tag-class: org.richfaces.taglib.DataGridTag

9.7.5. Style classes and skin parameters

Table 9.4. Style classes (selectors) and corresponding skin parameters

Class (selector)	Skin Parameters	Mapped CSS properties
`.rf-dg` This class defines styles for the grid.	`tableBackgroundColor`	background-color
	`tableBorderWidth`	border-left-width, border-top-width
	`tableBorderColor`	border-left-color, border-top-color
`.rf-dg-cap` This class defines styles for the grid caption.	No skin parameters.
`.rf-dg-r` This class defines styles for a grid row.	No skin parameters.
`.rf-dg-c` This class defines styles for a grid cell.	`tableBorderWidth`	border-bottom-width, border-right-width
	`tableBorderColor`	border-bottom-color, border-right-color
	`generalTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
`.rf-dg-nd-c` This class defines styles for a node cell.	`tableBorderWidth`	border-bottom-width, border-right-width
	`tableBorderColor`	border-bottom-color, border-right-color
	`generalTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
`.rf-dg-th` This class defines styles for the grid header section.	`tableBorderWidth`	border-bottom-width
	`tableBorderColor`	border-bottom-color
`.rf-dg-h` This class defines styles for a grid header.	No skin parameters.
`.rf-dg-h-f` This class defines styles for the first header.	No skin parameters.
`.rf-dg-h-r` This class defines styles for a header row.	No skin parameters.
`.rf-dg-h-c` This class defines styles for a header cell.	`tableHeaderBackgroundColor`	background-color
	`tableBorderWidth`	border-bottom-width, border-right-width
	`tableBorderColor`	border-bottom-color, border-right-color
	`tableHeaderTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
`.rf-dg-f` This class defines styles for a grid footer.	No skin parameters.
`.rf-dg-f-f` This class defines styles for the first footer.	No skin parameters.
`.rf-dg-f-c` This class defines styles for a footer cell.	`tableFooterBackgroundColor`	background-color
	`tableBorderWidth`	border-bottom-width, border-right-width
	`tableBorderColor`	border-bottom-color, border-right-color
	`generalTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size

9.8. `<rich:list>`

The <rich:list> component renders a list of items. The list can be an numerically ordered list, an un-ordered bullet-point list, or a data definition list. The component uses a data model for managing the list items, which can be updated dynamically.

9.8.1. Basic usage

The var attribute names a variable for iterating through the items in the data model. The items to iterate through are determined with the value attribute by using EL (Expression Language).

9.8.2. Type of list

By default, the list is displayed as an un-ordered bullet-point list. The type attribute is used to specify different list types:

unordered

The default presentation. The list is presented as a series of bullet-points, similar to the <ul> HTML element.

[D]

Figure 9.10. Unordered list

ordered

The list is presented as a numbered series of items, similar to the <ol> HTML element.

[D]

Figure 9.11. Ordered list

definitions

The list is presented as a series of data definitions. Part of the data model, specified as the term, is listed prominently. The other associated data is listed after each term.

[D]

Figure 9.12. Data definition list

The term is marked using the term facet. The facet is required for all definition lists. Use of the facet is shown in Example 9.11, “Data definition list”.

Example 9.11. Data definition list


<h:form>

    <rich:list var="car" value="#{dataTableScrollerBean.allCars}" type="definitions" rows="5" title="Cars">

        <f:facet name="term">

            <h:outputText value="#{car.make} #{car.model}"></h:outputText>

        </f:facet>

        <h:outputText value="Price:" styleClass="label"></h:outputText>

        <h:outputText value="#{car.price}" /><br/>

        <h:outputText value="Mileage:" styleClass="label"></h:outputText>

        <h:outputText value="#{car.mileage}" /><br/>

    </rich:list>

</h:form>

9.8.3. Bullet and numeration appearance

The appearance of bullet points for unordered lists or numeration for ordered lists can be customized through CSS, using the list-style-type property.

9.8.4. Customizing the list

The first attribute specifies which item in the data model to start from, and the rows attribute specifies the number of items to list. The title attribute is used for a floating tool-tip. Example 9.12, “<rich:list> example” shows a simple example using the <rich:list> component.

Example 9.12. <rich:list> example


<h:form>

    <rich:list var="car" value="#{dataTableScrollerBean.allCars}" rows="5" type="unordered" title="Car Store">

        <h:outputText value="#{car.make} #{car.model}"/><br/>

        <h:outputText value="Price:" styleClass="label"></h:outputText>

        <h:outputText value="#{car.price} "/><br/>

        <h:outputText value="Mileage:" styleClass="label"></h:outputText>

        <h:outputText value="#{car.mileage} "/><br/>

    </rich:list>

</h:form>

[D]
Figure 9.13. <rich:list> example

9.8.5. Reference data

component-type: org.richfaces.List
component-class: org.richfaces.component.html.HtmlList
component-family: org.richfaces.List
renderer-type: org.richfaces.ListRenderer
tag-class: org.richfaces.taglib.ListTag

9.8.6. Style classes and skin parameters

Table 9.5. Style classes (selectors) and corresponding skin parameters

Class (selector)	Skin Parameters	Mapped CSS properties
`.rf-ulst-itm` This class defines styles for an item in an unordered list.	`generalTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
`.rf-olst-itm` This class defines styles for an item in an unordered list.	`generalTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
`.rf-dlst-trm` This class defines styles for the term of an item in a definition list.	`generalTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
`.rf-dlst-dfn` This class defines styles for the definition of an item in a definition list.	`generalTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size

9.9. `<rich:dataScroller>`

The <rich:dataScroller> component is used for navigating through multiple pages of tables or grids.

[D]

Figure 9.14. The <rich:dataScroller> component

9.9.1. Basic usage

The <rich:dataScroller> must be placed in the footer facet of the table or grid it needs to control. Alternatively, use the for attribute to bind the parent table or grid to the scroller.

The bound table or grid should also have the rows attribute defined to limit the number of rows per page.

The <rich:dataScroller> component must be re-rendered whenever a filter changes on the bound table, so that the scroller matches the current model for the table.

Example 9.13. Basic usage


<rich:dataTable id="table" value="#{capitalsBean.capitals}" var="cap" rows="5">

   <!-- table content -->

   ...

</rich:dataTable>

<rich:datascroller for="table" maxPages="5">

   <f:facet name="first">

      <h:outputText value="First" />

   </f:facet>

   <f:facet name="last">

      <h:outputText value="Last" />

   </f:facet>

</rich:datascroller>

9.9.2. Appearance and interactivity

The page attribute is a value-binding attribute used to define and save the current page number.

The <rich:dataScroller> component provides a range of controllers for scrolling through tables and grids:

Controls for scrolling by a specific amount

The component includes controls for switching to the first page, the last page, the next page, and the previous page, as well as controls for fast-forwarding or rewinding by a set amount. Use the fastStep attribute to set the number of pages to skip when fast-forwarding or rewinding.

The appearance of these controls can be customized using the following facets: first, last, next, previous, fastForward, and fastRewind. Additionally, there are facets for the controls' disabled states: first_disabled, last_disabled, next_disabled, previous_disabled, fastforward_disabled, and rewind_disabled.

Page controls

The component also features a series of numbered controls to jump to a specific page. Use the maxPages attribute to limit the number of page controls that appear. The current page control is highlighted.

The pageIndexVar and pagesVar attributes are request-scope variables for the current page and the total number of pages. Use these attributes with the pages facet to provide information about the pages of the table, as shown in Example 9.14, “pages facet”.

Example 9.14. pages facet


<rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5">

   <!-- table content -->

   ...

   <f:facet name="footer">

      <rich:datascroller pageIndexVar="pageIndex" pagesVar="pages">

         <f:facet name="pages">

            <h:outputText value="#{pageIndex} / #{pages}" />

         </f:facet>

      </rich:datascroller>

   </f:facet>

</rich:dataTable>

To add optional separators between controls, define the separators with the controlsSeparator facet.

9.9.3. JavaScript API

The <rich:dataScroller> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:

switchToPage(pageIndex): Switch to the page specified with the pageIndex parameter.
next(): Switch to the next page.
previous(): Switch to the previous page.
first(): Switch to the first page.
last(): Switch to the last page.
fastForward(): Step forward through the pages by the fastStep amount.
fastRewind(): Step backward through the pages by the fastStep amount.

9.9.4. Reference data

component-type: org.richfaces.DataScroller
component-class: org.richfaces.component.html.HtmlDataScroller
component-family: org.richfaces.DataScroller
renderer-type: org.richfaces.DataScrollerRenderer
tag-class: org.richfaces.taglib.DataScrollerTag

9.9.5. Style classes and skin parameters

Table 9.6. Style classes (selectors) and corresponding skin parameters

Class (selector)	Skin Parameters	Mapped CSS properties
`.rf-ds` This class defines styles for the data scroller.	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
	`tableBackgroundColor`	background
`.rf-ds-btn` This class defines styles for buttons in the data scroller.	`generalTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
	`tableBorderColor`	border-color
	`headerBackgroundColor`	background-color
`.rf-ds-btn-first` This class defines styles for the first button.	No skin parameters.
`.rf-ds-btn-fastrwd` This class defines styles for the fast rewind button.	No skin parameters.
`.rf-ds-btn-prev` This class defines styles for the previous button.	No skin parameters.
`.rf-ds-btn-next` This class defines styles for the next button.	No skin parameters.
`.rf-ds-btn-fastfwd` This class defines styles for the fast forward button.	No skin parameters.
`.rf-ds-btn-last` This class defines styles for the last button.	No skin parameters.
`.rf-ds-nmb-btn` This class defines styles for page number buttons in the data scroller.	`generalTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
	`tableBorderColor`	border-color
	`tableBackgroundColor`	background-color
`.rf-ds-press` This class defines styles for a data scroller when a control is pressed.	`tableBorderColor`	border-color
`tableBackgroundColor`	background
`.rf-ds-act` This class defines styles for an active data scroller.	`tableBorderColor`	color
`.rf-ds-dis` This class defines styles for a disabled data scroller.	`tableBorderColor`	color

9.10. Table filtering

Documentation in development

This section is currently under development. Any features it describes may not be available in the current release of RichFaces.

Tables entries can be filtered by the user through either the basic method built in to the <rich:column> component, or by defining external filters. Refer to Section 9.3, “<rich:column>” for details on using the <rich:column> component in tables.

9.10.1. Basic filtering

The built-in filtering abilities of the <rich:column> component allow the user to enter text as a filtering value. The table displays only those entries that begin with the filter value.

Set the filterValue attribute to point to the value used to filter the column. This can be either an initial filtering value on the page, or a value binding on the server. The filterValue value is then used with the JavaScript startsWith() method to filter the column entries based on the data specified with the filterBy attribute. Expressions in the filterBy attribute must refer to the variable declared in the table's var attribute, which is used to fill the contents of the table.

The filter is processed and the table is rendered when the onblur event occurs for the column. This can be changed by defining a different event with the filterEvent attribute. For example, to implement live updating such that the filter refreshes after every keystroke, set filterEvent="keyup".

Example 9.15. Basic filtering


<rich:dataTable value="#{capitalsBean.capitals}" var="cap">

   <f:facet name="header">

      <rich:column>

         <h:outputText value="State Name">

      </rich:column>

      <rich:column>

         <h:outputText value="State Capital">

      </rich:column>

   </f:facet>

   <rich:column filterValue="#{capitalsBean.currentStateFilterValue}"

                filterBy="#{cap.state}" filterEvent="keyup">

      <h:outputText value="#{cap.state}"/>

   </rich:column> 

   <rich:column filterValue="#{capitalsBean.currentNameFilterValue}"

                filterBy="#{cap.name}" filterEvent="keyup">

      <h:outputText value="#{cap.name}"/> 

   </rich:column>

</rich:dataTable>

The example uses the basic filtering method on both columns in the table.

[D]

9.10.2. External filtering

If you require more advanced filtering using custom functions or expressions, use the external filtering properties of the <rich:column> component.

Use the filterExpression attribute to define an expression that can be evaluated as a boolean value. The expression checks if each table entry satisfies the filtering condition when the table is rendered.

Use the filterMethod attribute to define a method binding. The method needs to accept an object as a parameter and return a boolean value. Similar to the filterExpression attribute, the table is rendered only with those entries that satisfy the filtering condition. By defining a custom filtering method, you can implement complex business logic to filter a table.

Example 9.16. External filtering


<rich:dataTable value="#{capitalsBean.capitals}" var="cap" id="table">

   <f:facet name="header">

      <rich:column>

         <h:outputText value="State Name">

      </rich:column>

      <rich:column>

         <h:outputText value="State Time Zone">

      </rich:column>

   </f:facet>

   <rich:column filterMethod="#{filteringBean.filterStates}">

        <f:facet name="header">

            <h:inputText value="#{filteringBean.filterValue}" id="input">

                <a4j:ajax event="keyup" render="table"

                              ignoreDupResponses="true" requestDelay="700"/>

            </h:inputText>

        </f:facet>

      <h:outputText value="#{cap.state}"/>

   </rich:column> 

   <rich:column filterExpression=

      "#{fn:containsIgnoreCase(cap.timeZone, filteringBean.filterZone)}">

        <f:facet name="header">

            <h:selectOneMenu value="#{filteringBean.filterZone}">

                <f:selectItems value="#{filteringBean.filterZones}" />

                <a4j:ajax event="change" render="table" />

            </h:selectOneMenu>

        </f:facet>

      <h:outputText value="#{cap.timeZone}"/> 

   </rich:column>

</rich:dataTable>

The example uses a filter expression on the first column and a filter method on the second column.

[D]

9.11. Table sorting

Documentation in development

This section is currently under development. Any features it describes may not be available in the current release of RichFaces.

Tables entries can be sorted by defining external sorting algorithms. Refer to Section 9.3, “<rich:column>” for details on using the <rich:column> component in tables.

Sorting non-English tables

To sort a table whose contents are not in English, add the org.richfaces.datatableUsesViewLocale context parameter to the project's web.xml settings file. Set the value of the context parameter to true.

9.11.1. External sorting

Bind the sortOrder attribute to bean properties to manage the sorting order externally. The bean must handle all the sorting algorithms. Example 9.17, “External sorting” demonstrates table sorting using an external control.

Example 9.17. External sorting


<rich:dataTable value="#{dataTableScrollerBean.allCars}"

                var="category" rows="20" id="table" reRender="ds2"

                sortPriority="#{sortingBean.prioritList}">

   <rich:column id="make" sortBy="#{category.make}"

                sortOrder="#{sortingBean.makeDirection}">

      <f:facet name="header">

         <h:outputText styleClass="headerText" value="Make" />

      </f:facet>

      <h:outputText value="#{category.make}" />

   </rich:column>

   <rich:column id="model" sortBy="#{category.model}"

                sortOrder="#{sortingBean.modelDirection}">

      <f:facet name="header">

         <h:outputText styleClass="headerText" value="Model" />

      </f:facet>

      <h:outputText value="#{category.model}" />

   </rich:column>

   <rich:column id="price" sortBy="#{category.price}"

                sortOrder="#{sortingBean.priceDirection}">

      <f:facet name="header">

         <h:outputText styleClass="headerText" value="Price" />

      </f:facet>

      <h:outputText value="#{category.price}" />

   </rich:column>

   <rich:column id="mileage" sortBy="#{category.mileage}"

                sortOrder="#{sortingBean.mileageDirection}">

      <f:facet name="header">

         <h:outputText styleClass="headerText" value="Mileage" />

      </f:facet>

      <h:outputText value="#{category.mileage}" />

   </rich:column>

</rich:dataTable>

The example uses an external control to manage the table's sorting.

[D]

When using the sortMode="multiple" configuration, set the priority by which columns are sorted with the sortPriorities attribute.

Use the sortExpression attribute to define a bean property to use for sorting the column. The expression checks each table entry against the sorting expression during rendering.