6.6.9.

< rich:datascroller >

6.6.9.1.
6.6.9.2.
6.6.9.3.
6.6.9.4.
6.6.9.5.

available since 3.0.0

Description
Key Features
Details of Usage
Reference Data
Relevant Resources Links

6.6.9.1. Description
The component designed for providing the functionality of tables scrolling using Ajax
requests.

Figure 6.34. <rich:datascroller> component

6.6.9.2. Key Features

o
o
o
o

Provides table scrolling functionality

Built-in Ajax processing
Provides fast controls
Skin support

6.6.9.3. Details of Usage

The <rich:datascroller> component provides table scrolling functionalitity the same as
TOMAHAWK scroller but with Ajax requests usage.
The <rich:datascroller> component
should
be
reRendered
also
with <rich:dataTable> when you changing filter in order to be updated according to
the<rich:dataTable> current model.
The component should be placed into the footer of the parent table or be bound to it with
the "for" attribute. Note, that "for" is evaluated on view build, not on view render, that is why
it will ignore JSTL tags.
The table should also have the defined "rows" attribute limiting the quantity of inputted table
rows.
The scroller could limit the maximum quantity of rendered links on the table pages with the
help of the "maxPages" attribute.
Component provides two controllers groups for switching:
o
o

Page numbers for switching onto a particular page

The
controls

of

fast

switching: "first", "last", "next", "previous", "fastforward", "fastrewind"

The controls of fast switching are created adding the facets component with the
corresponding name:

Example:

...
<rich:datascroller for="table" maxPages="10">
<f:facet name="first">
<h:outputText value="First"/>
</f:facet>
<f:facet name="last">
<h:outputText value="Last"/>
</f:facet>
</rich:datascroller>
...

Figure 6.35. <rich:datascroller> controls of fast switching

The screenshot shows one controller from each group.

There
are
also
facets
used
to
create
the
disabled
states: "first_disabled", "last_disabled", "next_disabled", "previous_d
isabled","fastforward_disabled", "fastrewind_disabled".
For

the "fastforward"/"fastrewind" controls

customization

the

additional "fastStep" attribute is used. The attribute indicates pages quantity to switch onto
when fast scrolling is used.
The "page" is a value-binding attribute used to define and save the current page number.
The example is placed below.
Example:

...
<h:form id="myForm">
<rich:dataTable id="carList" rows="7" value="#{dataTableScrollerBean.allCars}" var="category">
<f:facet name="header">

<rich:columnGroup>
<h:column>
<h:outputText value="Make" />
</h:column>
<h:column>
<h:outputText value="Model" />
</h:column>
<h:column>
<h:outputText value="Price" />
</h:column>
</rich:columnGroup>
</f:facet>
<h:column>
<h:outputText value="#{category.make}" />
</h:column>
<h:column>
<h:outputText value="#{category.model}" />
</h:column>
<h:column>
<h:outputText value="#{category.price}" />
</h:column>
</rich:dataTable>
<rich:datascroller id="sc2" for="carList" reRender="sc1" maxPages="7" page="#{dataTableScroll
erBean.scrollerPage}" />
<h:panelGrid>
<h:panelGroup>
<h:outputText value="Set current page number:" />
<h:inputText value="#{dataTableScrollerBean.scrollerPage}" id="sc1" size="1"/>
<h:commandButton value="Set" />
</h:panelGroup>
</h:panelGrid>

</h:form>
...

In the example above you can enter the page number you want and set it by clicking on
the <h:commandButton> . By the way, if you use<rich:datascroller> page links the
input field rerenders and current page number changes.
The result should be like below:

Figure 6.36. The "page" attribute usage

The "pageIndexVar" and "pagesVar" attributes define a request scope variables and provide
an ability to show the current page and the number of pages in the <rich:datascroller> .
These attributes are used for definition the names of variables, that is used in the facet with
name "pages" . An example can be found below:
Example:

...
<h:form>
<rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5">
<rich:column>
<h:outputText value="#{cap.name}" />
</rich:column>
<f:facet name="footer">
<rich:datascroller pageIndexVar="pageIndex" pagesVar="pages">
<f:facet name="pages">
<h:outputText value="#{pageIndex} / #{pages}" />
</f:facet>
</rich:datascroller>
</f:facet>
</rich:dataTable>

</h:form>
...

It's possible to insert optional separators between controls. For this purpose use
a "controlsSeparator" facet. An example is placed below.

...
<f:facet name="controlsSeparator">
<h:graphicImage value="/image/sep.png"/>
</f:facet>
...

