templates

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.

Install

Install with npm

$ npm i templates --save

Usage

var templates = require('templates');

API

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();

.use

Run a plugin on the instance.

Params

• {Function}: fn
• returns {Object}

Example

var app = assemble()
  .use(require('foo'))
  .use(require('bar'))
  .use(require('baz'))

.view

Returns a new view, using the View class currently defined on the instance.

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 object

Example

var view = app.view('foo', {conetent: '...'});
// or
var view = app.view({path: 'foo', conetent: '...'});

.data

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

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

**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.  

### [.collection](index.js#L220)

Create a new view collection. View collections are decorated with special methods for getting, setting and rendering views from that collection. Collections created with this method are not stored on `app.views` as with the [create](#create) method.

**Params**

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

**Example**

```js
var collection = app.collection();
collection.addViews({...}); // add an object of views
collection.addView('foo', {content: '...'}); // add a single view

// collection methods are chainable too
collection.addView('home.hbs', {content: 'foo <%= title %> bar'})
  .render({title: 'Home'}, function(err, res) {
    //=> 'foo Home bar'
  });

.create

Create a new view collection that is stored on the app.views object. For example, if you create a collection named posts, then all posts will be stored on app.views.posts, and a posts method will be added to app, allowing you to add posts to the collection using app.posts().

Params

• name {String}: The name of the collection. Plural or singular form.
• opts {Object}: Collection options
• loaders {String|Array|Function}: Loaders to use for adding views to the created collection.
• returns {Object}: Returns the collection instance for chaining.

Example

app.create('posts');
app.posts({...}); // add an object of views
app.post('foo', {content: '...'}); // add a single view

// collection methods are chainable too
app.post('home.hbs', {content: 'foo <%= title %> bar'})
  .render({title: 'Home'}, function(err, res) {
    //=> 'foo Home bar'
  });

.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': { ... }}

.matchView

Returns the first view from collection with a key that matches the given glob pattern.

Params

• collection {String}: Collection name.
• pattern {String}: glob pattern
• options {Object}: options to pass to micromatch
• returns {Object}

Example

var pages = app.matchView('pages', 'home.*');
//=> {'home.hbs': { ... }, ...}

var posts = app.matchView('posts', '2010-*');
//=> {'2015-10-10.md': { ... }, ...}

.matchViews

Returns any views from the specified collection with keys that match the given glob pattern.

Params

• collection {String}: Collection name.
• pattern {String}: glob pattern
• options {Object}: options to pass to micromatch
• returns {Object}

Example

var pages = app.matchViews('pages', 'home.*');
//=> {'home.hbs': { ... }, ...}

var posts = app.matchViews('posts', '2010-*');
//=> {'2015-10-10.md': { ... }, ...}

.handle

Handle a middleware method for view.

Params

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

Example

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

See the [route API documentation][route-api] for details on adding handlers and middleware to routes.

Params

• path {String}
• returns {Object} Route: for chaining

Example

app.create('posts');
app.route(/blog/)
  .all(function(view, next) {
    // do something with view
    next();
  });

app.post('whatever', {path: 'blog/foo.bar', content: 'bar baz'});

.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();
});

.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 of Templates 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();
});

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');

.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 fn property with the compiled function.

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'});

.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
});

Related projects

• assemble: Static site generator for Grunt.js, Yeoman and Node.js. Used by Zurb Foundation, Zurb Ink, H5BP/Effeckt,… 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
• template: Render templates using any engine. Supports, layouts, pages, partials and custom template types. Use template… more | homepage
• verb: Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… more | homepage

Running tests

Install dev dependencies:

$ npm i -d && npm test

Contributing

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

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2015 Jon Schlinkert Released under the MIT license.

This file was generated by verb-cli on September 13, 2015.