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.
(TOC generated by verb using markdown-toc)
Install
Install with npm:
$ npm i templates --save
Features
- create custom view collections using
app.create('foo')
- register any template engine for rendering views
- register helpers
- partial support
- plugins and middleware
Example
This is just a very small glimpse at the templates
API!
var templates = require('templates');
var app = templates();
app.create('pages');
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) {
});
Usage
var templates = require('templates');
var app = templates();
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);
.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) {
});
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) {
return function(item) {
};
});
Application
This section describes the methods and features available on the main Templates
class.
This function is the main export of the templates module. Initialize an instance of templates
to create your application.
Params
Example
var templates = require('templates');
var app = templates();
Create a new list. See the list docs for more information about lists.
Params
opts
{Object}: List optionsreturns
{Object}: Returns the list
instance for chaining.
Example
var list = app.list();
list.addItem('abc', {content: '...'});
app.create('pages');
var list = app.list(app.pages);
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 optionsreturns
{Object}: Returns the collection
instance for chaining.
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 optionsreturns
{Object}: Returns the collection
instance for chaining.
Engines
Register a view engine callback fn
as ext
.
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'));
var engine = require('consolidate');
app.engine('jade', engine.jade);
app.engine('swig', engine.swig);
var swig = app.engine('swig');
Helpers
Register a template helper.
Params
name
{String}: Helper namefn
{Function}: Helper function.
Example
app.helper('upper', function(str) {
return str.toUpperCase();
});
Register multiple template helpers.
Params
helpers
{Object|Array}: Object, array of objects, or glob patterns.
Example
app.helpers({
foo: function() {},
bar: function() {},
baz: function() {}
});
Get a sync helper that was previously registered.
Params
name
{String}: Helper namefn
{Function}: Helper function.
Example
app.helper('upper', function(str) {
return str.toUpperCase();
});
Register an async helper.
Params
name
{String}: Helper name.fn
{Function}: Helper function
Example
app.asyncHelper('upper', function(str, next) {
next(null, str.toUpperCase());
});
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() {}
});
Register a namespaced helper group.
Params
helpers
{Object|Array}: Object, array of objects, or glob patterns.
Example
app.helperGroup('mdu', {
foo: function() {},
bar: function() {},
});
View
API for the View
class.
Create an instance of View
. Optionally pass a default object to use.
Params
Example
var view = new View({
path: 'foo.html',
content: '...'
});
Creates a context object from front-matter data, view.locals
and the given locals
object.
Params
locals
{Object}: Optionally pass locals to the engine.returns
{Object}: Returns the context object.
Example
var ctx = page.context({foo: 'bar'});
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'});
Asynchronously render a view.
Params
locals
{Object}: Optionally pass locals to the engine.returns
{Object} View
: instance, for chaining.
Example
view.render({title: 'Home'}, function(err, res) {
});
Return true if the view is the given view type
. Since types are assigned by collections, views that are "collection-less" will not have a type, and thus will always return false
(as expected).
Params
type
{String}: (renderable
, partial
, layout
)
Example
view.isType('partial');
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
view.data('a', 'b');
view.data({c: 'd'});
console.log(view.cache.data);
Build the context for the given view
and locals
.
Params
view
{Object}: The view being renderedlocals
{Object}returns
{Object}: The object to be passed to engines/views as context.
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
Item
API for the Item
class.
Create an instance of Item
. Optionally pass a default object to use.
Params
Example
var item = new Item({
path: 'foo.html',
content: '...'
});
Re-decorate Item methods after calling vinyl's .clone()
method.
Params
options
{Object}returns
{Object} item
: Cloned instance
Example
item.clone({deep: true});
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
item.data('a', 'b');
item.data({c: 'd'});
console.log(item.cache.data);
Build the context for the given view
and locals
.
Params
view
{Object}: The view being renderedlocals
{Object}returns
{Object}: The object to be passed to engines/views as context.
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
Collections
API for the Collections
class.
Create an instance of Collection
with the given options
.
Params
Example
var collection = new Collection();
collection.addItem('foo', {content: 'bar'});
Set an item on the collection. This is identical to addItem except setItem
does not emit an event for each item and does not iterate over the item queue
.
Params
key
{String|Object}: Item key or objectvalue
{Object}: If key is a string, value is the item object.returns
{Object}: returns the item
instance.
Example
collection.setItem('foo', {content: 'bar'});
Similar to setItem
, adds an item to the collection but also fires an event and iterates over the item queue
to load items from the addItem
event listener. An item may be an instance of Item
, if not, the item is converted to an instance of Item
.
Params
key
{String}value
{Object}
Example
var list = new List(...);
list.addItem('a.html', {path: 'a.html', contents: '...'});
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: '...'}
});
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: '...'}
]);
Get an item from the collection.
Params
key
{String}: Key of the item to get.returns
{Object}
Example
collection.getItem('a.html');
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
collection.data('a', 'b');
collection.data({c: 'd'});
console.log(collection.cache.data);
Build the context for the given view
and locals
.
Params
view
{Object}: The view being renderedlocals
{Object}returns
{Object}: The object to be passed to engines/views as context.
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
List
API for the List
class.
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
Example
var list = new List();
list.addItem('foo', {content: 'bar'});
Set an item on the collection. This is identical to addItem except setItem
does not emit an event for each item and does not iterate over the item queue
.
Params
key
{String|Object}: Item key or objectvalue
{Object}: If key is a string, value is the item object.returns
{Object}: returns the item
instance.
Example
collection.setItem('foo', {content: 'bar'});
Similar to setItem, adds an item to the list but also fires an event and iterates over the item queue
to load items from the addItem
event listener. If the given item is not already an instance of Item
, it will be converted to one before being added to the items
object.
Params
key
{String}value
{Object}returns
{Object}: Returns the instance of the created Item
to allow chaining item methods.
Example
var items = new Items(...);
items.addItem('a.html', {path: 'a.html', contents: '...'});
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: '...'}
});
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);
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');
Get a the index of a specific item from the list by key
.
Params
key
{String}returns
{Object}
Example
list.getIndex('foo.html');
Get a specific item from the list by key
.
Params
key
{String}returns
{Object}
Example
list.getItem('foo.html');
Remove an item from the list.
Params
items
{Object}: Object of views
Example
var list = new List(...);
list.addItems({
'a.html': {path: 'a.html', contents: '...'}
});
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
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');
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');
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});
Group
API for the Group
class.
Create an instance of Group
with the given options
.
Params
Example
var group = new Group({
'foo': { items: [1,2,3] }
});
Lookups
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 findcolleciton
{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');
var page = app.find('my-page.hbs', 'pages');
Get view key
from the specified collection
.
Params
collection
{String}: Collection name, e.g. pages
key
{String}: Template namefn
{Function}: Optionally pass a renameKey
functionreturns
{Object}
Example
var view = app.getView('pages', 'a/b/c.hbs');
var view = app.getView('pages', 'a/b/c.hbs', function(fp) {
return path.basename(fp);
});
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');
var posts = app.getViews('posts');
Rendering
Compile content
with the given locals
.
Params
view
{Object|String}: View object.locals
{Object}isAsync
{Boolean}: Load async helpersreturns
{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({title: 'Foo'});
view.fn({title: 'Bar'});
view.fn({title: 'Baz'});
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) {
});
Context
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);
Build the context for the given view
and locals
.
Params
view
{Object}: The view being renderedlocals
{Object}returns
{Object}: The object to be passed to engines/views as context.
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
Routes and middleware
Handle a middleware method
for view
.
Params
method
{String}: Name of the router method to handle. See router methodsview
{Object}: View objectcallback
{Function}: Callback functionreturns
{Object}
Example
app.handle('customMethod', view, callback);
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} Route
: for chaining
Example
app.create('posts');
app.route(/blog/)
.all(function(view, next) {
next();
});
app.post('whatever', {path: 'blog/foo.bar', content: 'bar baz'});
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) {
next();
});
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) {
next();
});
app.onLoad('/blog/:title', function(view, next) {
next();
});
Code coverage
As of January 15, 2016, code coverage is 100%.
Statements : 100% (1162/1162)
Branches : 100% (475/475)
Functions : 100% (160/160)
Lines : 100% (1141/1141)
History
v0.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.
v0.9.5
- Fixes error messages when no engine is found for a view, and the view does not have a file extension.
v0.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)
v0.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.
v0.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
v0.5.1
- fixes bug where
default
layout was automatically applied to partials, causing an infinite loop in rare cases.
Related projects
- assemble: Assemble is a powerful, extendable and easy to use static site generator for node.js. Used… 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
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
License
Copyright © 2016 Jon Schlinkert
Released under the MIT license.
This file was generated by verb on January 15, 2016.