rich:scrollableDataTable

Component identification parameters

Name | Value
--- | ---
component-type | org.richfaces.component.ScrollableDataTable
component-class | org.richfaces.component.html.HtmlScrollableDataTable
component-family | org.richfaces.component.ScrollableDataTable
renderer-type | org.richfaces.renderkit.html.ScrollableDataTableRenderer
tag-class | org.richfaces.taglib.ScrollableDataTableTag

## Creating the Component with a Page Tag

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

Example:

    ...
        <rich:scrollableDataTable value="#{dataTableScrollerBean.allCars}" var="category">
            <!--...//Set of columns and header/footer facets-->
        </rich:scrollableDataTable>
    ...

## Creating the Component Dynamically Using Java

Example:

    import org.richfaces.component.html.HtmlScrollableDataTable;
    ...
    HtmlScrollableDataTable myScrollableDataTable = new HtmlScrollableDataTable();
    ...

## Details of Usage

The component represents on a page as a scrollable table with some fixed (non-scrollable) rows ( with header and footer) and columns. Like other tables <rich:scrollableDataTable> also has optional footer and header that could be implemented using the corresponding facets. Columns of the table are optionally resizable. Resizing is available using "drag and drop" of the column vertical borders. There is possibility to expand or collapse the columns through JS API on the client side. You can define the number of the fixed columns from the left side using attribute "frozenColCount" that is not scrolled via horizontal scroll.

There is possibility to increase component performance using attribute "hideWhenScrolling" . If attribute value is "true" data is hidden during scrolling.

It's possible to select the whole row with onclick on the row or some set of rows. Selection is optional and availability of such feature is defined on the component. There are two ways to select a few rows:

- Just clicking the columns one by one.

- Clicking some row with the SHIFT button hold. In this case all the rows starting from last selected up to clicked should be selected.

The columns provides the possibility of expanding/collapsing on the client side through the next JS API:

- `collapse(columnId)` - Performs the collapse action for the column with the corresponding id

It's possible to sort the table content after clicks on the header. The feature is optional. Every column should be pointed to the comparator method that is used for sorting the table. In case the <rich:scrollableDataTable> is already sorted by some column and the header of this column has been clicked again - the sorting is reversed.

After sorting selection that was made before is reset

The typical variant of using:

    ...
    <rich:scrollableDataTable value="#{modelBuilder.model}" var="issues"
    			frozenColCount="1"
    			first="0"
    			rows="40"
    			width="300px"
    			height="396px">
    	<rich:column width="100px">
    		<f:facet name="header" >
    			<h:outputText value="State"/>
    		</f:facet>
    		<h:outputText value="#{issues.cell1}"/>
    		<f:facet name="footer">
    			<h:outputText value="State"/>
    		</f:facet>
    	</rich:column>
    	<!--...//Set of columns and header/footer facets-->
    </rich:scrollableDataTable>
    ...

The "selection" attribute allows to get the row data when using one and multi-selection rows mode.

This attribute is a reference to object to the instance of `org.richfaces.model.selection.Selection`. interface interface, containing current collection of objects selected by you.

In the following example when you submit the form, current collection of the selected objects is placed in the object's property. Then on complete action the <rich:modalPanel> with selected data is shown.

Example:

    ...
    		<h:form>
    			<rich:spacer height="30" />
    			<rich:scrollableDataTable rowKeyVar="rkv" frozenColCount="1" height="200px"
    				width="300px" id="carList" rows="40" columnClasses="col"
    				value="#{dataTableScrollerBean.allCars}" var="category" sortMode="single"
    				selection="#{dataTableScrollerBean.selection}">
    				<rich:column id="make">
    					<f:facet name="header"><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="20px"/>
    			<a4j:commandButton value="Show Current Selection" reRender="table"
    				action="#{dataTableScrollerBean.takeSelection}"
    				oncomplete="javascript:Richfaces.showModalPanel('panel');"/>
    		</h:form>
    		<rich:modalPanel id="panel" autosized="true">
    				<f:facet name="header">
    					<h:outputText value="Selected Rows"/>
    				</f:facet>
    				<f:facet name="controls">
    					<span style="cursor:pointer" onclick="javascript:Richfaces.hideModalPanel('panel')">X</span>
    				</f:facet>
    			<rich:dataTable value="#{dataTableScrollerBean.selectedCars}" var="sel" id="table">
    				<rich:column>
    					<f:facet name="header"><h:outputText value="Make" /></f:facet>
    					<h:outputText value="#{sel.make}" />
    				</rich:column>
    				<rich:column id="model">
    					<f:facet name="header"><h:outputText value="Model" /></f:facet>
    					<h:outputText value="#{sel.model}" />
    				</rich:column>
    				<rich:column id="price">
    					<f:facet name="header"><h:outputText value="Price" /></f:facet>
    					<h:outputText value="#{sel.price}" />
    				</rich:column>
    				</rich:dataTable>
    		</rich:modalPanel>
    ...

