# Constructor
## Commonly used
### dataSource array | string | object | function
Data source, ultimately an array will be provided for Pagination.
Data source supports 4 formats.
1. **Array**
Directly provide an array, such as:
['1', '2', '3', '4']
2. **Object**
Provide an object, which will contain an array, and the array can be specified via `locator: 'data'`.
{
data: ['1', '2', '3', '4']
}
3. **Function**
Provide a custom function, use `done` to return an array, can achieve above 2 ways.
dataSource: function(done){
var result = [];
for(var i = 1; i < 196; i++){
result.push(i);
}
done(result);
}
You can also send a request to get data, use `done` return asynchronous data.
dataSource: function(done){
$.ajax({
type: 'GET',
url: '/test.json',
success: function(response){
done(response);
}
});
}
4. **URL**
Provide a URL, returns data via Ajax, each request returns one page of data, the data returned can also be located by `locator`.
If URL is file, HTTP or HTTPS protocol, will using `jsonp` to send requests, otherwise Ajax.
/test.json
For each pagination request, two parameters `pageNumber` and `pageSize` will be added, you can also use `alias` to specify the parameter's name.
/test.json?pageNumber=2&pageSize=10
### locator string | function (default `data`)
In general, data source is an array, and it can be processed directly by Pagination. But if the return is an Object, then you need to specify that array.
This option is used to manually modify the location of that array in data source.
Used as a string:
`locator: 'data'`:
```
{
data: ['1', '2', '3', '4']
}
```
locator uses [to-function](https://github.com/component/to-function), so you may use dot notation to traverse the result array, such as `locator: 'a.b'`:
```
{
a: {b: ['1', '2', '3', '4']}
}
```
Using as a function:
Provide a custom function, find the array position, and return.
```
locator: function(){
// find data and return
return 'a.b';
}
```
Please note that the data via Ajax will apply the same rules.
### totalNumber number (default `1`)
Total entries, This option must be specified when pagination is asynchronous.
Note: This option only has effect in Pagination constructor and only if dataSource option is a URL.
### pageNumber number (default `1`)
Specify the page number at initialization.
### pageSize number (default `10`)
Entries of per page.
### pageRange number (default `2`)
Range of visible page number, this means that the amount on both sides of the selected page. For example, if the selected page number is `6`, and pageRange set to 2, then the pagination bar will be displayed as like this '1 ... 4 5`6`7 8'.
### callback function(data, pagination)
Callback of each paging. Useful for process the result data before rendered.
The `callback` function will get two parameters
callback: function(data, pagination){ ... }
Parameter | Type | Description
------------ | ------------- | ------------
data | array | data of selected page
pagination | object | pagination data
`pagination` object contains the following custom properties:
Property | Type | Description
------------ | ------------- | ------------
pageNumber | number | The selected page number
pageRange | number | Visible page number range
pageSize | number | Entries of per page
totalPage | number | Total page
totalNumber | number | Total entries
el | jQuery object | Pagination element
direction | number | Pagination direction, `-1` means forward, `1` means backward, `0` means current is at initialization.
### alias object
Used to manually modify the parameters of the Ajax request. Useful for asynchronous pagination.
Here's the example:
alias: {
pageNumber: 'pageNum',
pageSize: 'limit'
}
When the Ajax request sent, will replace the defaults `pageaNumber` and `pageSize`.
/test.json?pageNum=2&limit=10
## Display control
### showPrevious boolean (default `true`)
Determines whether to display the `previous` button.
### showNext boolean (default `true`)
Determines whether to display the `next` button.
### showPageNumbers boolean (default `true`)
Determines whether to display the page number buttons.
### showNavigator boolean (default `false`)
Determines whether to display the navigator.
### showGoInput boolean (default `false`)
Determines whether to display the 'Go' input box.
### showGoButton boolean (default `false`)
Determines whether to display the 'Go' button.
### showFirstOnEllipsisShow boolean (default `true`)
Determines whether to display the first page number buttons when the ellipsis was displayed.
showBeginingOnOmit: false,
pageRange: 1,
totalNumber: 100,
pageSize: 10
The above settings, pagination bar will be displayed as like this "... 4 `5` 6 ... 10".
### showLastOnEllipsisShow boolean (default `true`)
Determines whether to display the last page number when the ellipsis was displayed.
showEndingOnOmit: false,
pageRange: 1,
totalNumber: 100,
pageSize: 10
The above settings, for example, pagination bar will be displayed as like this "1 ... 4 `5` 6 ...".
### autoHidePrevious boolean (default `false`)
Determines whether to display the `previous` button when the selected page number was the first page.
See [demo](/index.html#auto_hide)
### autoHideNext boolean (default `false`)
Determines whether to display the `next` button when the selected page number was the last page.
See [demo](/index.html#auto_hide)
## Style
### classPrefix string
Style prefix. Default is `pagination`.
### className string
Additional style class(es) for the Pagination element.
### activeClassName string
ClassName of the selected page number button. Default is `active`.
### disableClassName string
ClassName of the disabled page number button. Default is `disabled`.
### ulClassName string
ClassName of the 'ul' element that contained by the Pagination element.
## Customizable text
### prevText string
The text to display for the `previous` button. Default is `«`. That is the symbol '«'.
### nextText string
The text to display for the `next` button. Default is `»`. That is the symbol '»'.
### ellipsisText string
The text to display for the ellipsis button. Default is `...`.
### goButtonText string
The text to display for the `Go` button. Default is `Go`.
### formatNavigator string | function
Format template for the navigator. Default is `<%= currentPage %> / <%= totalPage %>`.
String containing the template variables or a function that returns such a string.
Provide 3 template variables.
- `currentPage`
- `totalPage`
- `totalNumber` Total entries.
See [demo](/index.html#format_navigator)
### formatGoInput string | function
Format template for the 'Go' input box. Default is `<%= input %>`.
String containing the template variables or a function that returns such a string.
`<%= input %>` is equivalent to a package of ``, therefore, you can also customize an input box element, ensure that the element has the `J-paginationjs-go-pagenumber` class.
Provide 4 template variables.
- `input`
- `currentPage`
- `totalPage`
- `totalNumber` Total entries.
See [demo](/index.html#format_go_input)
### formatGoButton string | function
Format template for the 'Go' button. Default is `<%= button %>`.
String containing the template variables or a function that returns such a string.
`<%= button %>` is equivalent to a package of ``, therefore, you can also customize an button element, ensure that the element has the `J-paginationjs-go-button` class.
Provide 4 template variables.
- `button`
- `currentPage`
- `totalPage`
- `totalNumber` Total entries.
### header string | function
Custom header content. `header` may be a string or a function.
Provide 3 template variables.
- `currentPage`
- `totalPage`
- `totalNumber`
### footer string | function
Custom footer content. `footer` may be a string or a function.
Provide 3 template variables.
- `currentPage`
- `totalPage`
- `totalNumber`
### pageLink string
Page link.
## Utilities
### formatResult function(data)
Provide a custom function, processing result data before the `callback` function called.
Return an processed array, or process the passed `data` array directly.
See [demo](/index.html#formatResult)
### formatAjaxError function(jqXHR, textStatus, errorThrown)
Provide a custom function, for rendering the error message.
```
formatAjaxError: function(jqXHR, textStatus, errorThrown){ ... }
```
### ajax object
Customized configuration for the built-in Ajax function. Must be parameter-compatible with `$.ajax`. Usuful for the asynchronous pagination.
Parameter | Type | Description
------------ | ------------- | ------------
type | string | The type of request to make (e.g. "POST", "GET", "PUT"); Default is `GET`.
dataType | string | Data type for the request. `xml`, `json`, `jsonp`, other formats supported by jQuery. Default is `json`.
data | object | By default, `pageNumber` and `pageSize` will be sent. If you need additional data to be sent to the server. set this option. For example: `{ ajax: { data: {dbType: 'oracle'} } }`.
cache | boolean | If set to `false`, it will force requested pages not to be cached by the browser. Default is `true`.
async | boolean | By default, all requests are sent asynchronously. If you need synchronous requests, set this option to `false`. Default is `true`.
beforeSend | function | A pre-request callback function that can be used to modify the jqXHR object before it is sent. Returning false in the beforeSend function will cancel the request.
For more info on the parameters, refer to the [JQuery API Documentation](http://api.jquery.com/jquery.ajax/).
### triggerPagingOnInit boolean (default `true`)
Determines whether to trigger default pagination at initialization.
in some cases, you may load the content of the first page with AJAX and the content already showed before you initialize the pagination, you should set this option to `false`.
There are anthor usage, load the content of the second page by default, for example:
triggerPagingOnInit: true,
pageNum: 2
### hideWhenLessThanOnePage boolean (default `false`)
Determines whether to hide pagination when less than one page.
### inlineStyle boolean (default `true`)
Determines whether to use inline styles.
Pagination comes with style content, by default, the style content will be inserted in an `style` element to the `head` element.
If you think the use of the `link` would be better, you can set this option to `false` to prevent insertion behavior, and references your css file to the `link` element.
The default styles: [pagination.css](../dist/2.0.6/pagination.css) [pagination.less](../dist/2.0.6/pagination.less), but you can easily write these styles to apply your own.
Note, make sure that use `pagination-with-styles.js` before set this option.
Note, this will not be supported from v2.0.6, please use Link to import css.
# Methods
After Pagination is constructed, you can modify the behavior using the available public methods.
```
var container = $('#example1');
container.pagination({ ... });
container.pagination('previous');
```
### previous
Go to the previous page.
### next
Go to the next page.
### go
Go to the custom page. There is 2 ways:
container.pagination('go', 8)
container.pagination(8)
A custom callback function is also supported, for example:
container.pagination('go', 8, function(data, pagination){
// template method of yourself
})
Note, after set a custom function, will no longer call the default `callback` function.
### disable
Disables the pagination.
Note: before the asynchronous pagination request sent, pagination will automatically call this method, and automatically call `enable` method to enables the pagination after the request was completed successfully.
### enable
Enables the pagination.
### show
Show the pagination.
### hide
Hide the pagination.
### destroy
Destroy the pagination instance.
### getSelectedPageNum number
Get selected page number.
### getTotalPage number
Get total page.
### getSelectedPageData array
Get selected page data.
### isDisabled function
Whether pagination was be disabled.
# [Events](id:events)
Pagination events are the common interface that function in 2 ways: as callbacks and as plugin hooks.
Using events as callbacks:
```
var container = $('#example1');
container.pagination({
afterRender: function(){
// function body
}
});
```
Using events as plugin hooks:
```
var container = $('#example2');
container.pagination({
dataSource: [1, 2, 3],
pageSize: 1
});
container.addHook('afterRender', function(){
// function body
});
```
Note, the hook can be added before Pagination initialized, can also be added after Pagination initialized.
### beforeInit function
Callback fired before Pagination instance initialized. Return `false` will stop the initialization.
### beforeRender function
Callback fired before Pagination bar is rendered. Parameters:
`isForced` is `true` if rendering was triggered by a paging; or `false` if rendering was triggered by Pagination initialization.
### beforePaging function
Callback fired before a paging was triggered.
### beforeDestroy function
Callback fired before pagination instance was destroyed.
### beforeDisable function
Callback fired before pagination was disabled.
### beforeEnable function
Callback fired before pagination was enabled.
### beforePreviousOnClick function
Callback fired before 'previous' clicked.
### beforePageOnClick function
Callback fired before page number clicked.
### beforeNextOnClick function
Callback fired before 'next' clicked.
### beforeGoInputOnEnter function
Callback fired before 'Go' input Enter pressed.
### beforeGoButtonOnClick function
Callback fired before 'Go' button clicked.
### afterInit function
Callback fired after Pagination instance is initialized.
### afterRender function
Callback fired after Pagination bar is rendered. Parameters:
`isForced` is `true` if rendering was triggered by a paging; or `false` if rendering was triggered by Pagination initialization.
### afterPaging function
Callback fired after a paging was triggered.
### afterDestroy function
Callback fired after pagination instance was destroyed.
### afterDisable function
Callback fired after pagination was disabled.
### afterEnable function
Callback fired after pagination was enabled.
### afterPreviousOnClick function
Callback fired after 'previous' clicked.
### afterPageOnClick function
Callback fired after page number clicked.
### afterNextOnClick function
Callback fired after 'next' clicked.
### afterGoInputOnEnter function
Callback fired after 'Go' input Enter pressed.
### afterGoButtonOnClick function
Callback fired after 'Go' button clicked.
### afterIsFirstPage function
Callback fired after the selected page number was the first.
### afterIsLastPage function
Callback fired after the selected page number was the last.
# Skin
Pagination comes with 5 sets of default skins, but you can fully customize your own skin.
The blue skin, for example, it can be used:
className: 'paginationjs-theme-blue'
The small blue skin:
className: 'paginationjs-theme-blue paginationjs-small'
The big blue skin:
className: 'paginationjs-theme-blue paginationjs-big'
If you need a custom style, you can add CSS class `custom-paginationjs`.
# Configuring Defaults
Pagination exposes its default options via the `$.fn.pagination.defaults` object. Properties changed in this object (same properties configurable through the constructor) will take effect for every instance created after the change.
For example:
```
$.extend($.fn.pagination.defaults, {
pageSize: 20
})
```
After the change, all the new pagination instances's `pageSize` will be set to 20.
---
[Help improve these docs. Open an issue or pull request.](https://github.com/superRaytin/paginationjs/issues)