Create new RichFaces Documentation Jira issue

This will launch the RichFaces Jira page - to complete your feedback please login if needed, and submit the Jira.

JBoss.orgCommunity Documentation

6.6.14.  < rich:scrollableDataTable > available since 3.1.0

Table 6.120. rich : scrollableDataTable attributes

Attribute Name Description
activeClassAssigns one or more space-separated CSS class names to the component active row
activeRowKeyRequest scope attribute under which the activeRowKey will be accessible
ajaxKeysThis attribute defines row keys that are updated after an AJAX request
binding JSF: The 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
columnClasses JSF: Assigns one or more space-separated CSS class names to the columns of the table. If the CSS class names are comma-separated, each class will be assigned to a particular column in the order they follow in the attribute. If you have less class names than columns, the class will be applied to every n-fold column where n is the order in which the class is listed in the attribute. If there are more class names than columns, the overflow ones 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
footerClassAssigns one or more space-separated CSS class names to any footer generated for this component
frozenColCountDefines the number of the fixed columns from the left side that will not be scrolled via horizontal scroll. Default value is "0".
headerClassAssigns one or more space-separated CSS class names to any header generated for this component
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".
id JSF: Every 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
onRowClickThe client-side script method to be called when the row is clicked
onRowDblClickThe client-side script method to be called when the row is double-clicked
onRowMouseDownThe client-side script method to be called when a mouse button is pressed down over the row
onRowMouseUpThe client-side script method to be called when a mouse button is released over the row
onselectionchangeThe client side script method to be called when a selected row is changed
rendered JSF: If "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
rowClasses JSF: Assigns one or more space-separated CSS class names to the rows of the table. If the CSS class names are comma-separated, each class will be assigned to a particular row in the order they follow in the attribute. If you have less class names than rows, the class will be applied to every n-fold row where n is the order in which the class is listed in the attribute. If there are more class names than rows, the overflow ones are ignored.
rowKeyConverterConverter for a row key object
rowKeyVarThe attribute provides access to a row key in a Request scope
rowsHTML: A number of rows to display, or zero for all remaining rows in the table
scriptVarName of JavaScript variable corresponding to component
selectedClassAssigns one or more space-separated CSS class names to the component rows selected
selectionValue binding representing selected rows
selectionModeDefines selection behaviour, provides an enumeration of the possible selection modes. Default value is "multi"
similarityGroupingIdIf there are any component requests with identical IDs then these requests will be grouped.
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
styleHTML: CSS style rules to be applied to the component
styleClass JSF: Assigns one or more CSS class names to the component. Corresponds 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
value JSF: The current value for this component
varA request-scope attribute via which the data object for the current row will be used when iterating
widthHTML: Defines a width of the component. Default value is "700px".


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:

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

It's possible to sort the table content after clicks on the header. The feature is optional (to disable it, use attribute sortable on rich:column ). 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:


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"

From version 3.3.1 it becomes possible to switch selection mode with selectionMode attribute

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.

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





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:


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:


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

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.