Q4Widgets API Documentation

q4.pager

A navigator for any kind of paginated content.

Latest Version update 1.2.7: 
- updated aria labels - removed 'Go To'
- on selecting new page, focus moves to top of new content
Version update 1.2.6: 
- added hidden div to announce page change
- added option for active and disabled class
- updated classes for elements for more consistency and BEM style
- added icons instead of svg for first/prev/next/last buttons
- added aria-disababled for elemenets that are disabled
- updated dots markup
Version update 1.2.5: 
- js--hidden class is now removed after items are reloaded if number of pages is greater than 1
- items are now hidden using js--hidden class and aria-hidden attribute
Version update 1.2.4: 
- Accessibility updates. Selector should be a NAV (see example). Added aria-labels and buttons for keyboard accessible users
Script link
q4.pager.1.2.7.min.js
Source file
q4.pager.js, line 2
Requires

Examples

This example uses the pager in conjunction with the q4.api widget. It uses the content option to automatically show and hide each page of events.

<div id='#events'></div>
<nav class="pager" aria-label="Pagination Navigation for **section name goes here**"></nav>

<script>
$('#events').events({
    template: (
        '<ul class="years">{{#years}}<li>{{year}}</li>{{/years}}</ul>' +
        '<ul class="items">' +
            '{{#items}}' +
            '<li>' +
                '<span class="date">{{date}}</span>' +
                '<a href="{{url}}">{{title}}</a>' +
            '</li>' +
            '{{/items}}' +
        '</ul>'
    ),
    yearTrigger: '.years li',
    complete: function (e) {
        $(e.target).pager({
            content: $(e.target).find('.items li'),
            perPage: 10,
            template: '<li class="pager_list-item"><button class="pager_button">{{{page}}}</button></li>',
            trigger: 'button'
        });
    }
});
</script>

Options

content stringjQuery
A jQuery object (or a selector for one) containing a number of elements. If this is passed, then when the page changes, the pager will show the elements on the current page and hide the others. Note: if the number of elements changes, you will need to reinitialize the pager.
count number
The number of items to page through. If `items` is passed, this will be overridden by the number of elements in that jQuery object.
perPage number
The number of items per page.
pageRange number
The number of pages to show at one time. Recommend using odd numbers. Adds "pager-hide" and "js--hidden" classes to all items that should be hidden.
Default value
null
Example
5
pages Array.<string>Array.<number>
A list of page numbers or labels. If this is empty, page numbers will be generated using `perPage` and either `content` or `count`.
startPage number
The active page on initialization.
Default value
1
showFirstLast boolean
Whether to show first/last page triggers.
Default value
true
showPrevNext boolean
Whether to show previous/next page triggers.
Default value
true
showPages boolean
Whether to show page number triggers.
Default value
true
showDots boolean
Whether to always show the first and last page with "..." to fill the gaps. Useful when dealing with large numbers of pages.
Default value
false
trigger string
A selector for each trigger.
Default value
button
activeClass string
The CSS class to add to a selected page trigger.
Default value
js--active
disabledClass string
The CSS class to add to a selected page trigger.
Default value
js--disabled
template string
A template for each trigger. Use {{page}} for the page number or label.
Default value
<li class="pager_list-item"><button class="pager_button">{{{page}}}</button></li>
clonePager Object
Whether and where to create a copy of the pager to another container
Default value
{"toggle":false,"selector":""}
labels Object
The text to display for first/last/previous/next page triggers.
pageMessageContainer string
A selector for a message saying which pages or items are being displayed.
pageMessageTemplate string
A Mustache template for the pagination message.
Example
'Showing items {{firstItem}} to {{lastItem}} of {{itemCount}}.'
Example
'Showing page {{page}} of {{pageCount}}.'
beforeChange function
A callback fired after a trigger is clicked.
Parameters
event Event
The triggering event.
data Object
A data object with these properties: - `page` The page we are changing to. - `prevPage` The page we are changing from.
afterChange function
A callback fired after updating the pager.
Parameters
event Event
The triggering event.
data Object
A data object with these properties: - `page` The page we are changing to. - `prevPage` The page we are changing from.

Methods

changePage
Set the current page displayed on the pager.
Parameters
page number/string
The page number or label to go to.
event Event
The event that triggered this change.