npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

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 NPM version NPM downloads Build Status

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

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.