vendor/mixitup-pagination
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial version

Browse Source
This commit is contained in:
Pascal Martineau
2018-01-17 14:09:34 -05:00
commit fa05241a63
52 changed files with 7254 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

629
docs/mixitup.Config.md Normal file
View File

@@ -0,0 +1,629 @@
# mixitup.Config
## Overview
The MixItUp configuration object is extended with the following properties
relating to the Pagination extension.
For the full list of configuration options, please refer to the MixItUp
core documentation.
### Contents
- [callbacks](#callbacks)
- [classNames](#classNames)
- [load](#load)
- [pagination](#pagination)
- [render](#render)
- [selectors](#selectors)
- [templates](#templates)
<h2 id="callbacks">callbacks</h2>
A group of optional callback functions to be invoked at various
points within the lifecycle of a mixer operation.
### onPaginateStart
A callback function invoked whenever a pagination operation starts.
This function is equivalent to `onMixStart`, and is invoked immediately
after it with the same arguments. Unlike `onMixStart` however, it will
not be invoked for filter or sort operations.
|Type | Default
|--- | ---
|`function`| `null`
### onPaginateStart
A callback function invoked whenever a pagination operation ends.
This function is equivalent to `onMixEnd`, and is invoked immediately
after it with the same arguments. Unlike `onMixEnd` however, it will
not be invoked for filter or sort operations.
|Type | Default
|--- | ---
|`function`| `null`
<h2 id="classNames">classNames</h2>
A group of properties defining the output and structure of class names programmatically
added to controls and containers to reflect the state of the mixer.
### elementPager
The "element" portion of the class name added to pager controls.
|Type | Default
|--- | ---
|`string`| `'control'`
###### Example: changing the `config.classNames.elementPager` value
```js
// Change from the default value of 'control' to 'pager'
var mixer = mixitup(containerEl, {
classNames: {
elementPager: 'pager'
}
});
// Base pager output: "mixitup-pager"
```
### elementPageList
The "element" portion of the class name added to the page list element, when it is
in its disabled state.
The page list element is the containing element in which pagers are rendered.
|Type | Default
|--- | ---
|`string`| `'page-list'`
###### Example: changing the `config.classNames.elementPageList` value
```js
// Change from the default value of 'page-list' to 'pagination-links'
var mixer = mixitup(containerEl, {
classNames: {
elementPageList: 'pagination-links'
}
});
// Disabled page-list output: "mixitup-pagination-links-disabled"
```
### elementPageStats
The "element" portion of the class name added to the page stats element, when it is
in its disabled state.
The page stats element is the containing element in which information about the
current page and total number of pages is rendered.
|Type | Default
|--- | ---
|`string`| `'page-stats'`
###### Example: changing the `config.classNames.elementPageStats` value
```js
// Change from the default value of 'page-stats' to 'pagination-info'
var mixer = mixitup(containerEl, {
classNames: {
elementPageList: 'pagination-info'
}
});
// Disabled page-list output: "mixitup-pagination-info-disabled"
```
### modifierFirst
The "modifier" portion of the class name added to the first pager in the list of pager controls.
|Type | Default
|--- | ---
|`string`| `'first'`
### modifierLast
The "modifier" portion of the class name added to the last pager in the list of pager controls.
|Type | Default
|--- | ---
|`string`| `'last'`
### modifierLast
The "modifier" portion of the class name added to the previous pager in the list of pager controls.
|Type | Default
|--- | ---
|`string`| `'prev'`
### modifierNext
The "modifier" portion of the class name added to the next pager in the list of pager controls.
|Type | Default
|--- | ---
|`string`| `'next'`
### modifierTruncationMarker
The "modifier" portion of the class name added to truncation markers in the list of pager controls.
|Type | Default
|--- | ---
|`string`| `'truncation-marker'`
<h2 id="load">load</h2>
A group of properties defining the initial state of the mixer on load (instantiation).
### page
An integer defining the starting page on load, if a page limit is active.
|Type | Default
|--- | ---
|`number`| `1`
###### Example: Defining a start page other than 1 to be applied on load
```js
// The mixer will show page 3 on load, with 8 items per page.
var mixer = mixitup(containerEl, {
pagination: {
limit: 8
},
load: {
page: 3
}
});
```
<h2 id="pagination">pagination</h2>
A group of properties defining the mixer's pagination behavior.
### generatePageList
A boolean dictating whether or not MixItUp should render a list of pager controls.
If you wish to control pagination functionality via the API, or your own UI, this can be set to `false`.
In order for this functionality to work, you must provide MixItUp with a `pageList`
element matching the selector defined in `selectors.pageList`. Pager controls will be
rendered inside this element as per the templates defined for the `templates.pager`
and related configuration options, or if set, a custom render
function supplied to the `render.pager` configuration option.
|Type | Default
|--- | ---
|`boolean`| `true`
###### Example: Disabling the rendering of the built-in "page list" UI
```js
var mixer = mixitup(containerEl, {
pagination: {
limit: 8,
generatePageList: false
}
});
```
### generatePageStats
A boolean dictating whether or not MixItUp should render a stats about the
current page (e.g. "1 to 4 of 16").
In order for this functionality to work, you must provide MixItUp with a `pageStats`
element matching the selector defined in `selectors.pageStats`. Page stats content will
be rendered inside this element as per the templates defined for the `templates.pageStats`
and `templates.pageStatsSingle` configuration options, or if set, a custom render
function supplied to the `render.pageStats` configuration option.
|Type | Default
|--- | ---
|`boolean`| `true`
###### Example: Disabling the rendering of the built-in "page stats" UI
```js
var mixer = mixitup(containerEl, {
pagination: {
limit: 8,
generatePageStats: false
}
});
```
### maintainActivePage
A boolean dictating whether or not to maintain the active page when switching
from filter to filter.
By default, MixItUp will attempt to maintain the active page or its highest
equivalent in the new collection of matching targets (e.g. page 3 would become
page 2 if there are not enough targets in the new collection), but by setting
this option to `false`, changing the active filter will always cause the mixer
to revert to page one of the new collection.
|Type | Default
|--- | ---
|`boolean`| `true`
###### Example: Ensuring that the mixer reverts to page one when filtered
```js
var mixer = mixitup(containerEl, {
pagination: {
limit: 8,
maintainActivePage: false
}
});
```
### loop
A boolean dictating whether or not to allow "looping" of the built-in previous
and next pagination controls.
By default, when on the first page, the "previous" button will be disabled,
and when on the last page, the "next" button will be disabled. By setting
this option to `true`, the user may loop from the first to last page and
vice-versa.
|Type | Default
|--- | ---
|`boolean`| `false`
###### Example: Allowing prev/next controls to "loop" through pages
```js
var mixer = mixitup(containerEl, {
pagination: {
limit: 8,
loop: true
}
});
```
### hidePageListIfSinglePage
A boolean dictating whether or not to prevent rendering of the built-in
"page list" UI if the matching collection of targets has only enough content
for one page.
|Type | Default
|--- | ---
|`boolean`| `false`
###### Example: Hiding the page list UI if only one page
```js
var mixer = mixitup(containerEl, {
pagination: {
limit: 8,
hidePageListIfSinglePage: true
}
});
```
### hidePageStatsIfSinglePage
A boolean dictating whether or not to prevent rendering of the built-in
"page stats" UI if the matching collection of targets has only enough content
for one page.
|Type | Default
|--- | ---
|`boolean`| `false`
###### Example: Hiding the page stats UI if only one page
```js
var mixer = mixitup(containerEl, {
pagination: {
limit: 8,
hidePageStatsIfSinglePage: true
}
});
```
### limit
A number defining the maximum number of items per page.
By default, this is set to `-1` and pagination is effectively
disabled. By setting this to any number greater than 0, pagination
will be applied to the mixers targets, effectively activating the
extension.
|Type | Default
|--- | ---
|`number`| `-1`
###### Example: Activating the pagination extension by defining a valid limit
```js
var mixer = mixitup(containerEl, {
pagination: {
limit: 8
}
});
```
### maxPagers
A number dictating the maximum number of individual pager controls to render before
truncating the list (e.g. adding an ellipses between non-consecutive pagers).
The minimum value permitted for this option is 5, which ensures
there will always be at least a first, last, and two padding pagers, in addition
to the pager representing the currently active page.
|Type | Default
|--- | ---
|`number`| `5`
<h2 id="render">render</h2>
A group of optional render functions for creating and updating elements.
### pager
A function returning an HTML string representing a single pager control element.
By default, MixItUp will render pager controls using its own internal renderer
and templates (see `templates.pager`), but you may override this functionality by
providing your own render function here instead. All pager elements must have a
data-page element indicating the action of the control.
The function receives an object containing all neccessary information
about the pager as its first parameter.
|Type | Default
|--- | ---
|`function`| `'null'`
### pageStats
A function returning an HTML string forming the contents of the "page stats" element.
By default, MixItUp will render page stats using its own internal renderer
and templates (see `templates.pageStats`), but you may override this functionality by
providing your own render function here instead.
The function receives an object containing all neccessary information
about the current page and total pages as its first parameter.
|Type | Default
|--- | ---
|`function`| `'null'`
<h2 id="selectors">selectors</h2>
A group of properties defining the selectors used to query elements within a mixitup container.
### pageList
A selector string used to query the page list element.
Depending on the value of `controls.scope`, MixItUp will either query the
entire document for the page list element, or just the container.
|Type | Default
|--- | ---
|`string`| `'.mixitup-page-list'`
### pageStats
A selector string used to query the page stats element.
Depending on the value of `controls.scope`, MixItUp will either query the
entire document for the page stats element, or just the container.
|Type | Default
|--- | ---
|`string`| `'.mixitup-page-stats'`
<h2 id="templates">templates</h2>
A group of template strings used to render pager controls and page stats elements.
### pager
|Type | Default
|--- | ---
|`string`| `'<button type="button" class="${classNames}" data-page="${pageNumber}">${pageNumber}</button>'`
### pagerPrev
|Type | Default
|--- | ---
|`string`| `'<button type="button" class="${classNames}" data-page="prev">&laquo;</button>'`
### pagerNext
|Type | Default
|--- | ---
|`string`| `'<button type="button" class="${classNames}" data-page="next">&raquo;</button>'`
### pagerTruncationMarker
|Type | Default
|--- | ---
|`string`| `'<span class="${classNames}">&hellip;</span>'`
### pageStats
|Type | Default
|--- | ---
|`string`| `'${startPageAt} to ${endPageAt} of ${totalTargets}'`
### pageStatsSingle
|Type | Default
|--- | ---
|`string`| `'${startPageAt} of ${totalTargets}'`
### pageStatsFail
|Type | Default
|--- | ---
|`string`| `'None found'`

142
docs/mixitup.Mixer.md Normal file
View File

@@ -0,0 +1,142 @@
# mixitup.Mixer
## Overview
The mixitup.Mixer class is extended with the following methods relating to
the Pagination extension.
For the full list of methods, please refer to the MixItUp core documentation.
### Contents
- [paginate()](#paginate)
- [nextPage()](#nextPage)
- [prevPage()](#prevPage)
<h3 id="paginate">paginate()</h3>
`.paginate(page [, animate] [, callback])`
Changes the current page and/or the current page limit.
| |Type | Name | Description
|---|--- | --- | ---
|Param |`number, string, object, HTMLElement` | `page` | A page number, string (`'next'`, `'prev'`), HTML element reference, or command object.
|Param |`boolean` | `[animate]` | An optional boolean dictating whether the operation should animate, or occur syncronously with no animation. `true` by default.
|Param |`function` | `[callback]` | An optional callback function to be invoked after the operation has completed.
|Returns |`Promise.<mixitup.State>` | A promise resolving with the current state object.
###### Example 1: Changing the active page
```js
console.log(mixer.getState().activePagination.page); // 1
mixer.paginate(2)
.then(function(state) {
console.log(mixer.getState().activePagination.page === 2); // true
});
```
###### Example 2: Progressing to the next page
```js
console.log(mixer.getState().activePagination.page); // 1
mixer.paginate('next')
.then(function(state) {
console.log(mixer.getState().activePagination.page === 2); // true
});
```
###### Example 3: Starting a page from an abitrary "anchor" element
```js
var anchorEl = mixer.getState().show[3];
mixer.paginate(anchorEl)
.then(function(state) {
console.log(mixer.getState().activePagination.anchor === anchorEl); // true
console.log(mixer.getState().show[0] === anchorEl); // true
});
```
###### Example 4: Changing the page limit
```js
var anchorEl = mixer.getState().show[3];
console.log(mixer.getState().activePagination.limit); // 8
mixer.paginate({
limit: 4
})
.then(function(state) {
console.log(mixer.getState().activePagination.limit === 4); // true
});
```
###### Example 5: Changing the active page and page limit
```js
mixer.paginate({
limit: 4,
page: 2
})
.then(function(state) {
console.log(mixer.getState().activePagination.page === 2); // true
console.log(mixer.getState().activePagination.limit === 4); // true
});
```
<h3 id="nextPage">nextPage()</h3>
`.nextPage()`
A shorthand for `.paginate('next')`. Moves to the next page.
| |Type | Name | Description
|---|--- | --- | ---
|Returns |`Promise.<mixitup.State>` | A promise resolving with the current state object.
###### Example: Moving to the next page
```js
console.log(mixer.getState().activePagination.page); // 1
mixer.nextPage()
.then(function(state) {
console.log(mixer.getState().activePagination.page === 2); // true
});
```
<h3 id="prevPage">prevPage()</h3>
`.prevPage()`
A shorthand for `.paginate('prev')`. Moves to the previous page.
| |Type | Name | Description
|---|--- | --- | ---
|Returns |`Promise.<mixitup.State>` | A promise resolving with the current state object.
###### Example: Moving to the previous page
```js
console.log(mixer.getState().activePagination.page); // 5
mixer.prevPage()
.then(function(state) {
console.log(mixer.getState().activePagination.page === 4); // true
});
```

42
docs/mixitup.State.md Normal file
View File

@@ -0,0 +1,42 @@
# mixitup.State
## Overview
`mixitup.State` objects expose various pieces of data detailing the state of
a MixItUp instance. They are provided at the start and end of any operation via
callbacks and events, with the most recent state stored between operations
for retrieval at any time via the API.
### Contents
- [activePagination](#activePagination)
- [totalPages](#totalPages)
<h3 id="activePagination">activePagination</h3>
The currently active pagination command as set by a control click or API call.
|Type | Default
|--- | ---
|`mixitup.CommandPagination`| `null`
<h3 id="totalPages">totalPages</h3>
The total number of pages produced as a combination of the current page
limit and active filter.
|Type | Default
|--- | ---
|`number`| `-1`

11
docs/mixitup.md Normal file
View File

@@ -0,0 +1,11 @@
#()
| |Type | Name | Description
|---|--- | --- | ---
|Returns |