table rich:dataTable HtmlDataTable

Component identification parameters

Name | Value
--- | ---
component-type | org.richfaces.DataTable
component-class | org.richfaces.component.html.HtmlDataTable
component-family | org.richfaces.DataTable
renderer-type | org.richfaces.DataTableRenderer
tag-class | org.richfaces.taglib.DataTableTag

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

## Creating the Component Dynamically from Java

Example:

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

## 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 rows 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:

Component usage

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

## Skin Parameters Redefinition

Skin parameters redefinition for a table

Skin parameters | CSS properties
--- | ---
tableBackgroundColor | background-color

Skin parameters redefinition for a header

Skin parameters | CSS properties
--- | ---
headerBackgroundColor | background-color

Skin parameters redefinition for a footer

Skin parameters | CSS properties
--- | ---
tableFooterBackgroundColor | background-color

Skin parameters redefinition for a column header

Skin parameters | CSS properties
--- | ---
additionalBackgroundColor | background-color

Skin parameters redefinition for a column footer

Skin parameters | CSS properties
--- | ---
tableSubfooterBackgroundColor | background-color

Skin parameters redefinition for cells

Skin parameters | CSS properties
--- | ---
generalSizeFont | font-size
generalTextColor | color
generalFamilyFont | font-family

## Definition of Custom Style Classes

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

DataTable class names

Classes names that define a whole component appearance

Class name | Description
--- | ---
rich-table | Defines styles for all table
rich-table-caption | Defines styles for a "caption" facet element

Classes names that define header and footer elements

Class name | Description
--- | ---
rich-table-header | Defines styles for a table header row
rich-table-header-continue | Defines styles for all header lines after the first
rich-table-subheader | Defines styles for a column header
rich-table-footer | Defines styles for a footer row
rich-table-footer-continue | Defines styles for all footer lines after the first
rich-table-subfooter | Defines styles for a column footer

Classes names that define rows and cells of a table

Class name | Description
--- | ---
rich-table-headercell | Defines styles for a header cell
rich-table-subheadercell | Defines styles for a column header cell
rich-table-cell | Defines styles for a table cell
rich-table-row | Defines styles for a table row
rich-table-firstrow | Defines styles for a table start row
rich-table-footercell | Defines styles for a footer cell
rich-table-subfootercell | Defines 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 and define necessary properties in them.

To change styles of particular <rich:dataTable> components, define your own style classes in the corresponding <rich:dataTable> attributes.

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