Starting from 3.2.1 of RichFaces multiple <rich:datascroller> instances behavior and page
bindings are corrected. Incorrect page after model changes handling is added. Phase Listener
called before RenderResponce scans the page for the <rich:datascroller> and performs the
following operations:
o

Checks if the <rich:datascroller> is rendered. (If the checking generates an

exception, the <rich:datascroller> is considered to be not rendered )

If
the <rich:datascroller> is
rendered
the
table
the <rich:datascroller> is
of<rich:datascroller> .

attached

gets

the

value

of

the

to

page

which
attribute

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

Note:
Make sure, that all <rich:datascroller> components, defined for a table, have same values
for all "page" attributes. The page, specified in the last "page" , will be rendered in browser.

6.6.9.4. Reference Data

Table of <rich:datascroller> attributes.
Table 6.46. Component Identification Parameters

Name

Value

component-type

org.richfaces.Datascroller

component-class

org.richfaces.component.html.HtmlDatascroller

component-family

org.richfaces.Datascroller

renderer-type

org.richfaces.DataScrollerRenderer

tag-class

org.richfaces.taglib.DatascrollerTag

Table 6.47. JavaScript API

Function

Description

switchToPage(page
)

Switches to the defined page, "page" is Number or String

next()

Navigates to the next page

previous()

Navigates to the previous page

first()

Navigates to the first page

last()

Navigates to the last page

fastForward()

Navigates ahead over a certain number of pages. The number of pages to traverse is
defined with fastStep attribute

fastRewind()

Navigates backwards over a certain number of pages. The number of pages to traverse is
defined with fastStep attribute

Table 6.48. Facets

Facet

Description

controlsSeparator

Redefines optional separators between controls

first

Redefines the "first" button with the content set

first_disabled

Redefines the disabled "first" button with the content set

last

Redefines the "last" button with the content set

last_disabled

Redefines the disabled "last" button with the content set

fastrewind

Redefines the "fastrewind" button with the content set

fastrewind_disabled

Redefines the disabled "fastrewind" button with the content set

fastforward

Redefines the "fastforward" button with the content set

fastforward_disabled

Redefines the disabled "fastforward" button with the content set

previous

Redefines the "previous" button with the content set

previous_disabled

Redefines the disabled "previous" button with the content set

next

Redefines the "next" button with the content set

next_disabled

Redefines the disabled "next" button with the content set

pages

Redefines the pages buttons with the content set

Table 6.49. Style classes (selectors) with the corresponding skin parameters

Class (selector)
name

.rich-datascr-button

.rich-datascr-ctrlsseparator

Description

Defines styles for a button

Defines styles for a separator between

buttons

Skin Parameters

CSS properties
mapped

additionalBackgroundCol
or

background-color

panelBorderColor

border-color

panelBorderColor

border-color

generalFamilyFont

font-family

generalSizeFont

font-size

additionalBackgroundCol
or

background-color

panelBorderColor

border-color

panelBorderColor

border-color

generalFamilyFont

font-family

Class (selector)
name
.rich-datascrbutton-dsbld

.rich-datascr-act

.rich-datascr-inact

.rich-dtascrollertable

Description

Defines styles for a disabled button

Defines styles for an active button

Defines styles for an inactive button

Defines styles for a wrapper <table>

element of a datascroller

Skin Parameters

CSS properties
mapped

generalSizeFont

font-size

panelBorderColor

color

generalTextColor

border-top-color,
color

generalFamilyFont

font-family

generalSizeFont

font-size

headerBackgroundColor

border-top-color,
color

generalFamilyFont

font-family

generalSizeFont

font-size

panelBorderColor

border-color

tableBackgroundColor

background-color

Table 6.50. Style classes (selectors) without skin parameters

Class name

Description

.rich-datascr

Defines styles for a wrapper <div> element of a datascroller

You can find all necessary information about style classes redefinition in Definition of Custom
Style Classes section.

6.6.9.5. Relevant Resources Links

On the component LiveDemo page you can see the example of <rich:datascroller> usage
and sources for the given example.
The solution about how to do correct pagination using datascroller (load a part of data from
database) can be found on the RichFaces Users Forum.
How to use <rich:dataTable> and <rich:datascroller> in a context of Extended Data
Model see on the RichFaces Users Forum.
This
article describes
how
when <rich:datascroller> used.

to

solve <rich:datatable> update

problem

Here you can find out how to use pair of <rich:datascrollers> outside the any dataTable.
The solution about how to make <rich:datascroller> be updated after sorting/filtering can
be found on Data Iteration Components FAQ.