6.37.  < rich:dataTable >

6.37.1. Description

The component for tables rendering that allows choosing data from a model and obtains built-in support of Ajax updates.

<rich:dataTable> component

Figure 6.63.  <rich:dataTable> component


6.37.2. Key Features

  • A completely skinned table and child elements

  • Possibility to insert the complex subcomponents "colGroup" and "subTable"

  • Possibility to update a limited set of strings with AJAX

  • Possibility to sort and to filter of columns

  • Sorting column values

  • Filtering column values

Table 6.134. rich : dataTable attributes

Attribute NameDescription
ajaxKeysThis attribute defines row keys that are updated after an AJAX request
alignleft|center|right [CI] Deprecated. This attribute specifies the position of the table with respect to the document. Permitted values: * left: The table is to the left of the document. * center: The table is to the center of the document. * right: The table is to the right of the document
bgcolorDeprecated. This attribute sets the background color for the document body or table cells. This attribute sets the background color of the canvas for the document body (the BODY element) or for tables (the TABLE, TR, TH, and TD elements). Additional attributes for specifying text color can be used with the BODY element. This attribute has been deprecated in favor of style sheets for specifying background color information
bindingThe attribute takes a value-binding expression for a component property of a backing bean
borderThis attributes specifies the width of the frame around a component
captionClassSpace-separated list of CSS style class(es) that are be applied to caption for this component
captionStyleCSS style(s) is/are to be applied to caption when this component is rendered
cellpaddingThis attribute specifies the amount of space between the border of the cell and its contents
cellspacingThis attribute specifies the amount of space between the border of the cell and its contents. The attribute also specifies the amount of space to leave between cells
columnClassesComma-delimited list of CSS style classes that are be applied to the columns of this table. A space separated list of classes may also be specified for any individual column. If the number of elements in this list is less than the number of columns specified in the "columns" attribute, no "class" attribute is output for each column greater than the number of elements in the list. If the number of elements in the list is greater than the number of columns specified in the "columns" attribute, the elements at the position in the list after the value of the "columns" attribute are ignored
columnsQuantity of columns
columnsWidthComma-separated list of width attribute for every column. Specifies a default width for each column in the table. In addition to the standard pixel, percentage, and relative values, this attribute allows the special form "0*" (zero asterisk) which means that the width of the each column in the group should be the minimum width necessary to hold the column's contents. This implies that a column's entire contents must be known before its width may be correctly computed. Authors should be aware that specifying "0*" will prevent visual user agents from rendering a table incrementally
componentStateIt defines EL-binding for a component state for saving or redefinition
dirDirection indication for text that does not inherit directionality. Valid values are "LTR" (left-to-right) and "RTL" (right-to-left)
firstA zero-relative row number of the first row to display
footerClassSpace-separated list of CSS style class(es) that are be applied to footer for this component
framevoid|above|below|hsides|lhs|rhs|vsides|box|border [CI] This attribute specifies which sides of the frame surrounding a table will be visible. Possible values: * void: No sides. This is the default value. * above: The top side only. * below: The bottom side only. * hsides: The top and bottom sides only. * vsides: The right and left sides only. * lhs: The left-hand side only. * rhs: The right-hand side only. * box: All four sides. * border: All four sides
headerClassSpace-separated list of CSS style class(es) that are be applied to header for this component
idEvery component may have a unique id that is automatically created if omitted
langCode describing the language used in the generated markup for this component
onclickHTML: a script expression; a pointer button is clicked
ondblclickHTML: a script expression; a pointer button is double-clicked
onkeydownHTML: a script expression; a key is pressed down
onkeypressHTML: a script expression; a key is pressed and released
onkeyupHTML: a script expression; a key is released
onmousedownHTML: script expression; a pointer button is pressed down
onmousemoveHTML: a script expression; a pointer is moved within
onmouseoutHTML: a script expression; a pointer is moved away
onmouseoverHTML: a script expression; a pointer is moved onto
onmouseupHTML: script expression; a pointer button is released
onRowClickHTML: a script expression; a pointer button is clicked on row
onRowDblClickHTML: a script expression; a pointer button is double-clicked on row
onRowMouseDownHTML: script expression; a pointer button is pressed down on row
onRowMouseMoveHTML: a script expression; a pointer is moved within of row
onRowMouseOutHTML: a script expression; a pointer is moved away of row
onRowMouseOverHTML: a script expression; a pointer is moved onto of row
onRowMouseUpHTML: script expression; a pointer button is released on row
renderedIf "false", this component is not rendered
rowClassesA comma-delimited list of CSS style classes that is applied to popup table rows. A space separated list of classes may also be specified for any individual row. The styles are applied, in turn, to each row in the table. For example, if the list has two elements, the first style class in the list is applied to the first row, the second to the second row, the first to the third row, the second to the fourth row, etc. In other words, we keep iterating through the list until we reach the end, and then we start at the beginning again
rowKeyConverterConverter for a row key object
rowKeyVarThe attribute provides access to a row key in a Request scope
rowsA number of rows to display, or zero for all remaining rows in the table
rulesThis attribute specifies which rules will appear between cells within a table. The rendering of rules is user agent dependent. Possible values: * none: No rules. This is the default value. * groups: Rules will appear between row groups (see THEAD, TFOOT, and TBODY) and column groups (see COLGROUP and COL) only. * rows: Rules will appear between rows only. * cols: Rules will appear between columns only. * all: Rules will appear between all rows and columns
sortModeDefines mode of sorting. Possible values are 'single' for sorting of one column and 'multi' for some.
sortPriorityDefines a set of columns ids in the sorting order
stateVarThe attribute provides access to a component state on the client side
styleCSS style(s) is/are to be applied when this component is rendered
styleClassCorresponds to the HTML class attribute
titleAdvisory title information about markup elements generated for this component
valueThe current value for this component
varA request-scope attribute via which the data object for the current row will be used when iterating
widthThis attribute specifies the desired width of the entire table and is intended for visual user agents. When the value is percentage value, the value is relative to the user agent's available horizontal space. In the absence of any width specification, table width is determined by the user agent

