This tutorial applies to Infusion v1.3 and earlier. If you are using Infusion v1.3.1 or later, please see the latest Pager Tutorial
This page will walk you through an example of adding the Infusion Pager to your application.
This tutorial assumes that:
- you are familiar with what the Pager is and does
- now you just want to know how to add it to your file.
Tutorial: How to Use the Pager
You're implementing a roster for a large school, and since there are thousands of students at this school, you want the list of students to be paged. This tutorial will show you how to use the Infusion Pager for this.
There are four basic steps to adding the Pager to your application:
- Setup: Download and install the Fluid Infusion library
- Step 1: Prepare your markup
- Step 2: Write the script, setting the options
- Step 3: Add the script and styles to your HTML
The rest of this tutorial will explain each of these steps in detail.
Setup: Download and install the Fluid Infusion library
- Download a copy of the Fluid Infusion component library from:
You only really need the "Minified deployment package," but if you want to actually look at the code, you should download the "Source package."
- Unpack the zip file you just downloaded, and place the resulting folder somewhere convenient for your development purposes.
The folder will have the release number in its name (e.g. infusion-1.4/). The rest of this tutorial will use infusion-1.4 in its examples, but if you downloaded a different version, you'll have to adjust.
Step 1: Prepare your markup
The Rendered version of the Pager component works with the raw data that you want paged, and lays is out according to a template you provide in your mark-up.
The Pager is made up of several parts:
- a Pager Bar: The set of links to different pages (some people use two of these, one above the data, one below)
- the paged data itself
- a summary, such as "Items 20-30 of 76" (this is optional)
- a control to allow the user to change the number of items per page (this is also optional)
Let's say you want to display your roster results in a
<table> element, and you want the page links at the top. We'll start simple, with just a top Pager Bar above the paged data (we'll add a summary and other enhancements later). Because you're dealing with thousands of student, you obviously don't want to have to manually create a
<table> with thousands of rows – this is where the Pager's use of the Renderer comes in. In your HTML, you simply create a single table row that acts as a template to be used for each row. The same applies to the page links in the Pager Bar: you only define the minimum set of links necessary to illustrate how you want the links rendered.
So we might have something like this:
Some notes about this mark-up:
- This code uses the Fluid Skinning System (FSS) for some layout, in particular, the "fl-force-left" and "fl-container-flex" classes.
- This code assumes you have a CSS file containing the various "demo-..." CSS classes for styling the markup.
Next, you will need to let the Pager know which pieces of mark-up are to be used for what. This is accomplished though an
class on an element. In particular, you'll need to identify
- the main container of the entire Pager markup
- the container of the Pager Bar
- the different kinds of links in the Pager Bar
- the table you're using for the data
- the row template, and the columns within it
The Pager defines some default class names for some of these things. Others, you will have to define yourself. So:
- the main container of the entire Pager markup: There is no default for this, so let's attach an
idof "demo-pager-container" to our main
- the container of the Pager Bar: The default for this is a class name of "flc-pager-top" so we'll add that class to the
<div>containing our list of links (note that all default selectors for Fluid components start with "flc-", which is short for "fluid component." These selectors are used for manipulating the DOM only, and should not be used for styling.)
- the different kinds of links in the Pager Bar: The pager defines a number of default class names for these links, so we'll use those:
- "flc-pager-previous" for the link to the 'previous' page of data
- "flc-pager-next" for the link to the 'next' page of data
- "flc-pager-links" for the container for the page-specific links
- "flc-pager-pageLink" for an individual page-specific link
- "flc-pager-pageLink-skip" for the markup to use where there are gaps in the page links, used with the "gapped" page strategy. This is useful when there will be many links, and can be used to produce lists like "1 2 3 ... 7 8 9 ... 12 13")
- the table you're using for the data: There is no default for this, so let's attach an
idof "membership-table" to the
- the row template, and the columns within it: The pager requires a special
idwith a namespace of
rsffor these items, so we'll define the namespace for the table, and add ids to the row and each of the column cells. Note that the row id must have a colon (:) at the end of it, to indicate that it will be repeated.
This should get us started.
Step 2: Write the script, setting the options
You'll need to create a file, say
pagersetup.js, to contain your initialization script - the script you write to apply the Pager to your roster:
Initializing a Pager is pretty simple: one call to the creator function, passing
- the selector for your main container (
- options for configuring your Pager. It's setting up the options where the magic happens.
bodyRenderer option allows you to specify and configure the subcomponent used to render the actual data. By default, no subcomponent is used (valid in the case where all of the necessary mark-up has been provided), but we want the Pager to render our data for us, so we will configure it to use the
fluid.pager.selfRender subcomponent provided with the Pager.
The option value itself is an object containing the name of the subcomponent and configuration options for it:
selectors option to the subcomponent specifies the
<div> that contains our data table.
The Pager will automatically create a Pager Bar component, but the
pagerBar option allows you to customize some of the behaviour of the Pager Bar.
The Pager Bar includes two subcomponents: PageList, which controls the actual list of page links, and PreviousNext, which controls the 'next' and 'previous' buttons (see Pager Subcomponents for more information). The default 'next'/'previous' subcomponent should be fine for us, but the default PageList is called a "direct" page list. This is only useful if you already have markup for each page link. Since we don't know how many pages we'll have, we need to use the "rendered" page list provided by the Pager.
For our scenario, our
dataModel will look like this:
dataOffset option tells the pager where in the
dataModel to look for the actual data. This option is not always necessary, depending on the format of
dataModel. In our case, we need to specify it, as shown on the right.
model option contains the initial settings for the Pager model itself. This is different than the
model includes information such as the number of items which may be shown on the page, the sort order, the index of the current page, etc. The Pager includes defaults for these, but for our use case, we'll override one of the defaults: We'd like the initial number of items per page to be larger than the default of 10:
columnDefs option defines the rules for extracting and presenting data from the data model into your columns. It is an array containing one entry for each column which is to be rendered in the table.
Our data model is relatively simple, so our
columnDefs entries only need to specify two things:
key: This is the
rsf:idof the element in the markup that is the column where the data should go
valuebinding: This is the path into your
dataModelof the data that should be rendered into the column
If you recall, our template for the rows looked like this:
and our data model for the roster looked like this:
columnDefs structure will be as shown on the right.
These options are the minimum you will need to set to use the rendered Pager.
Step 3: Add the script and styles to your HTML
You'll need to add your initialization script, along with the Fluid library and Pager style sheets, to you HTML file, as shown below::
NOTE that the
InfusionAll.js file is minified - all of the whitespace has been removed, so it isn't really human-readable. If you're using the source distribution and you want to be able to debug the code, you'll want to include each of the required files individually. This would look like this:
InfusionAll.js file has everything you need.
The Rendered page list we selected for our Pager Bar renders one link for every page of data. This is fine if you have a handful of pages, but what if you have tens of page? or hundreds? The rendered page list uses a strategy for rendering the list of links. The default is a "direct list" – one link per page. For cases where you expect to have many, many pages, the Pager provides a strategy called the "Gapped Page Strategy." This strategy displays the links for first few pages and the last few pages, and for some pages around the current page, but simply shows a gap for any other pages. As different pages are selected, the gaps are automatically adjusted.
We construct the gapped page strategy by calling the function
fluid.pager.gappedPageStrategy(locality, midLocality). We will configure our PageList to only include the first and last 3 pages (
locality), or within 1 of the current page position (
The Pager provides the ability to sort the table's rows with respect to a column. This is accomplished very easily, by simply
- adding a flag to the
- ensuring that the headers of the sortable columns are links.
This example defines the name, email and role columns as sortable, and the comments column as not sortable. (Note that not sortable is the default, so strictly speaking, it is not necessary to set
When we convert the header text to a link, we must assign the link the same
rsf:id as we did for the data in the columns themselves. This ensures that when the header is used to sort the data, the correct column of data is used.
Another feature the Pager offers is the ability to provide information about what range of data is associated with a given page. This is an annotation attached to each page link, displayed as a tooltip when a page link is hovered over and spoken aloud by screen readers when a page link receives keyboard focus.
To enable the range annotation, use the
annotateColumnRange option of the Pager. Set its value to the
rsf:id of the column to extract the range data from:
Here, we're selecting the user name column as the source data for the range annotation. With this option enabled, the range annotation tooltip will display the first and last user names that would appear on the given page's data.