This documentation refers to the latest trunk version of the Pager code. For information related to the v0.5 released version, please see Pager API - v0.5. |
Pager Overview
The Pager component allows users to break up long lists of items into separate pages. In the Fluid 0.6 release, the Pager, as well as operating a 100% markup-driven mode, also features integration with Fluid's Renderer to support rendering of dynamic multi-page data-driven tables. However, the Renderer integration as of this release should be considered experimental.
Markup assumptions
The Pager makes certain assumptions about the mark-up:
- The entire pager must be contained within a container element.
- Within that container, there are one or two 'pager bar' elements, each containing:
- any number of page links
- optionally, a 'next' element and a 'previous' element
- optionally, a dropdown control for selecting the page size
The Pager uses CSS selectors to access these various components. Default selectors are assumed, which can be overriden (see #options below). |
|
Creation
fluid.pager(container, options);
|
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, as described below in the Options section.
Supported Events
The Pager component fires the following event:
Event |
Type |
Description |
Parameters |
Parameter Description |
onModelChange
|
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 |
(newModel, oldModel, that)
|
newModel is a structure of type PagerModel and represents the update state of the model. oldModel is a snapshot of this model before the event was fired. that is the overall component that |
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 |
initiatePageChange
|
default |
Fired when the implementation wishes to initiate the change of state corresponding to the selection of a new page |
(pageRequest)
|
A structure which includes either the member pageIndex representing the new required page index, or relativePage representing an offset from the current page position |
initiatePageSizeChange
|
default |
Fired when the implementation wishes to initiate the change of state corresponding to an updated page size for the visible range |
newPageSize |
an integer representing the desired new page size |
that organization
Where the component that is constructed by a line such as
var that = fluid.pager(component, options);
|
, the returned object will have the following top-level organisation in terms of subcomponents and model:
The "model" of the pager - note to distinguish carefully between the pager's model, and 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 |
pageIndex |
integer |
Primary |
The current index of the page, expressed 0-based amongst the range of pages |
pageSize |
integer |
Primary |
The number of "items" which may be shown on a page |
totalRange |
integer |
Primary |
The total count of "items" in the underlying user's data model |
pageCount |
integer |
Computed |
The limit of the range in which pageIndex is expressed |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="f5204111-88e5-41fe-b6b8-9245647a28d5"><ac:plain-text-body><![CDATA[ |
[pageLimit] |
integer |
Computed |
The limit of the range of items shown on the current page represented by the model |
]]></ac:plain-text-body></ac:structured-macro> |
(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.
Options
The following options to the creator function can be used to customize the behaviour of the Pager component:
Name |
Description |
Values |
Default |
selectors |
Javascript object containing selectors for various fragments of the Pager component. |
The object may contain any subset of the following keys:
pagerTop
pagerBottom
pageLinks
previous
next
Any values not provided will revert to the default. |
selectors: {
pagerTop: ".pager-top",
pagerBottom: ".pager-bottom",
pageLinks: ".page-link",
previous: ".previous",
next: ".next"
}
|
|
styles |
Javascript object containing CSS style names that will be applied to the Pager component. |
The object may contain any subset of the following keys:
currentPage
disabled
Any values not provided will revert to the default. |
styles: {
currentPage: "current-page",
disabled: "disabled"
}
|
|
pageWillChange |
A function that will be called each time a new page has been selected. This function will most likely retrieve data for the selected page, or otherwise update the data. |
a function |
pageWillChange: function (link) {
}
|
|
Dependencies
The Pager dependencies can be met by including the minified Fluid-all.js file in the header of the HTML file:
<script type="text/javascript" src="Fluid-all.js"></script>
|
Alternatively, the individual file requirements are:
<script type="text/javascript" src="jquery/jquery-1.2.6.js"></script>
<script type="text/javascript" src="fluid/Fluid.js"></script>
<script type="text/javascript" src="fluid/Pager.js"></script>
|