gulp-collection
v0.3.2
Published
Gulp plugin to group vinyl files into a collection and create new vinyl files using pagination and permalinks.
Downloads
7
Readme
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
License
Copyright © 2016, Brian Woodward. Released under the MIT license.
This file was generated by verb, v0.9.0, on August 02, 2016.