6.73.  < rich:scrollableDataTable >

6.73.1. Description

The <rich:scrollableDataTable> component is used for the table-like component creation. The component just adds the set of additional features described below in comparison with the standard table.

<rich:scrollableDataTable> component

Figure 6.201.  <rich:scrollableDataTable> component


6.73.2. Key Features

  • Highly customizable look and feel

  • Variable content of the table cells

  • Dynamically fetching the rows from the server when the table is scrolled up and down

  • Resizing columns by mouse dragging the column bar

  • Sorting column by clicking the header

  • Fixed one or more left columns when table is scrolled horizontally

  • One and multi-selection rows mode

  • Built-it drag-n-drop support

  • Sorting column values

Table 6.401. rich : scrollableDataTable attributes

Attribute NameDescription
activeClassA CSS class to be applied to an active row
activeRowKeyRequest scope attribute under which the activeRowKey will be accessible
ajaxKeysThis attribute defines row keys that are updated after an AJAX request
bindingThe attribute takes a value-binding expression for a component property of a backing bean
bypassUpdatesIf "true", after process validations phase it skips updates of model beans on a force render response. It can be used for validating components input
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
componentStateIt defines EL-binding for a component state for saving or redefinition
dataSerialized (on default with JSON) data passed on the client by a developer on AJAX request. It's accessible via "data.foo" syntax
eventsQueueName of requests queue to avoid send next request before complete other from same event. Can be used to reduce number of requests of frequently events (key press, mouse move etc.)
firstA zero-relative row number of the first row to display
footerClassSpace-separated list of CSS style class(es) that are be applied to any footer generated for this table
frozenColCountDefines the number of the fixed columns from the left side that will not be scrolled via horizontal scroll. Default value is '0'
headerClassSpace-separated list of CSS style class(es) that are be applied to any header generated for this table
heightDefines a height of the component. Default value is 500px
hideWhenScrollingIf 'true' data will be hidden during scrolling. Can be used for increase performance. Default value is 'false'
idEvery component may have a unique id that is automatically created if omitted
ignoreDupResponsesAttribute allows to ignore an Ajax Response produced by a request if the newest 'similar' request is in a queue already. ignoreDupResponses="true" does not cancel the request while it is processed on the server, but just allows to avoid unnecessary updates on the client side if the response isn't actual now
onbeforedomupdateJavaScript code for call before DOM has been updated on client side
oncompleteJavaScript code for call after request completed on client side
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
onRowMouseUpHTML: script expression; a pointer button is released on row
onselectionchangeHTML: script expression to invoke on changing of rows selection
processId['s] (in format of call UIComponent.findComponent()) of components, processed at the phases 2-5 in case of AjaxRequest caused by this component. Can be single id, comma-separated list of Id's, or EL Expression with array or Collection
renderedIf "false", this component is not rendered
requestDelayAttribute defines the time (in ms.) that the request will be wait in the queue before it is ready to send. When the delay time is over, the request will be sent to the server or removed if the newest 'similar' request is in a queue already
reRenderId['s] (in format of call UIComponent.findComponent()) of components, rendered in case of AjaxRequest caused by this component. Can be single id, comma-separated list of Id's, or EL Expression with array or Collection
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
scriptVarName of JavaScript variable corresponding to component
selectedClassName of the CSS class for a selected row
selectionValue binding representing selected rows
sortModeDefines mode of sorting. Possible values are 'single' for sorting of one column and 'multi' for some.
sortOrderValueBinding pointing at a property of a class to manage rows sorting
stateVarThe attribute provides access to a component state on the client side
statusID (in format of call UIComponent.findComponent()) of Request status component
styleCSS style(s) is/are to be applied when this component is rendered
styleClassCorresponds to the HTML class attribute
timeoutResponse waiting time on a particular request. If a response is not received during this time, the request is aborted
valueThe current value for this component
varA request-scope attribute via which the data object for the current row will be used when iterating
widthDefines a width of the component. Default value is 700px

Table 6.402. Component identification parameters

NameValue
component-typeorg.richfaces.component.ScrollableDataTable
component-classorg.richfaces.component.html.HtmlScrollableDataTable
component-familyorg.richfaces.component.ScrollableDataTable
renderer-typeorg.richfaces.renderkit.html.ScrollableDataTableRenderer
tag-classorg.richfaces.taglib.ScrollableDataTableTag

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

6.73.4. Creating the Component Dynamically Using Java

Example:


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

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

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 instace of org.richfaces.model.selection.Selection interface, containing current collection of objects selected by you.

In the following example when you submits the form current collection of objects selected by you 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

Figure 6.202. The "selection" attribute usage


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

  • onselectionchange

  • oncomplete

  • onRowClick

  • onRowDblClick

  • onRowMouseUp

  • onRowMouseDown

Information about sorting and filtering you can find here.

Information about the "process" attribute usage you can find here.

6.73.6. JavaScript API

Table 6.403. JavaScript API

FunctionDescription
collapse(columnId)Performs a collapse action for column with corresponding Id

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

6.73.8. Skin Parameters Redefinition

Table 6.404. Skin parameters for all table

Skin parametersCSS properties
tableBackgroundColorbackground-color
tableBorderColorborder-color
tableBorderWidthborder-width

Table 6.405. Skin parameters for header rows and cells

Skin parametersCSS properties
headerBackgroundColorbackground-color
headerTextColorcolor
generalFamilyFontfont-family
generalSizeFontfont-size
tableBorderWidthborder-bottom-width
tableBorderColorborder-bottom-color
tableBorderWidthborder-right-width
tableBorderColorborder-right-color

Table 6.406. Skin parameters for footer rows and cells

Skin parametersCSS properties
tableSubfooterBackgroundColorbackground-color
generalFamilyFontfont-family
generalSizeFontfont-size
tableBorderColorborder-right-color
generalFamilyFontfont-family
generalSizeFontfont-size

Table 6.407. Skin parameters for column cells

Skin parametersCSS properties
tableBorderColorborder-right-color
tableBorderColorborder-bottom-color

Table 6.408. Skin parameters for active rows

Skin parametersCSS properties
tabDisabledTextColorcolor

Table 6.409. Skin parameters for selected rows

Skin parametersCSS properties
additionalBackgroundColorbackground-color

6.73.9. Definition of Custom Style Classes

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

Classes names

Figure 6.203. Classes names


Table 6.410. Classes names that define a component appearance

Class nameDescription
rich-sdtDefines styles for a component appearance

Table 6.411. Classes names that define footer and header elements

Class nameDescription
rich-sdt-header-cellDefines styles for header cells
rich-sdt-header-rowDefines styles for a header raw
rich-sdt-column-cellDefines styles for column cells
rich-sdt-footer-cellDefines styles for footer cells
rich-sdt-footer-rowDefines styles for a footer raw
rich-sdt-hsepDefines styles for header separators

Table 6.412. Classes names that define different states

Class nameDescription
rich-sdt-row-activeDefines styles for an active row
rich-sdt-row-selectedDefines styles for a selected row
rich-sdt-column-sort-upDefines styles for ascending sorted column
rich-sdt-column-sort-downDefines 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

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

Figure 6.205. Redefinition styles with own classes and styleClass attributes


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

6.73.10. Relevant Resources Links

Here you can see the example of <rich:scrollableDataTable> usage.