templates
Advanced tools
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.
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 with npm:
$ npm install --save templates
var templates = require('templates');
var app = templates();
// 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'
});
This section describes API features that are shared by all Templates classes.
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'}
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`
};
});
The Templates class is the main export of the templates library. All of the other classes are exposed as static properties on 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();
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: '...'});
// or, create list from a collection
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.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);
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 settingssettings {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');
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: ['<%', '%>']
});
Get registered engine ext.
Params
ext {String}: The engine to get.Example
app.engine('hbs', require('engine-handlebars'));
var engine = app.getEngine('hbs');
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() {}
});
Register an async helper.
Params
name {String}: Helper name.fn {Function}: Helper functionExample
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() {}
});
Get a previously registered helper.
Params
name {String}: Helper namereturns {Function}: Returns the registered helper function.Example
var fn = app.getHelper('foo');
Get a previously registered async helper.
Params
name {String}: Helper namereturns {Function}: Returns the registered helper function.Example
var fn = app.getAsyncHelper('foo');
Return true if sync helper name is registered.
Params
name {String}: sync helper namereturns {Boolean}: Returns true if the sync helper is registeredExample
if (app.hasHelper('foo')) {
// do stuff
}
Return true if async helper name is registered.
Params
name {String}: Async helper namereturns {Boolean}: Returns true if the async helper is registeredExample
if (app.hasAsyncHelper('foo')) {
// do stuff
}
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() %>
API for the View class.
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('...')
});
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'});
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);
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`
});
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'}
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');
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;
};
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'}
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.Update context in a helper so that this.helper.options is
the options for that specific helper.
Params
context {Object}key {String}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.viewTypesreturns {Object}: Merged partialsMerge "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.viewTypescallback {Function}: Function that exposes err and partials parametersAPI for the Item class.
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('...')
});
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'
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'
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'}
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.Update context in a helper so that this.helper.options is
the options for that specific helper.
Params
context {Object}key {String}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.viewTypesreturns {Object}: Merged partialsMerge "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.viewTypescallback {Function}: Function that exposes err and partials parametersAPI for the Views class.
Create an instance of Views with the given options.
Params
options {Object}Example
var collection = new Views();
collection.addView('foo', {content: 'bar'});
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 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
});
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 the view instance.Example
collection.setView('foo', {content: 'bar'});
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');
Delete a view from collection views.
Params
key {String}returns {Object}: Returns the instance for chainingExample
views.deleteView('foo.html');
Load multiple views onto the collection.
Params
views {Object|Array}returns {Object}: returns the collection objectExample
collection.addViews({
'a.html': {content: '...'},
'b.html': {content: '...'},
'c.html': {content: '...'}
});
Load an array of views onto the collection.
Params
list {Array}returns {Object}: returns the views instanceExample
collection.addList([
{path: 'a.html', content: '...'},
{path: 'b.html', content: '...'},
{path: 'c.html', content: '...'}
]);
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');
Return true if the collection belongs to the given view type.
Params
type {String}: (renderable, partial, layout)Example
collection.isType('partial');
Alias for viewType
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'}
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.Update context in a helper so that this.helper.options is
the options for that specific helper.
Params
context {Object}key {String}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.viewTypesreturns {Object}: Merged partialsMerge "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.viewTypescallback {Function}: Function that exposes err and partials parametersFind 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');
// optionally pass a collection name as the second argument
var page = app.find('my-page.hbs', 'pages');
Get view key from the specified collection.
Params
collection {String}: Collection name, e.g. pageskey {String}: Template namefn {Function}: Optionally pass a renameKey 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);
});
Get all views from a collection using the collection's singular or plural name.
Params
name {String}: The collection name, e.g. pages or pagereturns {Object}Example
var pages = app.getViews('pages');
//=> { pages: {'home.hbs': { ... }}
var posts = app.getViews('posts');
//=> { posts: {'2015-10-10.md': { ... }}
API for the Collections class.
Create an instance of Collection with the given options.
Params
options {Object}Example
var collection = new Collection();
collection.addItem('foo', {content: 'bar'});
Add an item to the collection.
Params
key {String|Object}: Item name or objectval {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'});
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, 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'});
Get an item from collection.items.
Params
key {String}: Key of the item to get.returns {Object}Example
collection.getItem('a.html');
Remove an item from collection.items.
Params
key {String}returns {Object}: Returns the instance for chainingExample
items.deleteItem('abc');
Load multiple items onto the collection.
Params
items {Object|Array}returns {Object}: returns the instance for chainingExample
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 Listfn {Function}: Optional sync callback function that is called on each item.returns {Object}: returns the Collection instance for chainingExample
collection.addList([
{path: 'a.html', content: '...'},
{path: 'b.html', content: '...'},
{path: 'c.html', content: '...'}
]);
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'}
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.Update context in a helper so that this.helper.options is
the options for that specific helper.
Params
context {Object}key {String}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.viewTypesreturns {Object}: Merged partialsMerge "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.viewTypescallback {Function}: Function that exposes err and partials parametersAPI 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
options {Object}Example
var list = new List();
list.addItem('foo', {content: 'bar'});
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 the item instance.Example
collection.addItem('foo', {content: 'bar'});
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: '...'});
Load multiple items onto the collection.
Params
items {Object|Array}returns {Object}: returns the instance for chainingExample
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 Listfn {Function}: Optional sync callback function that is called on each item.returns {Object}: returns the List instance for chainingExample
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');
//=> true
Get a the index of a specific item from the list by key.
Params
key {String}returns {Object}Example
list.getIndex('foo.html');
//=> 1
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>>'
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>>'
Remove an item from the list.
Params
key {Object|String}: Pass an item instance (object) or item.key (string).Example
list.deleteItem('a.html');
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']);
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 chainingFilters 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';
});
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
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 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});
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'}
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.Update context in a helper so that this.helper.options is
the options for that specific helper.
Params
context {Object}key {String}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.viewTypesreturns {Object}: Merged partialsMerge "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.viewTypescallback {Function}: Function that exposes err and partials parametersAPI for the Group class.
Create an instance of Group with the given options.
Params
options {Object}Example
var group = new Group({
'foo': { items: [1,2,3] }
});
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');
// optionally pass a collection name as the second argument
var page = app.find('my-page.hbs', 'pages');
Get view key from the specified collection.
Params
collection {String}: Collection name, e.g. pageskey {String}: Template namefn {Function}: Optionally pass a renameKey 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);
});
Get all views from a collection using the collection's singular or plural name.
Params
name {String}: The collection name, e.g. pages or pagereturns {Object}Example
var pages = app.getViews('pages');
//=> { pages: {'home.hbs': { ... }}
var posts = app.getViews('posts');
//=> { posts: {'2015-10-10.md': { ... }}
Compile content with the given locals.
Params
view {Object|String}: View object.locals {Object}isAsync {Boolean}: Load async helpersreturns {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'});
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 propertyExample
var indexPage = app.page('some-index-page.hbs');
app.compileAsync(indexPage, function(err, view) {
// view.fn => compiled function
});
Render a view with the given locals and callback.
Params
view {Object|String}: Instance of Viewlocals {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
});
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'}
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.Update context in a helper so that this.helper.options is
the options for that specific helper.
Params
context {Object}key {String}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.viewTypesreturns {Object}: Merged partialsMerge "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.viewTypescallback {Function}: Function that exposes err and partials parametersControl the entire render cycle, with simple-to-use routes and middleware.
Example
var router = new app.Router();
var route = new app.Route();
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);
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);
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'});
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();
});
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 chainingExample
app.all(/\.hbs$/, function(view, next) {
// do stuff to view
next();
});
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 chainingExample
app.handler('onFoo');
// or
app.handler(['onFoo', 'onBar']);
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 chainingExample
app.handlers(['onFoo', 'onBar', 'onBaz']);
// or
app.handlers('onFoo');
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
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
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
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
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
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
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
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
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'
});
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 fixesfixed
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.
Added
extends and blocks! See dry documentation for details.Fixed
Fixed
Added
.addView (or the method created by .create, e.g. .page)Fixed
view object has engineStack and localsStack propertiesrenameKey option used when loading data. Use the namespace option instead.List bug that was caused collection helpers to explodeThere should be no breaking changes in this release. If you experience a regression, please create an issue.
app.getView() and app.find()Breaking changes
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
View and Item class have been externalized to modules vinyl-item and vinyl-view so they can be used in other libraries..ctx() method on helper context, to simplify merging context in non-built-in helpersdebug methods and related codepartial, renderable and layout).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.Templates.setup() method for initializing any setup code that should have access to the instance before any other use code is run.app.option.set, app.option.get and app.option.mergeAlthough 99% of users won't be effected by the changes in this release, there were some potentially breaking changes.
render and compile methods were streamlined, making it clear that .mergePartials should not have been renamed to mergePartialsSync. So that change was reverted.this.helper object to the context in helpers, which has the helper name and options that were set specifically for that helperthis.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..get, .set and .merge methods on this.options, this.context and the this object in helpers..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.engine can now be defined on app or a collection using using app.option('engine'), views.option('engine')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/#818view helper has been refactored completely. The helper is now async and renders the view before returning its content.isApp, isViews, isCollection, isList, isView, isGroup, and isItem static methods. All return true when the given value is an instance of the respective class.deleteItem method to List and Collection, and deleteView method to Views._.proto property which is only exposed for unit tests was renamed to _.plugin.isRegistered feature.getView, now that the method has been refactored to be faster.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.renderable view is rendered (e.g. page)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.isType method on view. Shouldn't be any breaking changes..error method to .formatErrormergeContext optionview and item as the second argumentisType method for checking the viewType on a collectiondefault layout was automatically applied to partials, causing an infinite loop in rare cases.Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
| Commits | Contributor |
|---|---|
| 753 | jonschlinkert |
| 105 | doowb |
| 1 | chronzerg |
(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 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
Jon Schlinkert
Copyright © 2017, Jon Schlinkert. Released under the MIT License.
This file was generated by verb-generate-readme, v0.6.0, on July 27, 2017.
FAQs
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.
The npm package templates receives a total of 18,101 weekly downloads. As such, templates popularity was classified as popular.
We found that templates demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.