Table 6.135. Component identification parameters

NameValue
component-typeorg.richfaces.DataTable
component-classorg.richfaces.component.html.HtmlDataTable
component-familyorg.richfaces.DataTable
renderer-typeorg.richfaces.DataTableRenderer
tag-classorg.richfaces.taglib.DataTableTag

6.37.3. Creating the Component with a Page Tag

Here is a simple example as it could be used on a page:

Example:


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

6.37.4. Creating the Component Dynamically from Java

Example:


import org.richfaces.component.html.HtmlDataTable;
...
HtmlDataTable myTable = new HtmlDataTable();
...

6.37.5. Details of Usage

The <rich:dataTable> component is similar to the <h:dataTable> one, except Ajax support and skinnability. Ajax support is possible, because the component was created basing on the <a4j:repeat> component and as a result it could be partially updated with Ajax. "ajaxKeys" attribute allows to define row keys that is updated after an Ajax request.

Here is an example:

Example:


...
    <rich:dataTable value="#{capitalsBean.capitals}" var="capitals" 
                ajaxKeys="#{bean.ajaxSet}" binding="#{bean.table}" id="table">
        ...
    </rich:dataTable>
...
    <a4j:commandButton action="#{tableBean.action}" reRender="table" value="Submit"/>
...

In the example "reRender" attribute contains value of "id" attribute for <rich:dataTable> component. As a result the component is updated after an Ajax request.

The component allows to use "header" , "footer" and "caption" facets for output. See an example below:

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>
...

This is a result:

<rich:dataTable> component with facets

Figure 6.64.  <rich:dataTable> component with facets


Information about sorting and filtering you can find here.

6.37.6. Look-and-Feel Customization

For skinnability implementation, the components use a style class redefinition method. Default style classes are mapped on skin parameters.

There are two ways to redefine the appearance of all <rich:dataTable> components at once:

  • Redefine the corresponding skin parameters

  • Add to your style sheets style classes used by a <rich:dataTable> component

6.37.7. Skin Parameters Redefinition

Table 6.136. Skin parameters redefinition for a table

Skin parametersCSS properties
tableBackgroundColorbackground-color

Table 6.137. Skin parameters redefinition for a header

Skin parametersCSS properties
headerBackgroundColorbackground-color

Table 6.138. Skin parameters redefinition for a footer

Skin parametersCSS properties
tableFooterBackgroundColorbackground-color

Table 6.139. Skin parameters redefinition for a column header

Skin parametersCSS properties
additionalBackgroundColorbackground-color

Table 6.140. Skin parameters redefinition for a column footer

Skin parametersCSS properties
tableSubfooterBackgroundColorbackground-color

Table 6.141. Skin parameters redefinition for cells

Skin parametersCSS properties
generalSizeFontfont-size
generalTextColorcolor
generalFamilyFontfont-family

6.37.8. Definition of Custom Style Classes

On the screenshot there are classes names that define styles for component elements.

<rich:dataTable> class names

Figure 6.65.  <rich:dataTable> class names


Table 6.142. Classes names that define a whole component appearance

Class nameDescription
rich-tableDefines styles for all table
rich-table-captionDefines styles for a "caption" facet element

Table 6.143. Classes names that define header and footer elements

Class nameDescription
rich-table-headerDefines styles for a table header row
rich-table-header-continueDefines styles for all header lines after the first
rich-table-subheaderDefines styles for a column header
rich-table-footerDefines styles for a footer row
rich-table-footer-continueDefines styles for all footer lines after the first
rich-table-subfooterDefines styles for a column footer

Table 6.144. Classes names that define rows and cells of a table

Class nameDescription
rich-table-headercellDefines styles for a header cell
rich-table-subheadercellDefines styles for a column header cell
rich-table-cellDefines styles for a table cell
rich-table-rowDefines styles for a table row
rich-table-firstrowDefines styles for a table start row
rich-table-footercellDefines styles for a footer cell
rich-table-subfootercellDefines styles for a column footer cell

In order to redefine styles for all <rich:dataTable> components on a page using CSS, it's enough to create classes with the same names (possible classes could be found in the tables above) and define necessary properties in them.

Example:


...
.rich-table-cell{
    
font-weight:bold;
}
...

This is a result:

Redefinition styles with predefined classes

Figure 6.66. Redefinition styles with predefined classes


In the example the font weight for table cell was changed.

Also it’s possible to change styles of particular <rich:dataTable> component. In this case you should create own style classes and use them in corresponding <rich:dataTable> styleClass attributes. An example is placed below:

Example:


...
.myClass{
    
font-style:italic;
}
...

The "headerClass" attribute for <rich:dataTable> is defined as it’s shown in the example below:

Example:


<rich:dataTable  ... headerClass="myClass"/>

This is a result:

Redefinition styles with own classes and styleClass attributes

Figure 6.67. Redefinition styles with own classes and styleClass attributes


As it could be seen on the picture above, the font style for header was changed.

6.37.9. Relevant Resources Links

Here you can see the example of <rich:dataTable> usage and sources for the given example.

The article about <rich:dataTable> flexibility can be found here.

More information about using <rich:dataTable> and <rich:subTable> could be found on the RichFaces Users Forum.

How to use <rich:dataTable> and <rich:datascroller> in a context of Extended Data Model see here.