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

The Pager component can be driven in a variety of modes dependent on requirements. For the Infusion 1.5 release, what was previously a single monolithic component named fluid.pager has been factored into three components fluid.pager, fluid.table and fluid.pagedTable to make the different areas of responsibilities clearer. The component fluid.pager takes care of the pure functionality of paging - when used by itself it manages a pager bar holding a set of links which can be navigated to select different pages - however in this mode the component's user takes complete responsibility for rendering the UI which is being paged. The component fluid.pagedTable allows the framework to take responsibility for rendering the paged content using the Pager's built-in integration with Fluid's Renderer, and supports rendering of dynamic multi-page data-driven tables. The component fluid.table could be used just to render a single table without any paging, but this functionality has not received development attention in this release.

The Fluid Pager, like many Fluid components, is really an interface to a collection of Tutorial - Subcomponents that work together to provide a unified user experience. In particular, the Pager uses the following subcomponents:

PagerBar
- PageList
- PreviousNext
Summary
PageSize

Subcomponents of fluid.pagedTable

When used via the creator function named fluid.pagedTable which in addition to paging, manages paged content stored in a rendered table, the Pager component acquires the following additional subcomponents (the subcomponents listed under fluid.pager proper all remain available with the same configuration options):

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);      // EITHER
fluid.pagedTable(container, options); // OR

Status

This component is in Preview status

On This Page

See Also

Still need help?

Join the infusion-users mailing list and ask your questions there,
or hang out in our IRC Channel.

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 events:

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 updated state of the model. `oldModel` is a snapshot of this model before the event was fired. `that` is the overall component `that`
`onRenderPageLinks`	default	Fired when the pager's `pagerBar.pageList` control is preparing to render the page links - this requires that the pageList control is of type `fluid.pager.renderedPageList`. This event supplies the component tree that will be sent to the Renderer which may be manipulated or decorated to adjust the rendering behaviour	(Links Component Tree) New in v1.1:(Links Component Tree, newModel)	The component tree for the links - this will be an array of components with ids beginning with the prefix `page-link:` New in v1.1: A copy of the new `PagerModel` structure
`afterRender`	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.	`(that)`	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 new ChangeApplier

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. New in v1.1: The `pageRequest` parameter may also include a member `forceUpdate` which, if `true`, causes the `onModelChange` event to be fired on page change even if the `dataModel` has not actually changed.
`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

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:

Options available to `fluid.pager`:

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 available to the data-driven Pager `fluid.pagedTable`

The Pager can be used in a 100% markup-driven mode via the grade fluid.pager described above. It can also be used in a data-driven mode using the grade fluid.pagedTable:

fluid.pagedTable(container, options);

When Pager is configured for data-driven paging several other top-level Pager options and subcomponents become available:

Configuration of subcomponents available from fluid.pagedTable:

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.

Subcomponents available to both `fluid.pager` and `fluid.pagedTable`

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, and
fluid.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.

pageStrategy implementations

The framework includes three pageStrategy implementations:

fluid.pager.everyPageStrategy, which generates an entry for every page in the range
fluid.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 a pageStrategy 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.summary

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

Subcomponents available only to `fluid.pagedTable`

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 configure the rangeAnnotator subcomponent, as follows:

components: {
    rangeAnnotator: {
        type: "fluid.pager.rangeAnnotator"
    }
}

Top-level options for the RangeAnnotator

Please note that these options, while used to configure the RangeAnnotator subcomponent, can provided as top-level options to the Pager itself. The framework automatically forwards them to the rangeAnnotator subcomponent, if it is configured, using the distributeOptions system:

BodyRenderer subcomponent

The component (actually declared in the parent grade fluid.table) bodyRenderer performs 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 table 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.table.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
`selectors`
`keyStrategy`			`keyStrategy: "id"`
`keyPrefix`			`keyPrefix: ""`
`row`			`row: "row:"`
`header`			`header: "header:"`
`renderOptions`			`renderOptions: {`}

Options for fluid.table.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 model is used for both fluid.pager as well as fluid.pagedTable.

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.
If the creator fluid.pagedTable is used, the component exposes an additional model under that.dataModel holding the user's data model consists of the actual data being paged.

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
`[fluid:pageLimit]`	integer	Computed	The limit of the range of items shown on the current page represented by the model
`sortKey`	string	Primary	The `key` the `columnDef` for a column whose data is to be used for sorting the table [Optional - only supported for rendered views]
`sortDir`	-1 or 1	Primary	+1 represents sorting in ascending order by the `sortKey`, -1 represents sorting in descending order

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>

Pager Overview

Renderer Use

Subcomponents of fluid.pager

Subcomponents of fluid.pagedTable

Creation

Parameters

container

options

Supported Events

Options

Options available to fluid.pager:

Options available to the data-driven Pager fluid.pagedTable

Configuration of subcomponents available from fluid.pagedTable:

The ColumnDef structure

Component expansion

Subcomponents available to both fluid.pager and fluid.pagedTable

PagerBar subcomponent

options

PageList subcomponent

Options for fluid.pager.renderedPageList

pageStrategy implementations

PreviousNext subcomponent

Summary subcomponent

options

PageSize subcomponent

Subcomponents available only to fluid.pagedTable

RangeAnnotator subcomponent

Top-level options for the RangeAnnotator

BodyRenderer subcomponent

options

Options for fluid.table.selfRender

The Pager Model

Dependencies

Options available to `fluid.pager`:

Options available to the data-driven Pager `fluid.pagedTable`

Subcomponents available to both `fluid.pager` and `fluid.pagedTable`

Subcomponents available only to `fluid.pagedTable`

Browser not supported