Awesome

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

Params

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

Example

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

.addAsyncFilter

Params

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

Example

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

.addAsyncFilters

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

License

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