https://github.com/assemble/assemble-pager
Assemble plugin that adds prev/next pager information to the context, for a specific collection, specific files or all files in a stream.
https://github.com/assemble/assemble-pager
assemble collections pager pages paginate pagination plugin
Last synced: 6 months ago
JSON representation
Assemble plugin that adds prev/next pager information to the context, for a specific collection, specific files or all files in a stream.
- Host: GitHub
- URL: https://github.com/assemble/assemble-pager
- Owner: assemble
- License: mit
- Created: 2017-02-09T21:15:52.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2017-02-21T01:02:08.000Z (over 8 years ago)
- Last Synced: 2024-10-01T09:11:19.597Z (about 1 year ago)
- Topics: assemble, collections, pager, pages, paginate, pagination, plugin
- Language: JavaScript
- Homepage: https://github.com/assemble/assemble-pager
- Size: 16.6 KB
- Stars: 4
- Watchers: 6
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: .github/contributing.md
- License: LICENSE
Awesome Lists containing this project
README
# assemble-pager [](https://www.npmjs.com/package/assemble-pager) [](https://npmjs.org/package/assemble-pager) [](https://npmjs.org/package/assemble-pager) [](https://travis-ci.org/assemble/assemble-pager)
> Assemble plugin that adds prev/next pager information to the context.
## Table of Contents
- [Install](#install)
- [Usage](#usage)
- [Specify a collection](#specify-a-collection)
- [Excluding files](#excluding-files)
- [Template usage](#template-usage)
* [Helpers](#helpers)
* [Example usage](#example-usage)
* [Troubleshooting](#troubleshooting)
- [How it works](#how-it-works)
- [About](#about)
_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_
## Install
Install with [npm](https://www.npmjs.com/):
```sh
$ npm install --save assemble-pager
```
Adds data to the context to enable creating pagers that work like this:
## Usage
```js
var assemble = require('assemble');
var pager = require('assemble-pager');
var app = assemble();
// register the plugin
app.use(pager());
app.task('site', function() {
return app.src('src/*.md')
.pipe(app.pager()) // then add "app.pager()" before "app.renderFile()"
.pipe(app.renderFile())
.pipe(app.dest('blog'));
});
```
When `app.pager()` is called, it adds the `pager` variable to the context so that it's available to all views in the collection being rendered.
## Specify a collection
```js
// only add paging to the "posts" collection
.pipe(app.pager({collection: 'posts'}))
```
## Excluding files
If you don't [specify a collection](#specify-a-collection), all files in the stream will be buffered and included. However, you can selectively exclude files by setting `file.data.pager` to `false`, either in another plugin, middleware, or by defining it on yaml front-matter.
**Examples**
```js
// plugin, defined before `app.pager()`
.pipe(through.obj(function(file, enc, next) {
file.data.pager = false;
next(null, file);
}))
// middleware
app.onLoad(/\.foo$/, function(file, next) {
file.data.pager = false;
next();
});
```
Or yaml front-matter
```handlebars
---
pager: false
---
This is a page that should be skipped by `app.pager()`
```
## Template usage
The `pager` variable is an object with the following properties:
* `pager.prev` **{Object}** - the previous view that was rendered. This is an actual view, so you can get any data you need from it (like `pager.prev.path` or `pager.prev.data.title`, etc)
* `pager.next` **{Object}** - the next view to be rendered. This is an actual view, so you can get any data you need from it (like `pager.next.path` or `pager.next.data.title`, etc)
* `pager.current` **{Object}** - the view that is currently being rendered
* `pager.first` **{Object}** - Returns the first file in the list
* `pager.last` **{Object}** - Returns the last file in the list
* `pager.isFirst` **{Boolean}** - returns true if the "current" file is the first to be rendered
* `pager.isLast` **{Boolean}** - returns true if the "current" file is the last to be rendered
* `pager.index` **{Number}** - the list index of the current file being rendered
### Helpers
Some helpers are included with this plugin. To use them, do the following:
```js
var pager = require('assemble-pager');
app.helpers(pager.helpers);
```
Which adds the following helpers:
* `relative`- calculates the relative path from file `A` to file `B` (e.g. "current" file to next or previous file)
* `ifFirst`- returns true if the current file being rendered is the first file
* `ifLast`- returns true if the current file being rendered is the last file
* `next`- used in `href=""`, returns either the relative path to the "next" file, or `#` if the current file being rendered is the last file
* `prev`- used in `href=""`, returns either the relative path to the "previous" file, or `#` if the current file being rendered is the first file
* `attr`- stringify the options hash arguments to HTML attributes. For example, you can use this to conditionally add a class for a disabled next/prev link: `{{ifFirst (attr class="disabled")}}`, or `{{ifLast (attr class="disabled")}}` etc.
**Overriding helpers**
Helpers are exposed as an object so that you can choose to register them if you want, and/or override them if necessary:
For example, this is how the included "relative" helper works:
```js
var relative = require('relative');
app.helper('relative', function(from, to) {
return relative(from.data.path, to.data.path);
});
```
### Example usage
Since `pager` is just another variable on the context, you can do anything you normally would with a variable in your handlebars templates.
```handlebars
Prev
```
Or you can create a block:
```handlebars
{{#pager}}
Prev
{{/pager}}
```
**Partials**
To simplify paging even more, you can define partials like the following:
```js
app.partial('prev', 'Prev');
app.partial('next', '\nNext');
app.partial('pager', '{{> prev }}\n{{> next }}');
```
### Troubleshooting
The easiest way to see how this works is to log out the `pager` variables, to see what's on the context. You can use the built-in `log` helper to do this:
```handlebars
{{log pager}}
```
## How it works
This is really all the plugin does, with the addition of error and options handling (a commented version is below). You can copy this and create your own plugin if you need to:
```js
function pagerPlugin() {
var list = new app.List({pager: true});
return through.obj(function(file, enc, next) {
list.addItem(file);
next();
}, function(cb) {
for (var i = 0; i < list.items.length; i++) {
this.push(item);
}
cb();
});
}
```
With comments:
```js
function pagerPlugin() {
// create a new assemble `List`. Lists are like collections,
// but the items are stored as an array, versus an object
var list = new app.List({pager: true});
return through.obj(function(file, enc, next) {
// add files to the list as they come through the stream
list.addItem(file);
// don't pass the file through, we'll do
// that in the flush function
next();
}, function(cb) {
// all of the files have now been buffered onto the
// `list.items` array. We can now loop over that array
// and push the items back into the stream (it's important
// for all the items to be buffered this way so that all
// items are available on the context before anything is
// rendered, or items will be missing)
for (var i = 0; i < list.items.length; i++) {
this.push(item); //<= push the item into the stream
}
cb();
});
}
```
## About
### Contributing
Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
Please read the [contributing guide](.github/contributing.md) for advice on opening issues, pull requests, and coding standards.
### Building docs
_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_
To generate the readme, run the following command:
```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```
### Running tests
Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
```sh
$ npm install && npm test
```
### Author
**Jon Schlinkert**
* [github/jonschlinkert](https://github.com/jonschlinkert)
* [twitter/jonschlinkert](https://twitter.com/jonschlinkert)
### License
Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert).
MIT
***
_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.4.2, on February 09, 2017._