This article will introduce the basic pager, the many available sample pagers and then show you how you can easily customise them by making a few simple changes to achieve a dynamic effect. By the end of this article you should have a good idea of how the pager works and how to make your own creative changes to alter its look.
Default Pager
First we will look at the basic default pager. In figure 1 below, we see the default pager you get when, for example, you drop a view onto an XPage.
Figure 1: Default Pager
The default pager comes as part of the basic view control. Its pretty simple with Previous and Next controls and a page selector control for jumping quickly between pages. The text for the page links in the page selector control default to the number of the page.
Opening up such an XPage inside Designer and clicking on the pager itself inside the view will bring up the properties relating to this default pager (see figure 2). As you can see, the Pager style is set to "Sample 1". The next section covers the various different pager styles that can easily be selected from this panel.
Figure 2: Basic Pager viewed in Designer
Sample Pagers
There are a number of different styles of pagers available to you directly from the pager property panel by changing the pager style property. They range from the default pager as shown in figure 1 above to the more complex versions of the default pager as shown in figures 3 and 4 below...
Figure 3: Sample Pager 2
Figure 4: Sample Pager 3
...to pagers with icons replacing the text on the First, Next, Previous and Last links as shown in Figures 5 and 6 below
Figure 5: Sample Pager 4
Figure 6: Sample Pager 5
...to pagers with additional directional 'arrows' (<<,
) in the text on the First, Next, Previous and Last links as shown in Figures 7 and 8 below
Figure 7: Sample Pager 6
Figure 8: Sample Pager 7
These out of the box pagers will probably cover more than 95% of use cases but you can make further changes to the child controls themselves to customise the pager to another level.
Note that on large views, due to a performance issue, the "Last" link is replaced by the text "..."
Custom Pagers
The last pager style available in the pager property panel is the "Custom" style. When you select to create your own custom style pager, the following UI (see figure 9 below) becomes available to you.
Figure 9: Custom Pager Designer UI
This UI allows you to build your own custom pager with any many (or as few) of the available pager child controls included inside it. The child controls can simply be added and removed using the buttons in the pager properties panel and their order edited also. Each of the child controls included at this stage will have a default look and feel set by the currently active theme. We will look at how you can take one step further and customise these individual child controls in the next section.
Digging deeper
Each pager is made up of a number of individual child controls. There are the 4 main link controls (First, Next, Previous & Last), the page selector control, the current page display control and the separator control. These can be added to a pager in any order and you can have as many or as few of them inside a pager as you like.
Figure 10: Custom Pager creation
As we've seen already, the UI in Designer (see figure 10) allows us to add controls and change the order in which they display with some simple clicks of the mouse. Behind the scenes in the source code view, what you are doing is changing the contents and order of strings held in the layout property of the pager tag.
The pager layout property
Figure 11: Source code view showing the pager layout property
"headerPager" id="pager1" layout="Previous Group Next">
Above in figure 11, we see the layout property contains a space separated list of all the individual child controls displaying within the pager (in this example its the default pager layout). You can edit this list directly in the source window and use any of the predefined pager child controls from the following list...
First, Next, Previous, Last | - Action links containing default text showing the associated type of action |
FirstArrow, NextArrow, PreviousArrow, LastArrow | - Action links containing default text and arrows (e.g. "<<", " ") showing the associated type of action and direction. |
FirstImage, NextImage, PreviousImage, LastImage | - Links containing default images (e.g. and ) showing the associated type direction of the action. |
Group | - The page selector control (see page selector below) |
Status | - The current page control (see current page below) |
Separator, SeparatorPage | - The separator control and a default version containing the word "Page". |
So for example the standard sample 5 pager looks like this in the source code view...
"headerPager" id="pager1"
layout="SeparatorPage Status FirstImage PreviousImage SeparatorPage Group NextImage LastImage">
Applying a theme
The reasoning behind the pager layout property using a space seperated list of strings is to allow for easy application of a theme to the pager. It is possible using a theme entry to override the contents of the layout property and so directly control the contents of the pager via the theme.
e.g. in the current theme file add the following...
PagerControl.Pager
layout
PreviousArrow Group NextArrow
The theme gives you direct control over the content of the pager via the layout property and so you can simple swap child controls in and out of the pager using the theme as you wish (in this case above we are changing the layout of the pager to use previous and next arrow links on either side of a page selector control).
Taking this one step further, you can choose to style each individual child control by the addition of an entry in the theme. The theme id for each individual control follows the format PagerControl.Pager. where should be replaced by one of the following valid id's.
First, Next, Previous, Last | - Ids for action links. |
Firstarrow, Nextarrow, Previousarrow, Lastarrow | - Ids for action links with arrows. |
Firstimage, Nextimage, Previousimage, Lastimage | - Ids for action links with images. |
Group | - Id for page selector control. |
Status | - Id for current page control. |
Separator, Separatorpage | - Id for separator controls. |
So for example, to individually style the Next link in the pager you would need to add the following to your theme file...
PagerControl.Pager.Next
styleClass
myStyledNext
This will tell XPages that you wish to use the "myStyledNext" class from your CSS file to be applied to the Pager's Next action link.
The child controls
In order to get access to the individual child controls using the UI, we need to go to the design view and select any of the child elements in the pager itself (see figure 12 below).
Figure 12: Editing the pager child components
Here we can see the properties associated with the "First" link control. Lets take a closer look at each of the pager child controls and explore how we can individually customise them.
First, Next, Previous & Last
The basic function of these controls is to allow the user to move to the start, end and back and forth one page at a time. The basic controls default to text or an image depending on the setting in the pager style property. You can insert your own image by setting it in the property panel and also display some text beside the image by adding your own label. See below in figure 13 where the 'I' image is used for the Previous link, the 'B' image is used in the page selector and the 'M' imag e is used as the Next link.
Figure 13: An 'alternate' pager example
Page Selector
The page selector child control allows a user to define a group of page links and display them together. The default for this control is to show page numbers but you can replace the label property with any text you like and also add an image to represent the pages (see figure 9 above).
Current Page
The default current page control displays the number of the currently displayed page. It is possible to access further information for display in this control via its label property. The default functionality can be reproduced by changing the label value to "{0}". This special string is replaced by the number of the current page, so for example the following label... "The current page is {0}" will display at run time as "The current page is x" (where x is the current page number). You can also use the special string "{1}" in the label to display the number of the last page, e.g. "Current page is {0} of {1}".
e.g. Display the current page number inside a text string
"headerPager" id="pager1" pageCount="4">
"pagerControl1" type="Status"
value="The current page is {0}">
The separator control is a simple control that allows you to add extra text or images to the pager. Its main function is to simply act as a separator for the other controls (hence the name). It defaults to the "|" character but you can change its label to whatever you like or add an image to it for display. It can be quite useful for placing text on front of the Page Selector and Current Page controls.
Summary
The pager is a control that provides most of the functionality that a user will require by default but if you scratch below the surface, it is a highly customisable control that allows a high degree of flexibility in how it is displayed.