Awesome
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.
Table of Contents
(TOC generated by verb using markdown-toc)
Install
Install with npm:
$ npm install --save templates
Features
- templates are vinyl files
- rich plugin support, use any base plugin!
- render templates with any template engine, including nunjucks, handlebars, lodash and any consolidate engine!
- helpers: support for sync and async
- templates collections support
- partials and includes
- layouts
- pages
- custom template "types"
- pagination
- permalinks
- middleware can be used to tranform files at any stage in the render cycle
- pagination
- Much more!
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 theuse
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
:
- Item: Collection item, powered by vinyl-item.
- View: Collection item, powered by vinyl-view.
- List
- Views:
- Collection: Base collections class. Use this if you need to customize the render cycle, middleware stages, and so on.
- Group
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 optionsreturns
{Object}: Returns thelist
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 optionsreturns
{Object}: Returns thecollection
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 optionsreturns
{Object}: Returns thecollection
instance for chaining.
.setup
Expose static setup
method for providing access to an instance before any other code is run.
Params
app
{Object}: Application instancename
{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}: orsettings
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 namefn
{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 namereturns
{Function}: Returns the registered helper function.
Example
var fn = app.getHelper('foo');
.getAsyncHelper
Get a previously registered async helper.
Params
name
{String}: Helper namereturns
{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 namereturns
{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 namereturns
{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 ofTemplates
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 renderedlocals
{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 ofviewTypes
to include onoptions.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 ofviewTypes
to include onoptions.viewTypes
callback
{Function}: Function that exposeserr
andpartials
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 ofTemplates
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 renderedlocals
{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 ofviewTypes
to include onoptions.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 ofviewTypes
to include onoptions.viewTypes
callback
{Function}: Function that exposeserr
andpartials
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 objectvalue
{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 theview
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 objectvalue
{Object}: If key is a string, value is the view object.returns
{Object}: returns theview
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 thecollection
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 theviews
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 ofTemplates
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 renderedlocals
{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 ofviewTypes
to include onoptions.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 ofviewTypes
to include onoptions.viewTypes
callback
{Function}: Function that exposeserr
andpartials
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 findcolleciton
{String}: Optionally pass a collection name (e.g. pages)returns
{Object|undefined}: Returns the view if found, orundefined
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 namefn
{Function}: Optionally pass arenameKey
functionreturns
{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
orpage
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 objectval
{Object}: Item object, whenkey
is a string.returns
{Object}: returns theitem
instance.
Events
emits
:item
With the createditem
andcollection
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 objectval
{Object}: Item object, whenkey
is a string.returns
{Object}: returns thecollection
instance.
Events
emits
:item
With the createditem
andcollection
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 ofList
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 ofTemplates
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 renderedlocals
{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 ofviewTypes
to include onoptions.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 ofviewTypes
to include onoptions.viewTypes
callback
{Function}: Function that exposeserr
andpartials
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 objectvalue
{Object}: If key is a string, value is the item object.returns
{Object}: returns theitem
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 ofList
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 ofList
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 theitem
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 anitem
instance (object) oritem.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 newList
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 ofTemplates
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 renderedlocals
{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 ofviewTypes
to include onoptions.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 ofviewTypes
to include onoptions.viewTypes
callback
{Function}: Function that exposeserr
andpartials
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 findcolleciton
{String}: Optionally pass a collection name (e.g. pages)returns
{Object|undefined}: Returns the view if found, orundefined
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 namefn
{Function}: Optionally pass arenameKey
functionreturns
{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
orpage
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 helpersreturns
{Object}: View object with compiledview.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 exposeserr
and theview
object with compiledview.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 ofView
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 ofTemplates
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 renderedlocals
{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 ofviewTypes
to include onoptions.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 ofviewTypes
to include onoptions.viewTypes
callback
{Function}: Function that exposeserr
andpartials
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 methodsfile
{Object}: View objectcallback
{Function}: Callback functionreturns
{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 featureschanged
: for changes in existing functionalitydeprecated
: for once-stable features removed in upcoming releasesremoved
: for deprecated features removed in this releasefixed
: 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 hasengineStack
andlocalsStack
properties
0.24.0
- Bumps base-data which removed
renameKey
option used when loading data. Use thenamespace
option instead.
0.23.0
- Bumps [base-engine][] to fix a bug in engine-cache.
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()
andapp.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
andItem
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
- Numerous dependency updates
0.18.0
- Fixes inheritance bug that only manifests in node v0.4.0
- Improved error handling in routes
0.17.0
- Removed
debug
methods and related code - Improve layout handling with respect to template types (
partial
,renderable
andlayout
) - Update dependencies
0.16.0
- Improved context handling
- Ensure collection middleware is handled after app middleware
0.15.0
- removes
.removeItem
method that was deprecated in v0.10.7 fromList
.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
andapp.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
andcompile
methods were streamlined, making it clear that.mergePartials
should not have been renamed tomergePartialsSync
. 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 onthis.context.view
, but it makes sense to add this to the root of the context as a convenience. We will deprecatethis.context.view
in a future version. - Helper context:
.get
,.set
and.merge
methods onthis.options
,this.context
and thethis
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
- Adds helper methods, .hasAsyncHelper, .hasHelper, .getAsyncHelper, and .getHelper
- Ensures that both collection and app routes are handled when both are defined for a view
0.11.0
- Default
engine
can now be defined onapp
or a collection using usingapp.option('engine')
,views.option('engine')
- Default
layout
can now defined usingapp.option('layout')
,views.option('layout')
. No changes have been made toview.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
, andisItem
static methods. All return true when the given value is an instance of the respective class. - Adds
deleteItem
method to List and Collection, anddeleteView
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
andlocals
, sincectx
(the parameter that was removed) was technically being merged in twice.
0.8.0
- Exposes
isType
method onview
. 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
anditem
as the second argument - adds
isType
method for checking theviewType
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.