This is a result:

The "selection" attribute usage

On RichFaces LiveDemo page you can find fuller example of use of this attribute with example bean.

The <rich:scrollableDataTable> component has the following extra attributes for event processing on the client:

- "onselectionchange"

- "onRowClick"

- "onRowDblClick"

- "onRowMouseUp"

- "onRowMouseDown"

Information about sorting and filtering you can find in RichFaces Developer guide section aboutsorting.

Information about the "process" attribute usage you can find in the "Decide what to process" guide section.

Note:

If you want to use specific features such as pagination on database level you should pass to the "value" of the <rich:scrollableDataTable> component an object which class extends `org.richfaces.model.ScrollableTableDataModel`.

## JavaScript API

JavaScript API

Function | Description
--- | ---
collapse(columnId) | Performs a collapse action for column with corresponding Id

## Facets

Facets

Facet | Description
--- | ---
header | Defines the header content
footer | Defines the footer content

## 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:scrollableDataTable> components at once:

- Redefine the corresponding skin parameters

- Add to your style sheets style classes used by a <rich:scrollableDataTable> component

## Skin Parameters Redefinition

Skin parameters for all table

Skin parameters | CSS properties
--- | ---
tableBackgroundColor | background-color
tableBorderColor | border-color
tableBorderWidth | border-width

Skin parameters for header rows and cells

Skin parameters | CSS properties
--- | ---
headerBackgroundColor | background-color
headerTextColor | color
generalFamilyFont | font-family
generalSizeFont | font-size
tableBorderWidth | border-bottom-width
tableBorderColor | border-bottom-color
tableBorderWidth | border-right-width
tableBorderColor | border-right-color

Skin parameters for footer rows and cells

Skin parameters | CSS properties
--- | ---
tableSubfooterBackgroundColor | background-color
generalFamilyFont | font-family
generalSizeFont | font-size
tableBorderColor | border-right-color
generalFamilyFont | font-family
generalSizeFont | font-size

Skin parameters for column cells

Skin parameters | CSS properties
--- | ---
tableBorderColor | border-right-color
tableBorderColor | border-bottom-color

Skin parameters for active rows

Skin parameters | CSS properties
--- | ---
tabDisabledTextColor | color

Skin parameters for selected rows

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

## Definition of Custom Style Classes

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

Classes names

Classes names that define a component appearance

Class name | Description
--- | ---
rich-sdt | Defines styles for a component appearance

Classes names that define footer and header elements

Class name | Description
--- | ---
rich-sdt-header-cell | Defines styles for header cells
rich-sdt-header-row | Defines styles for a header raw
rich-sdt-column-cell | Defines styles for column cells
rich-sdt-footer-cell | Defines styles for footer cells
rich-sdt-footer-row | Defines styles for a footer raw
rich-sdt-hsep | Defines styles for header separators

Classes names that define different states

Class name | Description
--- | ---
rich-sdt-row-active | Defines styles for an active row
rich-sdt-row-selected | Defines styles for a selected row
rich-sdt-column-sort-up | Defines styles for ascending sorted column
rich-sdt-column-sort-down | Defines styles for descending sorted column

In order to redefine styles for all <rich:scrollableDataTable> 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-sdt-header-cell{
        font-style:italic;
    }
    ...

This is a result:

Redefinition styles with predefined classes

In the example the font style for header cell was changed.

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

Example:

    ...
    .myClass{
        background-color:#ffead9;
    }
    ...

The "selectedClass" attribute for <rich:scrollableDataTable> is defined as it's shown in the example below:

Example:

    <rich:scrollableDataTable ... selectedClass="myClass"/>

This is a result:

Redefinition styles with own classes and styleClass attributes

As it could be seen on the picture above, background color for selected item was changed.

## Relevant Resources Links

On the component LiveDemo page you can see the example of <rich:scrollableDataTable> usage.

Cookbook article Scrollable dataTable Selection Usage provides a simple example of how you can use the "selection" attribute in order to get row selection in rich:scrollableDataTable.