Node Promiscuous Modules

    templates

    1.2.9 • Public • Published

    templates NPM version NPM monthly downloads NPM total downloads Linux Build Status Windows Build Status

    System for creating and managing template collections, and rendering templates with any node.js template engine. Can be used as the basis for creating a static site generator or blog framework.

    Table of Contents

    (TOC generated by verb using markdown-toc)

    Install

    Install with npm:

    $ npm install --save templates

    Features

    Usage

    var templates = require('templates');
    var app = templates();

    Example

    // register an engine to automatically render `md` files
    app.engine('md', require('engine-lodash'));
     
    // create a template collection
    app.create('pages');
     
    // add a template to the collection
    app.page('post.md', {content: 'This is the <%= title %> page'});
     
    // render it
    app.render('post.md', {title: 'Home'}, function(err, view) {
      console.log(view.content);
      //=> 'This is the Home page'
    });

    API

    Common

    This section describes API features that are shared by all Templates classes.

    .option

    Set or get an option value.

    Params

    • key {String|Object}: Pass a key-value pair or an object to set.
    • val {any}: Any value when a key-value pair is passed. This can also be options if a glob pattern is passed as the first value.
    • returns {Object}: Returns the instance for chaining.

    Example

    app.option('a', 'b');
    app.option({c: 'd'});
    console.log(app.options);
    //=> {a: 'b', c: 'd'}

    .use

    Run a plugin on the given instance. Plugins are invoked immediately upon instantiating in the order in which they were defined.

    Example

    The simplest plugin looks something like the following:

    app.use(function(inst) {
      // do something to `inst`
    });

    Note that inst is the instance of the class you're instantiating. So if you create an instance of Collection, inst is the collection instance.

    Params

    • fn {Function}: Plugin function. If the plugin returns a function it will be passed to the use method of each item created on the instance.
    • returns {Object}: Returns the instance for chaining.

    Usage

    collection.use(function(items) {
      // `items` is the instance, as is `this`
     
      // optionally return a function to be passed to
      // the `.use` method of each item created on the
      // instance
      return function(item) {
        // do stuff to each `item`
      };
    });

    App

    The Templates class is the main export of the templates library. All of the other classes are exposed as static properties on Templates:

    Templates

    This function is the main export of the templates module. Initialize an instance of templates to create your application.

    Params

    • options {Object}

    Example

    var templates = require('templates');
    var app = templates();

    .list

    Create a new list. See the list docs for more information about lists.

    Params

    • opts {Object}: List options
    • returns {Object}: Returns the list instance for chaining.

    Example

    var list = app.list();
    list.addItem('abc', {content: '...'});
     
    // or, create list from a collection
    app.create('pages');
    var list = app.list(app.pages);

    .collection

    Create a new collection. Collections are decorated with special methods for getting and setting items from the collection. Note that, unlike the create method, collections created with .collection() are not cached.

    See the collection docs for more information about collections.

    Params

    • opts {Object}: Collection options
    • returns {Object}: Returns the collection instance for chaining.

    .create

    Create a new view collection to be stored on the app.views object. See the create docs for more details.

    Params

    • name {String}: The name of the collection to create. Plural or singular form may be used, as the inflections are automatically resolved when the collection is created.
    • opts {Object}: Collection options
    • returns {Object}: Returns the collection instance for chaining.

    .setup

    Expose static setup method for providing access to an instance before any other code is run.

    Params

    • app {Object}: Application instance
    • name {String}: Optionally pass the constructor name to use.
    • returns {undefined}

    Example

    function App(options) {
      Templates.call(this, options);
      Templates.setup(this);
    }
    Templates.extend(App);

    .engine

    Register a view engine callback fn as ext. Calls .setEngine and .getEngine internally.

    Params

    • exts {String|Array}: String or array of file extensions.
    • fn {Function|Object}: or settings
    • settings {Object}: Optionally pass engine options as the last argument.

    Example

    app.engine('hbs', require('engine-handlebars'));
     
    // using consolidate.js
    var engine = require('consolidate');
    app.engine('jade', engine.jade);
    app.engine('swig', engine.swig);
     
    // get a registered engine
    var swig = app.engine('swig');

    .setEngine

    Register engine ext with the given render fn and/or settings.

    Params

    • ext {String}: The engine to set.

    Example

    app.setEngine('hbs', require('engine-handlebars'), {
      delims: ['<%', '%>']
    });

    .getEngine

    Get registered engine ext.

    Params

    • ext {String}: The engine to get.

    Example

    app.engine('hbs', require('engine-handlebars'));
    var engine = app.getEngine('hbs');

    .helper

    Register a template helper.

    Params

    • name {String}: Helper name
    • fn {Function}: Helper function.

    Example

    app.helper('upper', function(str) {
      return str.toUpperCase();
    });

    .helpers

    Register multiple template helpers.

    Params

    • helpers {Object|Array}: Object, array of objects, or glob patterns.

    Example

    app.helpers({
      foo: function() {},
      bar: function() {},
      baz: function() {}
    });

    .asyncHelper

    Register an async helper.

    Params

    • name {String}: Helper name.
    • fn {Function}: Helper function

    Example

    app.asyncHelper('upper', function(str, next) {
      next(null, str.toUpperCase());
    });

    .asyncHelpers

    Register multiple async template helpers.

    Params

    • helpers {Object|Array}: Object, array of objects, or glob patterns.

    Example

    app.asyncHelpers({
      foo: function() {},
      bar: function() {},
      baz: function() {}
    });

    .getHelper

    Get a previously registered helper.

    Params

    • name {String}: Helper name
    • returns {Function}: Returns the registered helper function.

    Example

    var fn = app.getHelper('foo');

    .getAsyncHelper

    Get a previously registered async helper.

    Params

    • name {String}: Helper name
    • returns {Function}: Returns the registered helper function.

    Example

    var fn = app.getAsyncHelper('foo');

    .hasHelper

    Return true if sync helper name is registered.

    Params

    • name {String}: sync helper name
    • returns {Boolean}: Returns true if the sync helper is registered

    Example

    if (app.hasHelper('foo')) {
      // do stuff
    }

    .hasAsyncHelper

    Return true if async helper name is registered.

    Params

    • name {String}: Async helper name
    • returns {Boolean}: Returns true if the async helper is registered

    Example

    if (app.hasAsyncHelper('foo')) {
      // do stuff
    }

    .helperGroup

    Register a namespaced helper group.

    Params

    • helpers {Object|Array}: Object, array of objects, or glob patterns.

    Example

    // markdown-utils
    app.helperGroup('mdu', {
      foo: function() {},
      bar: function() {},
    });
     
    // Usage:
    // <%= mdu.foo() %>
    // <%= mdu.bar() %>

    Built-in helpers


    View

    API for the View class.

    View

    Create an instance of View. Optionally pass a default object to use.

    Params

    • view {Object}

    Example

    var view = new View({
      path: 'foo.html',
      contents: new Buffer('...')
    });

    .compile

    Synchronously compile a view.

    Params

    • locals {Object}: Optionally pass locals to the engine.
    • returns {Object} View: instance, for chaining.

    Example

    var view = page.compile();
    view.fn({title: 'A'});
    view.fn({title: 'B'});
    view.fn({title: 'C'});

    .renderSync

    Synchronously render templates in view.content.

    Params

    • locals {Object}: Optionally pass locals to the engine.
    • returns {Object} View: instance, for chaining.

    Example

    var view = new View({content: 'This is <%= title %>'});
    view.renderSync({title: 'Home'});
    console.log(view.content);

    .render

    Asynchronously render templates in view.content.

    Params

    • locals {Object}: Context to use for rendering templates.

    Example

    view.render({title: 'Home'}, function(err, res) {
      //=> view object with rendered `content`
    });

    .context

    Create a context object from locals and the view.data and view.locals objects. The view.data property is typically created from front-matter, and view.locals is used when a new View() is created.

    This method be overridden either by defining a custom view.options.context function to customize context for a view instance, or static View.context function to customize context for all view instances.

    Params

    • locals {Object}: Optionally pass a locals object to merge onto the context.
    • returns {Object}: Returns the context object.

    Example

    var page = new View({path: 'a/b/c.txt', locals: {a: 'b', c: 'd'}});
    var ctx = page.context({a: 'z'});
    console.log(ctx);
    //=> {a: 'z', c: 'd'}

    .isType

    Returns true if the view is the given viewType. Returns false if no type is assigned. When used with vinyl-collections, types are assigned by their respective collections.

    Params

    • type {String}: (renderable, partial, layout)

    Example

    var view = new View({path: 'a/b/c.txt', viewType: 'partial'})
    view.isType('partial');

    .View.context

    Define a custom static View.context function to override default .context behavior. See the context docs for more info.

    Params

    • locals {Object}
    • returns {Object}

    Example

    // custom context function
    View.context = function(locals) {
      // `this` is the view being rendered
      return locals;
    };

    .data

    Set, get and load data to be passed to templates as context at render-time.

    Params

    • key {String|Object}: Pass a key-value pair or an object to set.
    • val {any}: Any value when a key-value pair is passed. This can also be options if a glob pattern is passed as the first value.
    • returns {Object}: Returns an instance of Templates for chaining.

    Example

    app.data('a', 'b');
    app.data({c: 'd'});
    console.log(app.cache.data);
    //=> {a: 'b', c: 'd'}

    .context

    Build the context for the given view and locals.

    Params

    • view {Object}: The view being rendered
    • locals {Object}
    • returns {Object}: The object to be passed to engines/views as context.

    setHelperOptions

    Update context in a helper so that this.helper.options is the options for that specific helper.

    Params

    • context {Object}
    • key {String}

    .mergePartials

    Merge "partials" view types. This is necessary for template engines have no support for partials or only support one type of partials.

    Params

    • options {Object}: Optionally pass an array of viewTypes to include on options.viewTypes
    • returns {Object}: Merged partials

    .mergePartialsAsync

    Merge "partials" view types. This is necessary for template engines have no support for partials or only support one type of partials.

    Params

    • options {Object}: Optionally pass an array of viewTypes to include on options.viewTypes
    • callback {Function}: Function that exposes err and partials parameters

    Item

    API for the Item class.

    Item

    Create an instance of Item. Optionally pass a default object to use. See vinyl docs for API details and additional documentation.

    Params

    • item {Object}

    Example

    var item = new Item({
      path: 'foo.html',
      contents: new Buffer('...')
    });

    .content

    Normalize the content and contents properties on item. This is done to ensure compatibility with the vinyl convention of using contents as a Buffer, as well as the assemble convention of using content as a string. We will eventually deprecate the content property.

    Example

    var item = new Item({path: 'foo/bar.hbs', contents: new Buffer('foo')});
    console.log(item.content);
    //=> 'foo'

    .engine

    Getter/setter to resolve the name of the engine to use for rendering.

    Example

    var item = new Item({path: 'foo/bar.hbs'});
    console.log(item.engine);
    //=> '.hbs'

    .data

    Set, get and load data to be passed to templates as context at render-time.

    Params

    • key {String|Object}: Pass a key-value pair or an object to set.
    • val {any}: Any value when a key-value pair is passed. This can also be options if a glob pattern is passed as the first value.
    • returns {Object}: Returns an instance of Templates for chaining.

    Example

    app.data('a', 'b');
    app.data({c: 'd'});
    console.log(app.cache.data);
    //=> {a: 'b', c: 'd'}

    .context

    Build the context for the given view and locals.

    Params

    • view {Object}: The view being rendered
    • locals {Object}
    • returns {Object}: The object to be passed to engines/views as context.

    setHelperOptions

    Update context in a helper so that this.helper.options is the options for that specific helper.

    Params

    • context {Object}
    • key {String}

    .mergePartials

    Merge "partials" view types. This is necessary for template engines have no support for partials or only support one type of partials.

    Params

    • options {Object}: Optionally pass an array of viewTypes to include on options.viewTypes
    • returns {Object}: Merged partials

    .mergePartialsAsync

    Merge "partials" view types. This is necessary for template engines have no support for partials or only support one type of partials.

    Params

    • options {Object}: Optionally pass an array of viewTypes to include on options.viewTypes
    • callback {Function}: Function that exposes err and partials parameters

    Views

    API for the Views class.

    Views

    Create an instance of Views with the given options.

    Params

    • options {Object}

    Example

    var collection = new Views();
    collection.addView('foo', {content: 'bar'});

    .addView

    Add a view to collection.views. This is identical to addView except setView returns the collection instance, and addView returns the item instance.

    Params

    • key {String|Object}: View key or object
    • value {Object}: If key is a string, value is the view object.
    • next {Function}: Optionally pass a callback function as the last argument to load the view asynchronously. This will also ensure that .onLoad middleware is executed asynchronously.
    • returns {Object}: returns the view instance.

    Example

    collection.setView('foo', {content: 'bar'});
     
    // or, optionally async
    collection.setView('foo', {content: 'bar'}, function(err, view) {
      // `err` errors from `onLoad` middleware
      // `view` the view object after `onLoad` middleware has run
    });

    .setView

    Set a view on the collection. This is identical to addView except setView does not emit an event for each view.

    Params

    • key {String|Object}: View key or object
    • value {Object}: If key is a string, value is the view object.
    • returns {Object}: returns the view instance.

    Example

    collection.setView('foo', {content: 'bar'});

    .getView

    Get view name from collection.views.

    Params

    • key {String}: Key of the view to get.
    • fn {Function}: Optionally pass a function to modify the key.
    • returns {Object}

    Example

    collection.getView('a.html');

    .deleteView

    Delete a view from collection views.

    Params

    • key {String}
    • returns {Object}: Returns the instance for chaining

    Example

    views.deleteView('foo.html');

    .addViews

    Load multiple views onto the collection.

    Params

    • views {Object|Array}
    • returns {Object}: returns the collection object

    Example

    collection.addViews({
      'a.html': {content: '...'},
      'b.html': {content: '...'},
      'c.html': {content: '...'}
    });

    .addList

    Load an array of views onto the collection.

    Params

    • list {Array}
    • returns {Object}: returns the views instance

    Example

    collection.addList([
      {path: 'a.html', content: '...'},
      {path: 'b.html', content: '...'},
      {path: 'c.html', content: '...'}
    ]);

    .groupBy

    Group all collection views by the given property, properties or compare functions. See group-array for the full range of available features and options.

    • returns {Object}: Returns an object of grouped views.

    Example

    var collection = new Collection();
    collection.addViews(...);
    var groups = collection.groupBy('data.date', 'data.slug');

    .isType

    Return true if the collection belongs to the given view type.

    Params

    • type {String}: (renderable, partial, layout)

    Example

    collection.isType('partial');

    .viewTypes

    Alias for viewType

    .data

    Set, get and load data to be passed to templates as context at render-time.

    Params

    • key {String|Object}: Pass a key-value pair or an object to set.
    • val {any}: Any value when a key-value pair is passed. This can also be options if a glob pattern is passed as the first value.
    • returns {Object}: Returns an instance of Templates for chaining.

    Example

    app.data('a', 'b');
    app.data({c: 'd'});
    console.log(app.cache.data);
    //=> {a: 'b', c: 'd'}

    .context

    Build the context for the given view and locals.

    Params

    • view {Object}: The view being rendered
    • locals {Object}
    • returns {Object}: The object to be passed to engines/views as context.

    setHelperOptions

    Update context in a helper so that this.helper.options is the options for that specific helper.

    Params

    • context {Object}
    • key {String}

    .mergePartials

    Merge "partials" view types. This is necessary for template engines have no support for partials or only support one type of partials.

    Params

    • options {Object}: Optionally pass an array of viewTypes to include on options.viewTypes
    • returns {Object}: Merged partials

    .mergePartialsAsync

    Merge "partials" view types. This is necessary for template engines have no support for partials or only support one type of partials.

    Params

    • options {Object}: Optionally pass an array of viewTypes to include on options.viewTypes
    • callback {Function}: Function that exposes err and partials parameters

    .find

    Find a view by name, optionally passing a collection to limit the search. If no collection is passed all renderable collections will be searched.

    Params

    • name {String}: The name/key of the view to find
    • colleciton {String}: Optionally pass a collection name (e.g. pages)
    • returns {Object|undefined}: Returns the view if found, or undefined if not.

    Example

    var page = app.find('my-page.hbs');
     
    // optionally pass a collection name as the second argument
    var page = app.find('my-page.hbs', 'pages');

    .getView

    Get view key from the specified collection.

    Params

    • collection {String}: Collection name, e.g. pages
    • key {String}: Template name
    • fn {Function}: Optionally pass a renameKey function
    • returns {Object}

    Example

    var view = app.getView('pages', 'a/b/c.hbs');
     
    // optionally pass a `renameKey` function to modify the lookup
    var view = app.getView('pages', 'a/b/c.hbs', function(fp) {
      return path.basename(fp);
    });

    .getViews

    Get all views from a collection using the collection's singular or plural name.

    Params

    • name {String}: The collection name, e.g. pages or page
    • returns {Object}

    Example

    var pages = app.getViews('pages');
    //=> { pages: {'home.hbs': { ... }}
     
    var posts = app.getViews('posts');
    //=> { posts: {'2015-10-10.md': { ... }}

    Collections

    API for the Collections class.

    Collection

    Create an instance of Collection with the given options.

    Params

    • options {Object}

    Example

    var collection = new Collection();
    collection.addItem('foo', {content: 'bar'});

    .addItem

    Add an item to the collection.

    Params

    • key {String|Object}: Item name or object
    • val {Object}: Item object, when key is a string.
    • returns {Object}: returns the item instance.

    Events

    • emits: item With the created item and collection instance as arguments.

    Example

    collection.addItem('foo', {content: 'bar'});

    .setItem

    Identical to .addItem, except the collection instance is returned instead of the item, to allow chaining.

    Params

    • key {String|Object}: Item name or object
    • val {Object}: Item object, when key is a string.
    • returns {Object}: returns the collection instance.

    Events

    • emits: item With the created item and collection instance as arguments.

    Example

    collection.setItem('foo', {content: 'bar'});

    .getItem

    Get an item from collection.items.

    Params

    • key {String}: Key of the item to get.
    • returns {Object}

    Example

    collection.getItem('a.html');

    .deleteItem

    Remove an item from collection.items.

    Params

    • key {String}
    • returns {Object}: Returns the instance for chaining

    Example

    items.deleteItem('abc');

    .addItems

    Load multiple items onto the collection.

    Params

    • items {Object|Array}
    • returns {Object}: returns the instance for chaining

    Example

    collection.addItems({
      'a.html': {content: '...'},
      'b.html': {content: '...'},
      'c.html': {content: '...'}
    });

    .addList

    Load an array of items onto the collection.

    Params

    • items {Array}: or an instance of List
    • fn {Function}: Optional sync callback function that is called on each item.
    • returns {Object}: returns the Collection instance for chaining

    Example

    collection.addList([
      {path: 'a.html', content: '...'},
      {path: 'b.html', content: '...'},
      {path: 'c.html', content: '...'}
    ]);

    .data

    Set, get and load data to be passed to templates as context at render-time.

    Params

    • key {String|Object}: Pass a key-value pair or an object to set.
    • val {any}: Any value when a key-value pair is passed. This can also be options if a glob pattern is passed as the first value.
    • returns {Object}: Returns an instance of Templates for chaining.

    Example

    app.data('a', 'b');
    app.data({c: 'd'});
    console.log(app.cache.data);
    //=> {a: 'b', c: 'd'}

    .context

    Build the context for the given view and locals.

    Params

    • view {Object}: The view being rendered
    • locals {Object}
    • returns {Object}: The object to be passed to engines/views as context.

    setHelperOptions

    Update context in a helper so that this.helper.options is the options for that specific helper.

    Params

    • context {Object}
    • key {String}

    .mergePartials

    Merge "partials" view types. This is necessary for template engines have no support for partials or only support one type of partials.

    Params

    • options {Object}: Optionally pass an array of viewTypes to include on options.viewTypes
    • returns {Object}: Merged partials

    .mergePartialsAsync

    Merge "partials" view types. This is necessary for template engines have no support for partials or only support one type of partials.

    Params

    • options {Object}: Optionally pass an array of viewTypes to include on options.viewTypes
    • callback {Function}: Function that exposes err and partials parameters

    List

    API for the List class.

    List

    Create an instance of List with the given options. Lists differ from collections in that items are stored as an array, allowing items to be paginated, sorted, and grouped.

    Params

    • options {Object}

    Example

    var list = new List();
    list.addItem('foo', {content: 'bar'});

    .addItem

    Add an item to list.items. This is identical to setItem except addItem returns the item, add setItem returns the instance of List.

    Params

    • key {String|Object}: Item key or object
    • value {Object}: If key is a string, value is the item object.
    • returns {Object}: returns the item instance.

    Example

    collection.addItem('foo', {content: 'bar'});

    .setItem

    Add an item to list.items. This is identical to addItem except addItem returns the item, add setItem returns the instance of List.

    Params

    • key {String}
    • value {Object}
    • returns {Object}: Returns the instance of List to support chaining.

    Example

    var items = new Items(...);
    items.setItem('a.html', {path: 'a.html', contents: '...'});

    .addItems

    Load multiple items onto the collection.

    Params

    • items {Object|Array}
    • returns {Object}: returns the instance for chaining

    Example

    collection.addItems({
      'a.html': {content: '...'},
      'b.html': {content: '...'},
      'c.html': {content: '...'}
    });

    .addList

    Load an array of items or the items from another instance of List.

    Params

    • items {Array}: or an instance of List
    • fn {Function}: Optional sync callback function that is called on each item.
    • returns {Object}: returns the List instance for chaining

    Example

    var foo = new List(...);
    var bar = new List(...);
    bar.addList(foo);

    .hasItem

    Return true if the list has the given item (name).

    Params

    • key {String}
    • returns {Object}

    Example

    list.addItem('foo.html', {content: '...'});
    list.hasItem('foo.html');
    //=> true

    .getIndex

    Get a the index of a specific item from the list by key.

    Params

    • key {String}
    • returns {Object}

    Example

    list.getIndex('foo.html');
    //=> 1

    .getItem

    Get a specific item from the list by key.

    Params

    • key {String}: The item name/key.
    • returns {Object}

    Example

    list.getItem('foo.html');
    //=> '<Item <foo.html>>'

    .getView

    Proxy for getItem

    Params

    • key {String}: Pass the key of the item to get.
    • returns {Object}

    Example

    list.getItem('foo.html');
    //=> '<Item "foo.html" <buffer e2 e2 e2>>'

    .deleteItem

    Remove an item from the list.

    Params

    • key {Object|String}: Pass an item instance (object) or item.key (string).

    Example

    list.deleteItem('a.html');

    .deleteItems

    Remove one or more items from the list.

    Params

    • items {Object|String|Array}: List of items to remove.

    Example

    list.deleteItems(['a.html', 'b.html']);

    .extendItem

    Decorate each item on the list with additional methods and properties. This provides a way of easily overriding defaults.

    Params

    • item {Object}
    • returns {Object}: Instance of item for chaining

    .filter

    Filters list items using the given fn and returns a new array.

    • returns {Object}: Returns a filtered array of items.

    Example

    var items = list.filter(function(item) {
      return item.data.title.toLowerCase() !== 'home';
    });

    .sortBy

    Sort all list items using the given property, properties or compare functions. See array-sort for the full range of available features and options.

    • returns {Object}: Returns a new List instance with sorted items.

    Example

    var list = new List();
    list.addItems(...);
    var result = list.sortBy('data.date');
    //=> new sorted list

    .groupBy

    Group all list items using the given property, properties or compare functions. See group-array for the full range of available features and options.

    • returns {Object}: Returns the grouped items.

    Example

    var list = new List();
    list.addItems(...);
    var groups = list.groupBy('data.date', 'data.slug');

    .paginate

    Paginate all items in the list with the given options, See paginationator for the full range of available features and options.

    • returns {Object}: Returns the paginated items.

    Example

    var list = new List(items);
    var pages = list.paginate({limit: 5});

    .data

    Set, get and load data to be passed to templates as context at render-time.

    Params

    • key {String|Object}: Pass a key-value pair or an object to set.
    • val {any}: Any value when a key-value pair is passed. This can also be options if a glob pattern is passed as the first value.
    • returns {Object}: Returns an instance of Templates for chaining.

    Example

    app.data('a', 'b');
    app.data({c: 'd'});
    console.log(app.cache.data);
    //=> {a: 'b', c: 'd'}

    .context

    Build the context for the given view and locals.

    Params

    • view {Object}: The view being rendered
    • locals {Object}
    • returns {Object}: The object to be passed to engines/views as context.

    setHelperOptions

    Update context in a helper so that this.helper.options is the options for that specific helper.

    Params

    • context {Object}
    • key {String}

    .mergePartials

    Merge "partials" view types. This is necessary for template engines have no support for partials or only support one type of partials.

    Params

    • options {Object}: Optionally pass an array of viewTypes to include on options.viewTypes
    • returns {Object}: Merged partials

    .mergePartialsAsync

    Merge "partials" view types. This is necessary for template engines have no support for partials or only support one type of partials.

    Params

    • options {Object}: Optionally pass an array of viewTypes to include on options.viewTypes
    • callback {Function}: Function that exposes err and partials parameters

    Group

    API for the Group class.

    Group

    Create an instance of Group with the given options.

    Params

    • options {Object}

    Example

    var group = new Group({
      'foo': { items: [1,2,3] }
    });

    .find

    Find a view by name, optionally passing a collection to limit the search. If no collection is passed all renderable collections will be searched.

    Params

    • name {String}: The name/key of the view to find
    • colleciton {String}: Optionally pass a collection name (e.g. pages)
    • returns {Object|undefined}: Returns the view if found, or undefined if not.

    Example

    var page = app.find('my-page.hbs');
     
    // optionally pass a collection name as the second argument
    var page = app.find('my-page.hbs', 'pages');

    .getView

    Get view key from the specified collection.

    Params

    • collection {String}: Collection name, e.g. pages
    • key {String}: Template name
    • fn {Function}: Optionally pass a renameKey function
    • returns {Object}

    Example

    var view = app.getView('pages', 'a/b/c.hbs');
     
    // optionally pass a `renameKey` function to modify the lookup
    var view = app.getView('pages', 'a/b/c.hbs', function(fp) {
      return path.basename(fp);
    });

    .getViews

    Get all views from a collection using the collection's singular or plural name.

    Params

    • name {String}: The collection name, e.g. pages or page
    • returns {Object}

    Example

    var pages = app.getViews('pages');
    //=> { pages: {'home.hbs': { ... }}
     
    var posts = app.getViews('posts');
    //=> { posts: {'2015-10-10.md': { ... }}

    .compile

    Compile content with the given locals.

    Params

    • view {Object|String}: View object.
    • locals {Object}
    • isAsync {Boolean}: Load async helpers
    • returns {Object}: View object with compiled view.fn property.

    Example

    var indexPage = app.page('some-index-page.hbs');
    var view = app.compile(indexPage);
    // view.fn => [function]
     
    // you can call the compiled function more than once
    // to render the view with different data
    view.fn({title: 'Foo'});
    view.fn({title: 'Bar'});
    view.fn({title: 'Baz'});

    .compileAsync

    Asynchronously compile content with the given locals and callback. (fwiw, this method name uses the unconventional "*Async" nomenclature to allow us to preserve the synchronous behavior of the view.compile method as well as the name).

    Params

    • view {Object|String}: View object.
    • locals {Object}
    • isAsync {Boolean}: Pass true to load helpers as async (mostly used internally)
    • callback {Function}: function that exposes err and the view object with compiled view.fn property

    Example

    var indexPage = app.page('some-index-page.hbs');
    app.compileAsync(indexPage, function(err, view) {
      // view.fn => compiled function
    });

    .render

    Render a view with the given locals and callback.

    Params

    • view {Object|String}: Instance of View
    • locals {Object}: Locals to pass to template engine.
    • callback {Function}

    Example

    var blogPost = app.post.getView('2015-09-01-foo-bar');
    app.render(blogPost, {title: 'Foo'}, function(err, view) {
      // `view` is an object with a rendered `content` property
    });

    .data

    Set, get and load data to be passed to templates as context at render-time.

    Params

    • key {String|Object}: Pass a key-value pair or an object to set.
    • val {any}: Any value when a key-value pair is passed. This can also be options if a glob pattern is passed as the first value.
    • returns {Object}: Returns an instance of Templates for chaining.

    Example

    app.data('a', 'b');
    app.data({c: 'd'});
    console.log(app.cache.data);
    //=> {a: 'b', c: 'd'}

    .context

    Build the context for the given view and locals.

    Params

    • view {Object}: The view being rendered
    • locals {Object}
    • returns {Object}: The object to be passed to engines/views as context.

    setHelperOptions

    Update context in a helper so that this.helper.options is the options for that specific helper.

    Params

    • context {Object}
    • key {String}

    .mergePartials

    Merge "partials" view types. This is necessary for template engines have no support for partials or only support one type of partials.

    Params

    • options {Object}: Optionally pass an array of viewTypes to include on options.viewTypes
    • returns {Object}: Merged partials

    .mergePartialsAsync

    Merge "partials" view types. This is necessary for template engines have no support for partials or only support one type of partials.

    Params

    • options {Object}: Optionally pass an array of viewTypes to include on options.viewTypes
    • callback {Function}: Function that exposes err and partials parameters

    Middleware

    Control the entire render cycle, with simple-to-use routes and middleware.

    Example

    var router = new app.Router();
    var route = new app.Route();

    .handle

    Handle a middleware method for file.

    Params

    • method {String}: Name of the router method to handle. See router methods
    • file {Object}: View object
    • callback {Function}: Callback function
    • returns {undefined}

    Example

    app.handle('customMethod', file, callback);

    .handleOnce

    Run the given middleware handler only if the file has not already been handled by method.

    Params

    • method {Object}: The name of the handler method to call.
    • file {Object}
    • returns {undefined}

    Example

    app.handleOnce('onLoad', file, callback);

    .route

    Create a new Route for the given path. Each route contains a separate middleware stack. See the [route API documentation][route-api] for details on adding handlers and middleware to routes.

    Params

    • path {String}
    • returns {Object}: Returns the instance for chaining.

    Example

    app.create('posts');
    app.route(/blog/)
      .all(function(file, next) {
        // do something with file
        next();
      });
     
    app.post('whatever', {path: 'blog/foo.bar', content: 'bar baz'});

    .param

    Add callback triggers to route parameters, where name is the name of the parameter and fn is the callback function.

    Params

    • name {String}
    • fn {Function}
    • returns {Object}: Returns the instance for chaining.

    Example

    app.param('title', function(view, next, title) {
      //=> title === 'foo.js'
      next();
    });
     
    app.onLoad('/blog/:title', function(view, next) {
      //=> view.path === '/blog/foo.js'
      next();
    });

    .all

    Special route method that works just like the router.METHOD() methods, except that it matches all verbs.

    Params

    • path {String}
    • callback {Function}
    • returns {Object} this: for chaining

    Example

    app.all(/\.hbs$/, function(view, next) {
      // do stuff to view
      next();
    });

    .handler

    Add a router handler method to the instance. Interchangeable with the handlers method.

    Params

    • method {String}: Name of the handler method to define.
    • returns {Object}: Returns the instance for chaining

    Example

    app.handler('onFoo');
    // or
    app.handler(['onFoo', 'onBar']);

    .handlers

    Add one or more router handler methods to the instance.

    Params

    • methods {Array|String}: One or more method names to define.
    • returns {Object}: Returns the instance for chaining

    Example

    app.handlers(['onFoo', 'onBar', 'onBaz']);
    // or
    app.handlers('onFoo');

    .isApp

    Static method that returns true if the given value is a templates instance (App).

    Params

    • val {Object}: The value to test.
    • returns {Boolean}

    Example

    var templates = require('templates');
    var app = templates();
     
    templates.isApp(templates);
    //=> false
     
    templates.isApp(app);
    //=> true

    .isCollection

    Static method that returns true if the given value is a templates Collection instance.

    Params

    • val {Object}: The value to test.
    • returns {Boolean}

    Example

    var templates = require('templates');
    var app = templates();
     
    app.create('pages');
    templates.isCollection(app.pages);
    //=> true

    .isViews

    Static method that returns true if the given value is a templates Views instance.

    Params

    • val {Object}: The value to test.
    • returns {Boolean}

    Example

    var templates = require('templates');
    var app = templates();
     
    app.create('pages');
    templates.isViews(app.pages);
    //=> true

    .isList

    Static method that returns true if the given value is a templates List instance.

    Params

    • val {Object}: The value to test.
    • returns {Boolean}

    Example

    var templates = require('templates');
    var List = templates.List;
    var app = templates();
     
    var list = new List();
    templates.isList(list);
    //=> true

    .isGroup

    Static method that returns true if the given value is a templates Group instance.

    Params

    • val {Object}: The value to test.
    • returns {Boolean}

    Example

    var templates = require('templates');
    var Group = templates.Group;
    var app = templates();
     
    var group = new Group();
    templates.isGroup(group);
    //=> true

    .isView

    Static method that returns true if the given value is a templates View instance.

    Params

    • val {Object}: The value to test.
    • returns {Boolean}

    Example

    var templates = require('templates');
    var app = templates();
     
    templates.isView('foo');
    //=> false
     
    var view = app.view('foo', {content: '...'});
    templates.isView(view);
    //=> true

    .isItem

    Static method that returns true if the given value is a templates Item instance.

    Params

    • val {Object}: The value to test.
    • returns {Boolean}

    Example

    var templates = require('templates');
    var app = templates();
     
    templates.isItem('foo');
    //=> false
     
    var view = app.view('foo', {content: '...'});
    templates.isItem(view);
    //=> true

    .isVinyl

    Static method that returns true if the given value is a vinyl File instance.

    Params

    • val {Object}: The value to test.
    • returns {Boolean}

    Example

    var File = require('vinyl');
    var templates = require('templates');
    var app = templates();
     
    var view = app.view('foo', {content: '...'});
    templates.isVinyl(view);
    //=> true
     
    var file = new File({path: 'foo', contents: new Buffer('...')});
    templates.isVinyl(file);
    //=> true

    More examples

    This is just a very basic glimpse at the templates API!

    var templates = require('templates');
    var app = templates();
     
    // create a collection
    app.create('pages');
     
    // add views to the collection
    app.page('a.html', {content: 'this is <%= foo %>'});
    app.page('b.html', {content: 'this is <%= bar %>'});
    app.page('c.html', {content: 'this is <%= baz %>'});
     
    app.pages.getView('a.html')
      .render({foo: 'home'}, function (err, view) {
        //=> 'this is home'
      });

    History

    key

    Starting with v0.25.0, changelog entries will be categorized using the following labels from keep-a-changelog_:

    • added: for new features
    • changed: for changes in existing functionality
    • deprecated: for once-stable features removed in upcoming releases
    • removed: for deprecated features removed in this release
    • fixed: for any bug fixes

    1.1.0

    fixed

    Reverts layout changes from 1.0 to fix block-layout-nesting bug.

    There is a bug causing child blocks to be promoted up to ancestors when a nested layout/block is defined. It's not a common scenario, and probably hasn't been encountered in the wild yet since blocks were just introduced and haven't been documented yet. However, it's a bad bug, and would cause major problems if it surfaced.

    The good news is that I know how to fix it. Bad news is that it will be time consuming and I need to make other changes before I get to that fix. Thus, in the meantime the best course of action is removing the blocks code.

    1.0.0

    Added

    • Templates now uses dry for handling layouts
    • Advanced template-inheritance features, like extends and blocks! See dry documentation for details.

    0.25.2

    Fixed

    • Correctly handles arguments for the built-in singular helper when used with Handlebars.

    0.25.1

    Fixed

    • Ensures the template rendering engine's context is preserved.

    0.25.0

    Added

    • Views can now be created asynchronously by passing a callback as the last argument to .addView (or the method created by .create, e.g. .page)

    0.24.3

    Fixed

    • Ensures the view object has engineStack and localsStack properties

    0.24.0

    • Bumps base-data which removed renameKey option used when loading data. Use the namespace option instead.

    0.23.0

    0.22.2

    • fixes List bug that was caused collection helpers to explode

    0.22.0

    There should be no breaking changes in this release. If you experience a regression, please create an issue.

    • Externalizes a few core plugins to: base-helpers, base-routes, and [base-engine][]. The goal is to allow you to use only the plugins you need in your builds.
    • Improvements to lookup functions: app.getView() and app.find()
    • Bumps base to take advantages of code optimizations.

    0.21.0

    Breaking changes

    • The queue property has been removed, as well as related code for loading views using events. This behavior can easily be added using plugins or existing emitters.

    Non-breaking

    • The View and Item class have been externalized to modules vinyl-item and vinyl-view so they can be used in other libraries.

    0.20.0

    • Context: In general, context should be merged so that the most specific context wins over less specific. This fixes one case where locals was winning over front-matter
    • Helpers: Exposes .ctx() method on helper context, to simplify merging context in non-built-in helpers
    • Engines: Fixes bug that was using default engine on options instead of engine that matches view file extension.

    0.19.0

    0.18.0

    0.17.0

    • Removed debug methods and related code
    • Improve layout handling with respect to template types (partial, renderable and layout)
    • Update dependencies

    0.16.0

    0.15.0

    • removes .removeItem method that was deprecated in v0.10.7 from List
    • .handleView is deprecated in favor of .handleOnce and will be removed in a future version. Start using .handleOnce now.
    • adds a static Templates.setup() method for initializing any setup code that should have access to the instance before any other use code is run.
    • upgrade to base-data v0.4.0, which adds app.option.set, app.option.get and app.option.merge

    0.14.0

    Although 99% of users won't be effected by the changes in this release, there were some potentially breaking changes.

    • The render and compile methods were streamlined, making it clear that .mergePartials should not have been renamed to mergePartialsSync. So that change was reverted.
    • Helper context: Exposes a this.helper object to the context in helpers, which has the helper name and options that were set specifically for that helper
    • Helper context: Exposes a this.view object to the context in helpers, which is the current view being rendered. This was (and still is) always expose on this.context.view, but it makes sense to add this to the root of the context as a convenience. We will deprecate this.context.view in a future version.
    • Helper context: .get, .set and .merge methods on this.options, this.context and the this object in helpers.

    0.13.0

    • All template handling is async by default. Instead of adding .compileSync, we felt that it made more sense to add .compileAsync, since .compile is a public method and most users will expect it to be sync, and .compile methods with most engines are typically sync. In other words, .compileAsync probably won't be seen by most users, but we wanted to explain the decision to go against node.js naming conventions.
    • Improved layout detection and handling

    0.12.0

    0.11.0

    • Default engine can now be defined on app or a collection using using app.option('engine'), views.option('engine')
    • Default layout can now defined using app.option('layout'), views.option('layout'). No changes have been made to view.layout, it should work as before. Resolves issue/#818
    • Improves logic for finding a layout, this should make layouts easier to define and find going forward.
    • The built-in view helper has been refactored completely. The helper is now async and renders the view before returning its content.
    • Adds isApp, isViews, isCollection, isList, isView, isGroup, and isItem static methods. All return true when the given value is an instance of the respective class.
    • Adds deleteItem method to List and Collection, and deleteView method to Views.
    • Last, the static _.proto property which is only exposed for unit tests was renamed to _.plugin.

    0.10.7

    • Force-update base to v0.6.4 to take advantage of isRegistered feature.

    0.10.6

    • Re-introduces fs logic to getView, now that the method has been refactored to be faster.

    0.10.0

    • getView method no longer automatically reads views from the file system. This was undocumented before and, but it's a breaking change nonetheless. The removed functionality can easily be done in a plugin.

    0.9.5

    • Fixes error messages when no engine is found for a view, and the view does not have a file extension.

    0.9.4

    • Fixes a lookup bug in render and compile that was returning the first view that matched the given name from any collection. So if a partial and a page shared the same name, if the partial was matched first it was returned. Now the renderable view is rendered (e.g. page)

    0.9.0

    • breaking change: changes parameters on app.context method. It now only accepts two arguments, view and locals, since ctx (the parameter that was removed) was technically being merged in twice.

    0.8.0

    • Exposes isType method on view. Shouldn't be any breaking changes.

    0.7.0

    • breaking change: renamed .error method to .formatError
    • adds mergeContext option
    • collection name is now emitted with view and item as the second argument
    • adds isType method for checking the viewType on a collection
    • also now emits an event with the collection name when a view is created

    0.5.1

    • fixes bug where default layout was automatically applied to partials, causing an infinite loop in rare cases.

    About

    Related projects

    • assemble: Get the rocks out of your socks! Assemble makes you fast at creating web projects… more | homepage
    • en-route: Routing for static site generators, build systems and task runners, heavily based on express.js routes… more | homepage
    • engine: Template engine based on Lo-Dash template, but adds features like the ability to register helpers… more | homepage
    • layouts: Wraps templates with layouts. Layouts can use other layouts and be nested to any depth… more | homepage
    • verb: Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… more | homepage

    Contributing

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

    Contributors

    Commits Contributor
    753 jonschlinkert
    105 doowb
    1 chronzerg

    Building docs

    (This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

    To generate the readme, run the following command:

    $ npm install -g verbose/verb#dev verb-generate-readme && verb

    Running tests

    Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

    $ npm install && npm test

    Author

    Jon Schlinkert

    License

    Copyright © 2017, Jon Schlinkert. Released under the MIT License.


    This file was generated by verb-generate-readme, v0.6.0, on July 27, 2017.

    Install

    npm i templates

    DownloadsWeekly Downloads

    22,578

    Version

    1.2.9

    License

    MIT

    Last publish

    Collaborators

    • doowb
    • jonschlinkert
    • reaktivo