grunt-templatize
Super simple grunt task to convert one or more handlebars-like template files into a Javascript module. Supports AMD, commonjs, and namespaced module formats.
Templates support iteration using {{#each items}}{{/each}}
markup. For this to work, generated templates assume you have _.map
available, either via lodash
, underscore
, or other means. Configuration options are available to use your own map
-like function.
Simple Usage Example
First, make sure you have node.js and npm properly installed and working. You will also need to have grunt-cli
installed globally:
npm install grunt-cli -g
Create a new project folder with package.json
file and install dependencies from npm:
mkdir example
cd example
npm init
npm install grunt grunt-templatize --save-dev
mkdir templates
Create Gruntfile.js
in the project folder root:
module { 'use strict'; grunt; grunt; grunt; };
Create the following template files:
templates/header.tmplz
{{title}}{{body}}
templates/footer.tmplz
{{text}}
Run the following command:
grunt templatize
This will generate dist/templates.js
using the AMD module format with the following content:
;
Here is a beautified version of dist/templates.js
:
;
This AMD module can be imported into your application and the template can be compiled with code similar to this:
;
The module format of the destination file can be changed using a format
of amd
, commonjs
, or namesapce
. This is configured like this:
templatize: app: options: format: 'commonjs' src: 'templates/*.tmplz' dest: 'dist/templates.js'
Results using commonjs
format:
var _=;var p={return '<footer><a src="'+m0url+'">'+m0text+'</a></footer>';}{return '<header><h1>'+m0title+'</h1><div>'+m0body+'</div></header>';};moduleexports=p;
var _ = ;var p = { return '<footer><a src="'+m0url+'">'+m0text+'</a></footer>'; } { return '<header><h1>'+m0title+'</h1><div>'+m0body+'</div></header>'; };moduleexports=p;
Results using namespace
format:
!{roottemplatize=roottemplatize||{};var p=roottemplatize;roottemplatize{return '<footer><a src="'+m0url+'">'+m0text+'</a></footer>';};roottemplatize{return '<header><h1>'+m0title+'</h1><div>'+m0body+'</div></header>';};}this_;
!{ roottemplatize = roottemplatize || {}; var p = roottemplatize; roottemplatize { return '<footer><a src="'+m0url+'">'+m0text+'</a></footer>'; }; roottemplatize { return '<header><h1>'+m0title+'</h1><div>'+m0body+'</div></header>'; };}this_;
Support for multiple output target destination files:
grunt;
Full configuration including default values:
grunt;
HTML Fragments
By default, grunt-templatize will minify all of your HTML templates.
If you have templates that contain ill-formed HTML, as is often the case, then using the HTML Minifier feature will break your templates. This is because the minifier also makes the HTML well-formed by adding missing closing tags and removing extraneous closing tags.
To turn off the HTML minifier, set htmlminEnable: false
. Note that the option can be set differently for each target, as in this example:
grunt;
In many cases, HTML fragment templates are very short and can live on a single line. By setting htmlminMultiLines: true
, any single-line templates will not be minified, but any templates that contain more than one line will be minified.
grunt;
Any option can also be set for all targets using this style of options configuration:
templatize: options: templatize: htmlminEnable: false app: src: 'templates/*.tmplz' dest: 'dist/templates.js'
Iteration in Templates
Iteration is supported using {{#each item}}
and {{/each}}
tags in your templates. When these tags are used, the templatized output includes calls to the _.map()
function. If you are using Underscore or Lodash, this is available out of the box. If not, any implementation that is API compatible with the Underscore version should work.
Note that you may need to provide a custom prefix
and suffix
to use iteration effectively. For instance, to use Underscore instead of Lodash in an AMD module, you could use this configuration:
templatize: options: prefix: 'define(["underscore"],function(_){'
Here is an example of using the {{#each}}
iterator:
<h1>{{title}}</h1>
<ul>
{{#each items}}
<li>
<span>{{name}}</span>
<span>{{../foo}}</span>
</li>
{{/each}}
</ul>
This template should be given an object with this structure:
title: 'This is the title' foo: 'FOO' items: name: 'Item A' name: 'Item B'
Note that templatize supports nested {{#each}}
's, and within an inner scope, you can reference properties in the outer scope. This is done by using ../foo
notation. You can step up multiple scope levels by repeating the dots, i.e. ../../../foo
.
Partials in Templates
Templatize also supports template partials using the {{>partial}}
directive. Any template can be used as a partial and can be embedded within the output of another template. The model passed into a partial is the current context at the time the partial is called.
Here is an example of using a partial:
list.tmplz:
<h1>{{title}}</h1>
<ul>
{{#each items}}
{{>listitem}}
{{/each}}
</ul>
listitem.tmplz:
<li>
<span>{{name}}</span>
</li>
Note that you cannot reference properties in the calling function from within a partial. You can only access properties on the model that was passed to the partial.