engine-nunjucks

More comprehensive consolidate-style engine support for nunjucks. Should work with express, assemble, verb, generate, update, and any other app that follows consolidate conventions.

Install

Install with npm:

$ npm install --save engine-nunjucks

Usage

var engine = require('engine-nunjucks');

API

.configure

Initialize Nunjucks with the given options and default settings from engine-nunjucks.

Params

• options {String}

Example

engine.configure([options]);

.addGlobal

Add a global value that will be available to all templates. Note: this will overwrite any existing global called name. Returns env (the nunjucks instance) for further method chaining.

Params

• name {String}
• returns {any} value

Example

engine.addGlobal(name, value);

.addExtension

Add a custom nunjucks extension. Also called "tags". This exposes the parser API and allows you to do anything you want with the template.

Params

• name {String}: The name of the extension to add
• returns {Function} fn: function

Example

env.addExtension(name, fn);

.compile

Asynchronously compile the given string, with the given options and callback. If no callback is passed, .compileSync is called with the given arguments.

Params

• str {Object}: The string to compile
• options {Object|Function}: Options object to pass to nunjucks or callback function
• cb {Function}: Callback function
• returns {undefined}

Example

engine.compile('foo  bar', function(err, fn) {
  console.log(fn({title: 'AAA'})); //=> 'foo AAA bar'
  console.log(fn({title: 'BBB'})); //=> 'foo BBB bar'
  console.log(fn({title: 'CCC'})); //=> 'foo CCC bar'
});

.compileSync

Synchronously compile the given string with options.

Params

• str {Object}: The string to compile
• options {Object}: Options object to pass to nunjucks
• returns {Function}: returns the compiled function

Example

var fn = engine.compileSync('foo  bar');
console.log(fn({title: 'AAA'})); //=> 'foo AAA bar'
console.log(fn({title: 'BBB'})); //=> 'foo BBB bar'
console.log(fn({title: 'CCC'})); //=> 'foo CCC bar'

.render

Asynchronously render the given template string with locals and callback.

Params

• str {String}
• options {Object|Function}: or callback function
• callback {Function}

Example

var locals = {name: 'engine-nunjucks'};
engine.render('abc engine-nunjucks xyz', locals, function(err, html) {
 console.log(html);
 //=> '[foo:bar]'
})

.renderString

Asynchronously or synchronously render the given str with locals and optional callback.

Params

• str {Object|Function}: The string to render or compiled function.
• locals {Object}
• returns {String}: Rendered string.

Example

var engine = require('engine-nunjucks');
engine.renderString('engine-nunjucks', {name: 'engine-nunjucks'}, function(err, str) {
  console.log(str);
  //=> 'engine-nunjucks'
});
// or
var str = engine.renderString('engine-nunjucks', {name: 'engine-nunjucks'});
console.log(str);
//=> 'engine-nunjucks'

.renderSync

Synchronously render the given str (or compiled function) with locals.

Params

• str {String|Function}: The string to render or compiled function.
• locals {Object}
• returns {String}: Rendered string.

Example

var engine = require('engine-nunjucks');
engine.renderSync('engine-nunjucks', {name: 'engine-nunjucks'});
//=> 'engine-nunjucks'

.renderFile

Render the contents of the file at the given filepath, with locals and optional callback.

Params

• filepath {String}
• options {Object|Function}: or callback function
• cb {Function}

.addFilter

Register custom filter name with the given fn. nunjucks filters are technically similar to handlebars helpers, but they're used differently in templates. This method is also aliased as .filter.

Params

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

Example

engine.addFilter('foo', function(str) {
  // do stuff to `str`
  return str;
});

.addFilters

Register multiple template filters. Also aliased as .filters.

Params

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

Example

engine.addFilters({
  foo: function() {},
  bar: function() {},
  baz: function() {}
});

.addAsyncFilter

Register an async filter function. Also aliased as .asyncFilter.

Params

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

Example

engine.addAsyncFilter('upper', function(str, next) {
  next(null, str.toUpperCase());
});

.addAsyncFilters

Register multiple async template filters. Also aliased as .asyncFilters.

Params

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

Example

engine.addAsyncFilters({
  foo: function() {},
  bar: function() {},
  baz: function() {}
});

.getFilter

Get a previously registered filter.

Params

• name {String}: Filter name
• returns {Function}: Returns the registered filter function.

Example

var fn = engine.getFilter('foo');

.getAsyncFilter

Get a previously registered async filter.

Params

• name {String}: Filter name
• returns {Function}: Returns the registered filter function.

Example

var fn = engine.getAsyncFilter('foo');

Default options

These are the actual default options used. These can be overridden with custom values on any of the methods.

var defaults = {
  ext: '.html',
  name: 'nunjucks',
  base: 'templates',
  throwOnUndefined: true,
  autoescape: false,
  watch: false
};

About

Related projects

• assemble: Get the rocks out of your socks! Assemble makes you fast at creating web projects… more | homepage
• generate: Command line tool and developer framework for scaffolding out new GitHub projects. Generate offers the… more | homepage
• update: Be scalable! Update is a new, open source developer framework and CLI for automating updates… 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.

Building docs

(This document was generated by verb-generate-readme (a verb generator), please don't edit the readme directly. Any changes to the readme must be made in .verb.md.)

To generate the readme and API documentation with verb:

$ npm install -g verb verb-generate-readme && verb

Running tests

Install dev dependencies:

$ npm install -d && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2016, Jon Schlinkert. Released under the MIT license.

This file was generated by verb, v0.9.0, on July 27, 2016.