gulp-collection

Gulp plugin to group vinyl files into a collection and create new vinyl files using pagination and permalinks.

Install

Install with npm:

$ npm install --save gulp-collection

Usage

This gulp plugin will group together a collection of files based on a property specified in the given permalinks pattern.

var gulp = require('gulp');
var File = require('vinyl');
var collection = require('gulp-collection');

gulp.task('default', function() {
  var listFile = new File({path: 'list.hbs', contents: new Buffer('Contents to use for listing all the tags')});
  var itemFile = new File({path: 'item.hbs', contents: new Buffer('Contents to use for individual tags')});

  return gulp.src('*.hbs')
    // uses `tags` or the property
    .pipe(collection(':tags/:tag.hbs', {list: list, item: item}))
    .pipe(gulp.dest('dist/'));
});

Files coming through the stream are expected to have a .data property. This is used when grouping to determine how the collection files are created. If your source files have front-matter, you can use gulp-gray-matter to parse the front-matter and add the .data property:

var gulp = require('gulp');
var matter = require('gulp-gray-matter');
var collection = require('gulp-collection');

gulp.task('default', function() {
  var listFile = new File({path: 'list.hbs', contents: new Buffer('Contents to use for listing all the tags')});
  var itemFile = new File({path: 'item.hbs', contents: new Buffer('Contents to use for individual tags')});

  return gulp.src('*.hbs')
    .pipe(matter())
    .pipe(collection(':tags/:tag.hbs', {list: list, item: item}))
    .pipe(gulp.dest('dist/'));
});

Options

The following options will affect how files are grouped and how new vinyl files are created from the grouped collections.

Group callback function

A groupFn may be passed on options that will be called after the files have been grouped into a collection:

var gulp = require('gulp');
var matter = require('gulp-gray-matter');
var collection = require('gulp-collection');

gulp.task('default', function() {
  return gulp.src('*.hbs')
    .pipe(matter())
    .pipe(collection(':tags/:tag.hbs', {
      groupFn: function(group) {
        console.log(group);
      }
    }))
    .pipe(gulp.dest('dist/'));
});

Template list and item files.

Once the files have been grouped, new files will be created for the groups based on the list and item options passed to collection().

An initial list file will be created with a data object containing a property matching the first :prop property in the permalink pattern. This property will contain the entire group object:

// <File tags.hbs>
{
  data: {
    tags: {
      foo: [<File one.hbs>, <File two.hbs>],
      bar: [<File one.hbs>, <File three.hbs>],
      baz: [<File two.hbs>, <File three.hbs>]
    }
  }
}

For each item on the group object, an item file will be created with a data object containing a property matching the second :prop property in the permalink pattern and an items property with array of files that are in that group:

// <File tags/foo.hbs>
{
  data: {
    tag: 'foo',
    items: [<File one.hbs>, <File two.hbs>]
  }
}
// <File tags/bar.hbs>
{
  data: {
    tag: 'bar',
    items: [<File one.hbs>, <File three.hbs>]
  }
}
// <File tags/baz.hbs>
{
  data: {
    tag: 'baz',
    items: [<File two.hbs>, <File three.hbs>]
  }
}

Pagination

Item files may be paginated using paginationator by specifying a paginate property on the options:

var gulp = require('gulp');
var matter = require('gulp-gray-matter');
var collection = require('gulp-collection');

gulp.task('default', function() {
  return gulp.src('*.hbs')
    .pipe(matter())
    .pipe(collection(':tags/:tag/page/:pager.idx/index.html', {
      paginate: {limit: 3}
    }))
    .pipe(gulp.dest('dist/'));
});

When the paginate option is specified, an item file will be created for each page of items contained in that item group. Also, pager property will be available for use in the permalink structure. The example above shows using pager.idx to make permalinks that will look something like:

// "foo" tag pages
<File tags/foo/page/0/index.html>
<File tags/foo/page/1/index.html>
<File tags/foo/page/2/index.html>

// "bar" tag pages
<File tags/bar/page/0/index.html>
<File tags/bar/page/1/index.html>
<File tags/bar/page/2/index.html>

// "baz" tag pages
<File tags/baz/page/0/index.html>
<File tags/baz/page/1/index.html>
<File tags/baz/page/2/index.html>

The data property on each page will contain information about that page and the items on that page.

// <File tags/foo/page/1/index.html>
{
  data: {
    tag: 'foo',
    idx: 1, // actual array index of page
    total: 3, // total pages for tag "foo"
    current: 2, // current page number (idx + 1)
    items: [<File three.hbs>, <File four.hbs>] // items on this page
    first: 1, // first page number
    last: 3, // last page number
    prev: 1, // previous page number (current - 1)
    next: 3 // next page number (current + 1)
  }
}

Custom vinyl file constructor

A custom vinyl file constructor may be passed on the File option. This will be used when creating the new vinyl files from the list and item options.

The following example will use a vinyl-item constructor, which extends vinyl with additional functionality.

(Note) list and item do not need to be a vinyl file. They just need to have path and contents properties.

var gulp = require('gulp');
var matter = require('gulp-gray-matter');
var collection = require('gulp-collection');
var VinylItem = require('vinyl-item');

gulp.task('default', function() {
  var listFile = new VinylItem({path: 'list.hbs', contents: new Buffer('Contents to use for listing all the tags')});
  var itemFile = new VinylItem({path: 'item.hbs', contents: new Buffer('Contents to use for individual tags')});

  return gulp.src('*.hbs')
    .pipe(matter())
    .pipe(collection(':tags/:tag.hbs', {
      File: VinylItem,
      list: listFile,
      item: itemFile
    }))
    .pipe(gulp.dest('dist/'));
});

Examples

gulpfile.js

The gulpfile.js example shows a simple use case using gulp-gray-matter.

Run the gulpfile example with the following commands:

$ cd examples
$ gulp

advanced.js

The advanced example shows using gulp to read in files, gulp-gray-matter to parse the front-matter and Handlebars to render the templates into html files. This example also shows the use of pagination to create multiple pages from a long list of items.

Run the advanced example with the following commands:

$ cd examples
$ gulp --gulpfile advanced.js

example.js

The example.js example file creates a lot of Vinyl files dynamically and randomly gives them categories and tags. The example streams the dynamically created files through the collection plugin to show how pagination works with a lot of files. This example does not do any file I/O and is run with node directly.

Run the example.js file with the following commands:

$ cd examples
$ node example.js

About

Related projects

• group-array: Group array of objects into lists. | homepage
• paginationator: Paginate an array into pages of items. | homepage
• permalinks: Adds permalink or URL routing/URL rewriting logic to any node.js project. Can be used in… more | homepage
• placeholders: Replace placeholder values in a file path. | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Building docs

(This document was generated by verb-generate-readme (a verb generator), please don't edit the readme directly. Any changes to the readme must be made in .verb.md.)

To generate the readme and API documentation with verb:

$ npm install -g verb verb-generate-readme && verb

Running tests

Install dev dependencies:

$ npm install -d && npm test

Author

Brian Woodward

• github/github.com
• twitter/github.com

License

Copyright © 2016, Brian Woodward. Released under the MIT license.

This file was generated by verb, v0.9.0, on August 02, 2016.