Permalink
Browse files

feat(pagination-nav): New navigation pagination component (#816)

* feat(pagination-nav): New navigation based cpagination

* [pagination-nav] include new component

* [pagination-nav] ESLint

* [pagination-nav] ESLint

* [pagination-nav] ESLint

* [pagination-nav] demo files

* Create demo.css

* Create demo.details

* Create demo.html

* Create pagination-nav.js

* Create README.md

* Create meta.json

* Create index.js

* Update demo.html

* [pagination-nav] remove aria-controls

* [pagination-nav] docs update

* [pagination] minor docs update

* Typo corrections

* Typo corrections

* Update pagination-nav.vue

* Add pagination-nav doc page into doc tree

* More typos corrections

* [pagination-nav] Introduce link-gen prop

Allow user to generate their own HREF string or TO object by specifying a function via `link-gen` property.

The link-gen function is passed a single argument which is the page number

* ESLint

* ESLint

* document link-gen function prop

* Typo change and wrong variable fix

* tests directory name change

* Add example of using an array to generate page links

* Create pagination-nav.js

Initial test file

* [pagination-nav] allow custom page button content

Allow user to render custom content (non-html) for page link buttons

added new prop `page-gen` which accepts a function reference.  The function will be passed the page number (indexed starting from 1), and should return a string (html not supported).  If no page-gen function is provided then default content is the page number.

* [pagination-nav] Updated docs
  • Loading branch information...
tmorehouse committed Aug 12, 2017
1 parent 8c172c1 commit 3a4272cc04a6b0f2291d10d09d6877b3ba3bfc30
@@ -26,6 +26,7 @@ export default {
'nav': require('./nav').default,
'navbar': require('./navbar').default,
'pagination': require('./pagination').default,
'pagination-nav': require('./pagination-nav').default,
'popover': require('./popover').default,
'progress': require('./progress').default,
'table': require('./table').default,
@@ -0,0 +1,212 @@
# Pagination Navigation
> Quick first, previous, next, last, and page buttons for pagination based navigation, supporting
regular links or router links.
```html
<template>
<div>
<h6>Default</h6>
<b-pagination-nav base-url="#" :number-of-pages="10" v-model="currentPage" />
<h6 class="mt-4">With link generator function</h6>
<b-pagination-nav link-gen="linkGen" :number-of-pages="10" v-model="currentPage" />
<br>
<div class="mt-4">currentPage: {{currentPage}}</div>
</div>
</template>
<script>
export default {
data: {
currentPage: 1
},
methods: {
linkGen(pageNum) {
return '#page/' + pageNum + '/foobar';
}
}
}
</script>
<!-- pagination-1.vue -->
```
`<b-pagination-nav>` is a custom input component that provides navigational
pagination. The current page should be set via the `value` prop (or `v-model`),
and the total number of pages set with `number-of-pages`. Page numbers are indexed
from 1 through `number-of-pages`.
### Current page
You should **always** set the current page number by setting the prop `value` (or
using `v-model`) to ensure that correct active page number is highlighted.
### Link generation
By default, `<b-pagination-nav>` generates plain link tags, setting the HREF attribute
to `base-url` concatenated with the page number. The `base-url` prop defaults to '/'.
#### Router links
To generate page links as [`<router link>`](https://router.vuejs.org/en/api/router-link.html)
components, set the `use-router` prop. The HREF will then become the `to` prop of
the router link.
#### Link Generator function
If you need finer grained control over the generated link URLs or `<router-link>` `to` props,
you may set the `link-gen` prop to a function reference that accepts one argument which
is a page number. The `link-gen` function should return either a string (for HREF) or a
router `to` object. If the returned value is an object, then a router-link will always
be generated. If the return value is a string, a link is generated by default unless
the `use-router` prop is set.
```js
// For regular HREF (or string `to` prop if `use-router` is set)
linkGen(pageNum) {
return '/foo/page/' + pageNum
}
// Returning a router-link `to` object
linkGen(pageNum) {
return {
path: '/foo/page/' + pageNum
};
}
```
Using an array of links to generate pagination:
```html
<template>
<div>
<b-pagination-nav link-gen="linkGen" :number-of-pages="links.length" v-model="currentPage" />
<br>
<p>
Page #: {{ currentPage }}<br>
Page Link: {{ pageLink }}
</p>
</div>
</template>
<script>
export default {
data: {
currentPage: 1,
links: ['#foo','#bar', '#baz', '#faz']
},
computed: {
pageLink() {
return this.linkGen(this.currentPage);
}
},
methods: {
linkGen(pageNum) {
return this.links[pageNum - 1];
}
}
}
</script>
```
### Page number generation
By default, `<b-pagination-nav>` renders page numbers (1-N) in the page link
buttons. You can override this behaviour by supplying a function reference to
the `page-gen` property. The function reference should accept a single argument
which is a page number (1-N). The `page-gen` function should return a string.
Note HTML strings are currenly not supported.
### Customizing
`<b-pagination-nav>` supports several props that allow you to customize the appearance.
| Prop | Description
| ---- | -----------
| `limit` | Limit the maximum number of displayed page buttons (including ellipsis if present, and excluding first/prev/next/last buttons)
| `number-of-pages` | The total number of pages
| `first-text` | The "goto first page" button text (html supported)
| `prev-text` | The "goto previous page" button text (html supported)
| `next-text` | The "goto next page" button text (html supported)
| `last-text` | The "goto last page" button text (html supported)
| `ellipsis-text` | the `...` indicator text (html supported)
| `hide-ellipsis` | never show ellipsis indicators
| `hide-goto-end-buttons` | never display goto first/last buttons
Ellipsis indicator(s) will only be ever shown at the front and/or end of
the page number buttons. For `limit` values less than or equal to `3`, the ellipsis
indicator(s) will never be shown for practical display reasons.
### Alignment
By default the pagination component is left aligned. Change the alignment to
`center` or `right` (`right` is an alias for `end`) by setting the prop
`align` to the appropriate value.
```html
<template>
<div>
<h6>Left alignment (default)</h6>
<b-pagination-nav :number-of-pages="10" base-url="#" v-model="currentPage" />
<br>
<h6>Center alignment</h6>
<b-pagination-nav align="center" :number-of-pages="10" base-url="#" v-model="currentPage" />
<br>
<h6>Right (end) alignment</h6>
<b-pagination-nav align="right" :number-of-pages="10" base-url="#" v-model="currentPage" />
<br>
<div>currentPage: {{currentPage}}</div>
</div>
</template>
<script>
export default {
data: {
currentPage: 1
}
}
</script>
<!-- pagination-2.vue -->
```
### Small screen support (`xs`)
On smaller screens (i.e. mobile), some of the `<b-pagination>` buttons will be hidden to
minimize the potential of the pagination interface wrapping onto multiple lines:
- The ellipsis indicators will be hidden on screens `xs` and smaller.
- Page number buttons will be limited to a maximum of 3 visible on `xs` screens and smaller.
This ensures that no more than 3 page number buttons are visible,
along with the goto _first_, _prev_, _next_, and _last_ buttons.
### Accessibility
The `<b-pagination>` component provides many features to support assistive technology users,
such as `aria-` attributes and keyboard navigation.
#### ARIA labels:
`<b-pagination>` provides various `*-label-*` props which are used to set the `aria-label`
attributes on the various elements within the component, which will help users of
assistive technology.
| Prop | `aria-label` content default
| ---- | -----------
| `label-first-page` | "Go to first page"
| `label-prev-page` | "Go to previous page"
| `label-next-page` | "Go to next page"
| `label-last-page` | "Go to last page"
| `label-page` | "Go to page", appended with the page number
| `aria-label` | "Pagination", applied to the outer pagination container
#### Keyboard navigtion support:
`<b-pagination>` supports keyboard navigation out of the box.
- Tabbing into the pagination component will auto-focus the current page button
- <kbd>LEFT</kbd> and <kbd>RIGHT</kbd> arrow keys will focus the previous and next buttons in the page
list, respectively, and <kbd>ENTER</kbd> or <kbd>SPACE</kbd> keys will select (click) the focused page button
### See also
For pagination control of a component (such as `<b-table>`), use the
[`<b-pagination>`](./pagination) component instead.
@@ -0,0 +1,4 @@
import meta from './meta.json';
import readme from './README.md';
export default {meta, readme};
@@ -0,0 +1,4 @@
{
"title": "Pagination Navigation",
"component": "bPaginationNav"
}
@@ -43,7 +43,7 @@ values for `total-rows` and `per-page`.
### Customizing
`<b-pagination>` supports several props that allow you to customize the apperance.
`<b-pagination>` supports several props that allow you to customize the appearance.
| Prop | Description
| ---- | -----------
@@ -117,7 +117,7 @@ The `<b-pagination>` component provides many features to support assistive techn
such as `aria-` attributes and keyboard navigation.
#### `aria-controls`:
Whan pagination is controling anohter component on the page (such as `<b-table>`), set
When pagination is controling another component on the page (such as `<b-table>`), set
the `aria-controls` prop to the `id` of the element it is controling. This will help
non-sighted users know what component is being updated/controlled.
@@ -136,7 +136,7 @@ assistive technology.
| `label-page` | "Goto page", appended with the page number
| `aria-label` | "Pagination", applied to the outer pagination container
#### Keyboard navigtion support:
#### Keyboard navigation support:
`<b-pagination>` supports keyboard navigation out of the box.
- Tabbing into the pagination component will autofocus the current page button
- <kbd>LEFT</kbd> and <kbd>RIGHT</kbd> arrow keys will focus the previous and next buttons in the page
@@ -150,3 +150,6 @@ list, respectively, and <kbd>ENTER</kbd> or <kbd>SPACE</kbd> keys will select (c
Both events provide the single argument of the current page number (starting from 1)
### See Also
For navigation based pagination, please see the [`<b-pagination-nav>`](./pagination-nav)
component.
@@ -0,0 +1,4 @@
#app {
padding: 20px;
height: 400px;
}
@@ -0,0 +1,16 @@
/*
---
name: Pagination-Nav - BootstrapVue
description: https://bootstrap-vue.github.io/docs/components/pagination-nav
authors:
- Pooya Parsa
- Troy Morehouse
resources:
- https://unpkg.com/bootstrap@next/dist/css/bootstrap.min.css
- https://unpkg.com/bootstrap-vue@latest/dist/bootstrap-vue.css
- https://unpkg.com/vue@latest/dist/vue.min.js
- https://unpkg.com/tether@latest/dist/js/tether.min.js
- https://unpkg.com/bootstrap-vue@latest/dist/bootstrap-vue.js
js_wrap: l
...
*/
@@ -0,0 +1,8 @@
<div id="app">
<div>
<h6>Default</h6>
<b-pagination-nav number-of-pages="10" base-url="#" v-model="currentPage" />
<br>
<div>currentPage: {{currentPage}}</div>
</div>
</div>
@@ -0,0 +1,6 @@
window.app = new Vue({
el: '#app',
data: {
currentPage: 1
}
});
@@ -39,6 +39,7 @@ import bNavbarBrand from './navbar-brand.vue';
import bNavText from './nav-text.vue';
import bNavForm from './nav-form.vue';
import bPagination from './pagination.vue';
import bPaginationNav from './pagination-nav.vue';
import bPopover from './popover.vue';
import bProgress from './progress.vue';
import bTable from './table.vue';
@@ -86,6 +87,7 @@ export {
bNavText,
bNavForm,
bPagination,
bPaginationNav,
bPopover,
bProgress,
bTable,
Oops, something went wrong.

0 comments on commit 3a4272c

Please sign in to comment.