Gulp plugin to group vinyl files into a collection and create new vinyl files using pagination and permalinks.
npm install gulp-collectionGulp plugin to group vinyl files into a collection and create new vinyl files using pagination and permalinks.
Install with npm:
``sh`
$ npm install --save gulp-collection
This gulp plugin will group together a collection of files based on a property specified in the given permalinks pattern.
`js
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:
`js
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/'));
});
`
The following options will affect how files are grouped and how new vinyl files are created from the grouped collections.
A groupFn may be passed on options that will be called after the files have been grouped into a collection:
`js
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/'));
});
`
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:
`js`
//
{
data: {
tags: {
foo: [
bar: [
baz: [
}
}
}
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:
`js`
//
{
data: {
tag: 'foo',
items: [
}
}
//
{
data: {
tag: 'bar',
items: [
}
}
//
{
data: {
tag: 'baz',
items: [
}
}
Item files may be paginated using paginationator by specifying a paginate property on the options:
`js
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:
`js
// "foo" tag pages
// "bar" tag pages
// "baz" tag pages
`
The data property on each page will contain information about that page and the items on that page.
`js`
//
{
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: [
first: 1, // first page number
last: 3, // last page number
prev: 1, // previous page number (current - 1)
next: 3 // next page number (current + 1)
}
}
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.
`js
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/'));
});
`
_gulpfile.js_
The gulpfile.js example shows a simple use case using gulp-gray-matter.
Run the gulpfile example with the following commands:
`sh`
$ 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:
`sh`
$ 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:
`sh`
$ cd examples
$ node example.js
* 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
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
_(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:
`sh`
$ npm install -g verb verb-generate-readme && verb
Install dev dependencies:
`sh``
$ npm install -d && npm test
Brian Woodward
* github/github.com
* twitter/github.com
Copyright © 2016, Brian Woodward.
Released under the MIT license.
*
_This file was generated by verb, v0.9.0, on August 02, 2016._