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

• github/[e-mail]:vwochnik
• twitter/[e-mail]:vwochnik

License

Copyright (c) 2015 Vincent Wochnik
Released under the MIT license

---

This file was generated by verb-cli on April 18, 2015.