assemble-plugin-index
v0.3.3
Published
Template indexing plugin for Assemble.io.
Downloads
5
Maintainers
Readme
assemble-plugin-index
Template indexing plugin for Assemble.io.
Install with npm
npm i assemble-plugin-index --save-dev
Getting Started
In your assemblefile.js
, insert the following line immediately after you have require()
d assemble
:
var index = require('assemble-plugin-index')(assemble);
It is important that you pass the assemble
instance variable to the module for initialization.
Upon initialization, the module creates a new renderable index
collection within assemble
. Before using the plugin in the task pipeline, you have to specify a location where index
collections can be found:
assemble.indices('templates/indices/*.hbs');
Now, the plugin can be used within the task pipeline. The following example demonstrates the use of the index
plugin used within a task pipeline:
assemble.task('posts', function() {
assemble.src('templates/posts/*.hbs')
.pipe(index('posts', {pattern: 'index:num:', limit: 10}))
.pipe(assemble.dest('dist/'));
});
This will create dist/index.hbs
, dist/index1.hbs
, dist/index2.hbs
and so forth.
You can also specify options globally using the assemble
API:
assemble.option('index', {limit: 10});
Visit the plugin docs for more info or for help getting started.
API
index
- {String}: Identifier of an
index
template. - {Object}: Options for the generation of templates.
- {Object}: Options for rendering templates.
Plugin function for the generation of index templates.
Options
limit
Type: Number
Default: 10
Maximum collection items per index page.
pattern
Type: String
, 'Function'
Default: Template name with attached page number
File naming pattern with attached page number and without file extension. By default, files are named by the index template's name plus an additional page number for successive pages.
The string :num:
is replaced with the page number or removed for
the first page.
When a function is given, it is called for every page generated and must return a string without file extension. The function is called with the page number, index
, and an array of items
that are going to be added to the page.
filter
Type: String
, Array
, Function
Default: undefined
The default filter takes only the data
object of each template in the pipeline excluding src
and dest
properties. If these properties are needed, they need to be explicitly specified.
When a string is given, only one property named by the specified string within the data
object will be filtered.
When an array is given, all properties specified in the array within the data
object will be filtered.
When a function is given, the function will be called with a file
argument representing the currently processing vinyl
file. The function must immediately return the filtered result as an Object
containing filtered properties.
process
Type: Array
, Function
Default: function(items, cb) { return cb(null, items); }
A single or an array of chained post-processing functions. Each function must call the callback(error, items)
when finished. If an error
occurred, the chain is broken. Otherwise error
must be null
and items
must contain all items to index.
Context
The templating context contains the following variables which can be used for the generation of the index page.
items
Type: Array
An array containing all items available for this particular index page. Each item
contains the following properties:
- the relative
url
to the template - properties generated by the used
filter
pagination
Type: Object
An object describing the state of the index pagination as the following code listing shows:
{
first: 'index.html',
prev: 'index2.html',
current: 'index3.html',
next: undefined,
last: 'index3.html',
pages: ['index.html', 'index1.html', 'index2.html', 'index3.html'],
isFirst: false,
isLast: true
}
first
Type: String
Relative path of the first index page in a collection of index pages.
prev
Type: String
Relative path of the previous index page in a collection of index pages.
next
Type: String
Relative path of the next index page in a collection of index pages.
last
Type: String
Relative path of the last index page in a collection of index pages.
pages
Type: Array
An array of strings of relative paths of all index pages.
isFirst
Type: Boolean
Whether the current index page is the first index page of a collection of index pages.
isLast
Type: Boolean
Whether the current index page is the last index page of a collection of index pages.
Template
The following listing shows an example index
template:
<ul>
{{#each items}}
<li><a href="{{url}}">{{title}}</a></li>
{{/each}}
</ul>
{{#with pagination}}
<ul>
{{#if isFirst}}
<li><a>Prev</a></li>
{{else}}
<li><a href="{{prev}}">Prev</a></li>
{{/if}}
{{#each pages}}
{{#is this ../current}}
<li><a>{{@index}}</a></li>
{{else}}
<li><a href="{{this}}">{{@index}}</a></li>
{{/is}}
{{/each}}
{{#if isLast}}
<li><a>Next</a></li>
{{else}}
<li><a href="{{last}}">Next</a></li>
{{/if}}
</ul>
{{/with}}
Frequently Asked Questions
The file extensions of the pagination URLs don't match the actual file extension. How do I fix this?
This can be the case if you have configured a third-party plugin such as gulp-extname
to change file extensions.
Solution: Use the assemble
builtin {{replace}}
helper to replace file extensions. The following snippet shows a pagination with .html
extensions:
{{#with pagination}}
<ul>
{{#if isFirst}}
<li><a>Prev</a></li>
{{else}}
<li><a href="{{replace prev '.hbs' '.html'}}">Prev</a></li>
{{/if}}
{{#each pages}}
{{#is this ../current}}
<li><a>{{@index}}</a></li>
{{else}}
<li><a href="{{replace this '.hbs' '.html'}}">{{@index}}</a></li>
{{/is}}
{{/each}}
{{#if isLast}}
<li><a>Next</a></li>
{{else}}
<li><a href="{{replace last '.hbs' '.html'}}">Next</a></li>
{{/if}}
</ul>
{{/with}}
How do I sort items in the collection?
This is exactly what the postprocess
option is made for! Let's assume that you have a collection of blog posts that need to be sorted by their posted
property. When using a filter, do not forget to include the posted
property as well!
assemble.task('posts', function() {
assemble.src('templates/posts/*.hbs')
.pipe(index('posts', {
pattern: 'index:num:',
filter: ['title', 'posted', 'summary']
limit: 10,
process: [
function(items, cb) {
cb(null, items.sort(function(item1, item2) {
return item2.posted - item1.posted;
}));
}
]
}))
.pipe(assemble.dest('dist/'));
});
Authors
Vincent Wochnik
License
Copyright (c) 2015 Vincent Wochnik
Released under the MIT license
This file was generated by verb-cli on April 18, 2015.