Pager API
Pager Overview
The Pager component allows users to break up long lists of items into separate pages. Users can decide if they want paging and how many items should be presented per page.
Renderer Use
While the Pager can be used in a 100% markup-driven mode, it is recommended to use the data-driven mode. This mode uses the Pager's built-in integration with Fluid's Renderer, and supports rendering of dynamic multi-page data-driven tables.
NOTE: At this time, the Renderer-based data-driven mode is NOT the default mode for the Pager. To use the data-driven mode, you must configure certain options. For specific information on how to do this, see #Options for the Data-driven Pager below. In future releases, the data-driven mode will be the default mode, and less of this configuration will be required.
Subcomponents
The Fluid Pager, like many Fluid components, is really one interface to a collection of Subcomponents that work together to provide a unified user experience. In particular, the Pager uses the following subcomponents:
- PagerBar
- PageList
- PreviousNext
- Summary
- PageSize
- RangeAnnotator
- BodyRenderer
(For a description of these subcomponents, and an example showing how they might fit together, see Pager Subcomponents.)
These subcomponents are instantiated and managed by the Pager, but each has options that can be used to configure and customize it. These subcomponents, and their options, are described individually below.
Creation
fluid.pager(container, options);
This component is in Preview status
- Pager Component description
- Pager Tutorial - Markup-driven
- Fluid Component API
Join the infusion-users mailing list and ask your questions there.
Parameters
container
The container
parameter is is a selector, a single-element jQuery, or a DOM element specifying the root DOM node of the Pager markup.
options
The options
parameter is an optional collection of name-value pairs that configure the Pager and its subcomponents, as described below in the fluid:Options section.
Supported Events
The Pager component fires the following event:
Event |
Type |
Description |
Parameters |
Parameter Description |
---|---|---|---|---|
|
default |
Fired whenever the pager's model changes - that is, whenever there is a change to the displayed range of data for the pager, caused by a change to the page index, page size or underlying data |
|
|
|
default |
Fired when the pager's |
(Links Component Tree) |
The component tree for the links - this will be an array of components with ids beginning with the prefix |
New in v1.4: |
default |
Fired after any rendering of the Pager triggered by a model change, such as a page change, change in number if items per page, etc. This event fires after the initial rendering of the Pager. |
|
The overall Pager component object |
In addition, in this release, the Pager also supports the following events, which are however implementation-specific, and part of a transitional implementation strategy before the adoption of the Data Binder and BeanInvalidationModel:
Event |
Type |
Description |
Parameters |
Parameter Description |
---|---|---|---|---|
|
default |
Fired when the implementation wishes to initiate the change of state corresponding to the selection of a new page |
|
A structure which includes either the member |
|
default |
Fired when the implementation wishes to initiate the change of state corresponding to an updated page size for the visible range |
|
an integer representing the desired new page size |
For more information about events, see Events for Component Users.
Options
The following options to the creator function can be used to customize the behaviour of the Pager component:
There are also options available to select and configure each of the subcomponents used by the Pager. These options are listed here, and their contents are described in detail in the relevant sections below.
Options for the Data-driven Pager
While the Pager can be used in a 100% markup-driven mode, it is recommended to use the Pager's built-in integration with Fluid's Renderer, which supports rendering of dynamic multi-page data-driven tables. If the Renderer is used, various configuration information must be provided for it.
To configure the Pager in data-driven mode, you must request the fluid.pager.selfRender
for the bodyRenderer
option, as follows:
bodyRenderer: { type: "fluid.pager.selfRender", options: selfRenderOptions }
The selfRenderOptions
are described below, in the #BodyRenderer subcomponent section.
When Pager is configured for data-driven paging by setting the bodyRenderer
option to fluid.pager.selfRender
, several other top-level Pager options become available. NOTE that when the self-rendering is not used, these options are ignored.
The ColumnDef structure
The configuration option columnDefs
takes the form of an array of ColumnDef
objects, one configuring each required column of the rendered table (a renderer must be in use).
NOTE: Understanding the ColumnDef
object will be greatly facilitated by looking at the Renderer documentation.
The following table explains the layout and function of the fields in the ColumnDef
structure:
Component expansion
As this component is cloned, once for each cell in its column, it will undergo various forms of expansion - the most important of these is with respect to the special placeholder value fluid.VALUE
. This may be placed where any string or UIBound
component is expected, and will be expanded to hold either the value or binding of the correct column cell, with respect to the wildcard path specified in valuebinding
. A further form of expansion also allows interpolation of read-only values in the middle of literal string, by use of a Smarty-like variable syntax. The string ${VALUE
} will expand to the same value as fluid.VALUE
, whereas general EL expressions of the form which are supported for valuebinding
are also supported.
Here is a sample of a ColumnDef
object with a UILink
type cell showing both forms of substitution:
{key: "user-link", valuebinding: "*.userDisplayName", components: { target: "/dev/sn/profile.html?user=${*.userId}", linktext: fluid.VALUE}, sortable:true }
Here, the linktext
field will be bound to *.userDisplayName
, whereas the URL target will be formed by interpolation with a value from *.userId
. In this case both of these EL paths will be prefixed by any value in dataOffset
before fetching.
PagerBar subcomponent
The PagerBar
is the most substantial subcomponent of the pager, and contains controls operating links for page navigation - these may include previous/next, first/last as well as an array of numbered page links. The dropdown control for selecting page size, PageSize
may be physically nested within the same container as the markup managed by the PagerBar
, but is not logically part of the same control.
Subcomponent Name: fluid.pager.pagerBar
Two PagerBars may be configured for a Pager control, under the names pagerBar
and pagerBarSecondary
which were mentioned in the top-level options
structure above. These may appear at arbitrary positions in the overall markup (top/bottom, etc.), however, the pagerBar
is primary in that if one of these bars is omitted, it must be the pagerBarSecondary
.
options
PageList subcomponent
The PageList
subcomponent is actually a second-level subcomponent of the overall Pager - it is nested within the PagerBar
component configured at top level. PageList
is responsible for managing, and optionally rendering, a list of page link controls which allow quick random access to different page views.
Two implementations are provided:
fluid.pager.directPageList
(the default) which simply accepts a pre-rendered and unchanging list of page links present in the DOM at startup, andfluid.pager.renderedPageList
which treats the links in the DOM as a template, and accepts further configuration in order to generate a link list dynamically as the number of view pages alters.
The configuration for fluid.pager.directPageList
is taken entirely from the pageLinks
selector configured into the top-level components.
Options for fluid.pager.renderedPageList
pageStrategy implementations
The framework includes three pageStrategy
implementations:
fluid.pager.everyPageStrategy
, which generates an entry for every page in the rangefluid.pager.gappedPageStrategy
, which is a factory function which generates implementations which will collapse pages which are not near either the ends of the range or the currently visible page. For example,fluid.pager.gappedPageStrategy(3, 1)
will return apageStrategy
implementation which will return page numbers that are either within 3 pages of the end of the range, or within 1 of the current page position.fluid.pager.fluid.pager.consistentGappedPageStrategy
, will always display same number of page links (including skip place holders)
Integrators can choose to use one of these strategies by overriding the pageStrategy
options of the fluid.pager.renderedPageList
subcomponent.
PreviousNext subcomponent
The PagerBar
also has a PreviousNext
subcomponent, which displays controls for navigating to the 'next' or 'previous' page. This subcomponent has no options of its own.
Subcomponent Name: fluid.pager.previousNext
Summary subcomponent
The purpose of the summary component is to manage a small textual control representing an overall "summary" of the paging state. This typically holds a message reading similarly to "30-31 of 139 items"
Subcomponent Name: fluid.pager.summayr
options
PageSize subcomponent
The PageSize
component operates a control which allows the user to select the number of items shown at one time on a visible page of the control.
Subcomponent Name: fluid.pager.pageSize
The default implementation of the PageSize
component has no options of its own. Its assumption is that the tag identified by the pageSize
selector configured at the top-level component represents a standard HTML <select>
control which has been populated with a list of the desired range of page sizes. By default as listed above, the type of the PageSize
subcomponent is initialised to "fluid.pager.directPageSize"
.
RangeAnnotator subcomponent
The RangeAnnotator
subcomponent decorates the displayed page links with a tooltip displaying the range of data values held on that page. To use the RangeAnnotator
, you must specify the rangeAnnotator
option, as follows:
rangeAnnotator: { type: "fluid.pager.rangeAnnotator" }
Note that if the RangeAnnotator
is used you must provide top-level the annotateColumnRange
options. When the RangeAnnotator
is used, several other top-level Pager options become available. NOTE that when the RangeAnnotator
is not used, these options are ignored.
Top-level options for the RangeAnnotator
Please note that these options, while used to configure the RangeAnnotator
subcomponent, must be provided as top-level options to the Pager itself. In future releases, they will become options of the RangeAnnotator
itself.
BodyRenderer subcomponent
The component configured as bodyRenderer
, to the knowledge of the overall Page component, simply has the role of a standard listener to onModelChanegd
. However, the special function of this subcomponent, if configured, is to perform the work of locating an HTML template suitable for rendering the actual paged view contents, and responding to changes in the pager's model for the purpose of keeping the rendered View updated.
The work of rendering the paged body is split into two parts - firstly, the part of preparing the direct (JSON) representation of the data to be renderered. This is performed by the top-level component configured as modelFilter
. A ModelFilter
is simply a function, whose signature and purpose is documented as part of the top-level component options - it need not actually make use its argument model
to filter the data View, but there is a standard implementation fluid.pager.directModelFilter
that simply takes the model
(configured as the top-level that.options.dataModel
) and extracts just those rows identified by the pagerModel
.
The standard implementation of the BodyRenderer
in fluid.pager.selfRender
locates and makes use of the configured top-level ModelFilter
in its listener implementation. The ModelFilter
is invoked to do its work of preparing the data suitable for this event cycle, which is then handed to the Fluid Renderer - Background for rendering. Other implementations of BodyRenderer
might use other rendering schemes.
options
Name |
Description |
Values |
Default |
---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Options for fluid.pager.selfRender
The Pager Model
Where the component that
is constructed by a line such as
var that = fluid.pager(component, options);
the returned object will have a data member called model
:
that.model
This object is the "model" of the pager - note that this is not the same as the data model of the user:
- The Pager's model consists of the state of the paging component, which specifies the page index position, overall data range and page size.
- The user's data model consists of the actual data being paged, which is stored in
that.options.dataModel
.
This, the Pager's model, should be treated as read-only via this interface, and should only be manipulated by use of the component's event system.
The pager model is laid out as following:
Field |
Type |
Primary/Computed |
Description |
---|---|---|---|
|
integer |
Primary |
The current index of the page, expressed 0-based amongst the range of pages |
|
integer |
Primary |
The number of "items" which may be shown on a page |
|
integer |
Primary |
The total count of "items" in the underlying user's data model |
|
integer |
Computed |
The limit of the range in which pageIndex is expressed |
|
integer |
Computed |
The limit of the range of items shown on the current page represented by the model |
|
string |
Primary |
The |
|
-1 or 1 |
Primary |
+1 represents sorting in ascending order by the |
Note that pageLimit
is not actually stored within the model at any point, but is supplied a computation function computePageLimit
to match computePageCount
by which pageCount
is derived from the primary fields.
Dependencies
The Pager dependencies can be met by including the minified InfusionAll.js
file in the header of the HTML file:
<script type="text/javascript" src="InfusionAll.js"></script>
Alternatively, the individual file requirements are:
<!-- Stylesheets --> <link rel="stylesheet" type="text/css" href="framework/fss/css/fss-reset.css" /> <link rel="stylesheet" type="text/css" href="framework/fss/css/fss-layout.css" /> <link rel="stylesheet" type="text/css" href="components/pager/css/Pager.css" media="all" /> <link rel="stylesheet" type="text/css" href="lib/jquery/plugins/tooltip/css/jquery.tooltip.css" media="all" /> <link rel="stylesheet" type="text/css" href="lib/jquery/ui/css/jquery.ui.theme.css" /> <!-- Scripts --> <script type="text/javascript" src="lib/jquery/core/js/jquery.js"></script> <script type="text/javascript" src="lib/jquery/ui/js/jquery.ui.core.js"></script> <!-- New in v1.3 --> <script type="text/javascript" src="lib/jquery/ui/js/jquery.ui.widget.js"></script> <!-- New in v1.3 --> <script type="text/javascript" src="lib/jquery/ui/js/jquery.ui.position.js"></script> <!-- New in v1.3 --> <script type="text/javascript" src="lib/jquery/plugins/bgiframe/js/jquery.bgiframe.js"></script> <!-- New in v1.3 --> <script type="text/javascript" src="lib/jquery/plugins/tooltip/js/jquery.ui.tooltip.js"></script> <!-- New in v1.3 --> <script type="text/javascript" src="lib/json/js/json2.js"></script> <!-- New in v1.3 --> <script type="text/javascript" src="framework/core/js/Fluid.js"></script> <script type="text/javascript" src="framework/core/js/FluidDOMUtilities.js"></script> <!-- New in v1.3 --> <script type="text/javascript" src="framework/core/js/FluidDocument.js"></script> <!-- New in v1.3 --> <script type="text/javascript" src="framework/core/js/jquery.keyboard-a11y.js"></script> <!-- New in v1.3 --> <script type="text/javascript" src="framework/core/js/DataBinding.js"></script> <script type="text/javascript" src="framework/core/js/FluidRequests.js"></script> <!-- New in v1.3 --> <script type="text/javascript" src="lib/fastXmlPull/js/fastXmlPull.js"></script> <script type="text/javascript" src="framework/renderer/js/fluidParser.js"></script> <script type="text/javascript" src="framework/renderer/js/fluidRenderer.js"></script> <script type="text/javascript" src="components/tooltip/js/Tooltip.js"></script> <!-- New in v1.3 --> <script type="text/javascript" src="components/pager/js/Pager.js"></script>