gulp-group-array   

Gulp plugin to group vinyl files by properties on the vinyl file using group-array.

Install

Install with npm:

``sh
$ npm install --save gulp-group-array
`

Usage

`js
var groupArray = require('gulp-group-array');
`

API

$3

Group vinyl files by specified properties on the vinyl files. This uses group-array to do the grouping after all the vinyl files have come through the stream. See the group-array documentation for more advanced features.

Params

* args... {Mixed}: All of the arguments will be passed through to group-array except for the last argument if it's an object.
* options {Object}: Optional object to specify options. If this is passed, then it won't be passed to group-array.
* options.groupFn {Function}: Function that will be called with the group object. This is the results from calling group-array.
* options.flush {Boolean}: When set to false, the source files will not be pushed through the stream. (Defaults to true)
* options.groupFile {Boolean}: When set to true, a new vinyl-group will be created with a .group property containing the group object created by group-array.
* returns {Stream}: Returns a stream to pipe vinyl source files through.

Example

`js
gulp.task('group', function() {
return gulp.src(['path/to/src/files/*.js'])
.pipe(groupArray('dirname', {
groupFn: function(group) { console.log(group); }
}));
});
`

Examples

Use the groupFn to capture the group to use the group in another place:

`js
var cache = {};
gulp.task('group', function() {
return gulp.src(['path/to/src/files/*.js'])
.pipe(groupArray('dirname', {
groupFn: function(group) {
cache.group = group;
}
}));
});

gulp.task('default', ['group'], function(cb) {
// do something with the group
console.log(cache.group);
cb();
});
`

Use groupFile to get the group in another plugin before the other files come through. This example will use gulp-gray-matter to parse yaml front matter from handlebars templates, build a context for each file using the group and the file.data, then render the handlebars templates to html using the context.

This example requires having some handlebars templates with yaml front-matter.
Create a few files with the following template:

`handlebars
---
tags: ['foo', 'bar']
---
{{#each groups.tags as |items tag|}}


{{#each items as |item|}}

• {{item.path}}

{{/each}}

{{/each}}
`

Use the following javascript in a gulpfile.js to render the files:

`js
var gulp = require('gulp');
var extname = require('gulp-extname');
var extend = require('extend-shallow');
var Handlebars = require('handlebars');
var matter = require('gulp-gray-matter');
var through = require('through2');

var groupArray = require('gulp-group-array');

gulp.task('render', function() {
var cache = {groups: {}};

// load handlebars files that have yaml front matter
return gulp.src(['templates/*.hbs'])

// use gulp-gray-matter to parse yaml front matter and put it on .data object
.pipe(matter())

// look for data.tags from the front matter to group by and push the results into the stream
.pipe(groupArray('data.tags', { groupFile: true }))

// custom plugin that captures the tags group and renders the other handlebars files.
.pipe(through.obj(function(file, enc, cb) {
// the first file through should be the groupFile
if (file.group) {
cache.groups.tags = file.group;
return cb();
}

// use extend-shallow to create a data context from the file front matter and the cache
var context = extend({}, cache, file.data);

// render the handlebars using the context
var content = Handlebars.compile(file.contents.toString())(context);
file.contents = new Buffer(content);
cb(null, file);
}))
.pipe(extname())
.pipe(gulp.dest('dist'));
});
`

Run the following command to render the files:

`sh
$ gulp render
`

About

$3

* group-array: Group array of objects into lists. | homepage
* gulp: The streaming build system | homepage
* vinyl: A virtual file format | homepage

$3

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

$3

_(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
`

$3

Install dev dependencies:

`sh
$ npm install -d && npm test
``

$3

Brian Woodward

* github/doowb
* twitter/doowb

$3

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

*

_This file was generated by verb, v0.9.0, on July 29, 2016._