This is a grunt plugin to render nunjucks
templates and strings. It takes data in JSON
or YAML
format and allows to configure nunjucks in
Grunt tasks.
This plugin requires Grunt ~0.4.1
and Node ~0.10.0
. Please first have a look at the
Getting Started guide of Grunt.
You may install this plugin with this command:
npm install grunt-nunjucks-render --save-dev
Once the plugin is installed, it may be enabled inside your Gruntfile.js
with this line of JavaScript:
grunt.loadNpmTasks('grunt-nunjucks-render');
In your project's Gruntfile, add a section named nunjucks_render
to the data object
passed into grunt.initConfig()
:
grunt.initConfig({
nunjucks_render: {
options: {
// task global options go here
},
your_target: {
options: {
// target specific options go here
},
files: [
{
data: // path to JSON or YAML file(s)
src: // path to template file(s)
dest: // path to output destination file(s)
str: // direct string(s) to parse (before templates by default)
str_prepend: // direct string(s) to parse and concat before templates
str_append: // direct string(s) to parse and concat after templates
}
]
}
}
});
See the dedicated page to learn
how to build your files
objects. Note that some properties are added here:
data
to define a list of files to get the parsing data,str
, str_prepend
and str_append
to define some raw strings to parse and concatenate
to the final rendering.A special nunjucks environment loader
is designed by the plugin to use a full set of options when searching templates (original
and included ones). The loader is defined in lib/loader.js
.
The template_path
environment variable will always contain the path of the current parsed
template (the current file), even for inclusions. The template_date
environment variable
will always contain the date of the current parsing, even for inclusions.
The plugin embeds the date-filter natively to let you write formated dates:
{{ my_date | date() }} // with default format
{{ my_date | date('YYY') }} // with custom format
Options can be defined globally for the nunjucks_render
task or for each target.
The target options will always overload global settings.
A "template" here is a raw template, defined as the src
item of a target files, or a
nunjucks included template.
searchPaths
String
, Array
"."
(i.e. relative to your Gruntfile.js
)baseDir
is defined and the template is found in it, this file will be used.baseDir
String
"."
(i.e. relative to your Gruntfile.js
)name
entry.extensions
String
, Array
".j2"
(for jinja2){% include my-partial %}
instead of {% include my-partial.j2 %}
.autoescape
Boolean
false
watch
Boolean
true
data
Object
, String
(filename), Array
(array of filenames)null
data
value for a whole task or a target. This will
be merged with "per-file" data (which have precedence).processData
Function
null
name
RegExp
, Function
/.*/
asFunction
Boolean
false
env
nunjucks.Environment
null
strAdd
String
in "prepend" or "append""prepend"
str
files entry. By default, strings will be
parsed and prepended to final rendering (i.e. displayed before templates contents).
Note that when this argument is prepend
, the str
items will be added AFTER any
str_prepend
other items while if it is append
, the str
items will be added
BEFORE any other str_append
items.strSeparator
String
"\n"
You can have a look at the Gruntfile.js
of the plugin for various usage examples.
Define a base path for all parsed files:
options: {
baseDir: 'templates/to/read/'
},
files: {
'file/to/output-1.html': 'file-1.j2',
'file/to/output-2.html': 'file-2.j2',
'file/to/output-3.html': 'file-3.j2'
}
Define a global data
table for all parsed files:
options: {
data: {
name: "my name",
desc: "my description"
}
},
files: {
'file/to/output.html': 'template/to/read.j2'
}
Define a global JSON data file for all parsed files:
options: {
data: 'commons.json'
},
files: {
'file/to/output-1.html': 'template/to/read-1.j2',
'file/to/output-2.html': 'template/to/read-2.j2',
'file/to/output-3.html': 'template/to/read-3.j2'
}
Define a global data
table for all targets, over-written by a "per-target" data:
options: {
data: {
name: "my name",
desc: "my description"
}
},
my_target: {
files: {
data: { desc: "my desc which will over-write global one" },
src: 'template/to/read.j2',
dest: 'file/to/output.html'
}
}
Define a full set of grunt files:
files: [
{
expand: true,
src: 'template/to/read-*.j2',
data: 'common-data.json',
dest: 'dest/directory/'
}
]
Usage of the str
argument:
files: {
data: { desc: "my desc which will over-write global one" },
src: 'template/to/read.j2',
dest: 'file/to/output.html',
str: "My nunjucks string with var: {{ username }}"
}
files: {
data: { desc: "my desc which will over-write global one" },
src: 'template/to/read.j2',
dest: 'file/to/output.html',
str: [ "My first nunjucks string with var: {{ username }}", "My second nunjucks string with var: {{ username }}" ]
}
As this module defines "non-tasked" functions, you can use the followings in your own tasks or modules.
NunjucksRenderFile
var NunjucksRenderFile = require('grunt-nunjucks-render/lib/render-file');
var content = NunjucksRenderFile( filepath , data[ , options ][ , nunjucks.Environment ]);
NunjucksRenderString
var NunjucksRenderString = require('grunt-nunjucks-render/lib/render-string');
var content = NunjucksRenderString( str , data[ , options ][ , nunjucks.Environment ]);
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.