grunt-template-module

Precompile templates to a file and/or expose the templates through a module.

This is an awful lot like the existing grunt-contrib-jst grunt task. But it has a few differences. One is that it supports underscore, lodash and ejs template providers. The real key feature is that it allows you to compile these templates into a module that exposes each compiled template from an exports property. What this means is that if you provide the following configuration:

template-module: {
    myTemplates:{
        files: {
            "tmp/module_jst.js": ["test/fixtures/template.html"]
        }
        options: {
            module: true
        }
    }
}

You would end up with an entry in module_jst.js that looks like:

exports["tmp/module_jst.js"] = function(obj){...

I know. You're wondering why do such a thing? Doesn't contrib-jst offer an AMD wrapper? Yes, it does, but it is a very noisy way to get at it on the server. As well, if you use browserify, this will play much better with the compiled browserified (is that a word?) output.

So there you have it. Browserify and server happiness for underscore/lodash and EJS templates. And backward compatibility with contrib-jst.

And one more thing: prettify uses beautify instead. Let's try that again. The prettify option in the original used some very simple code to pretty things up. Instead it now uses node-beautify.

Getting Started

If you haven't used grunt before, be sure to check out the Getting Started guide, as it explains how to create a gruntfile as well as install and use grunt plugins. Once you're familiar with that process, install this plugin with this command:

npm install grunt-template-module

template-module task

Run this task with grunt template-module at the command line.

This task is a [multi task][] so any targets, files and options should be specified according to the [multi task][] documentation. [multi task]: https://github.com/gruntjs/grunt/wiki/Configuring-tasks

Usage

template-module: {
  compile: {
    options: {
      module: true,
      provider: 'lodash'
    },
    files: {
      "path/to/compiled/templates.js": ["path/to/source/**/*.html"]
    }
  }
}

Options

module

Type: 'Boolean' Default: true

When true, the module behavior described above will be delivered with love and chocolate.

provider

Type 'String' Default: underscore

The name of the template engine to use. Allowable values are underscore lodash and ejs

useStrict

Type boolean Default: false

Enable strict mode by adding 'strict mode'; to the output

options: {
  useStrict: true
}

prettify

Type: boolean Default: false

When doing a quick once-over of your compiled template file, it's nice to see an easy-to-read format. This will accomplish that.

options: {
  prettify: true
}

prettifyOptions

Type: object

When you set prettify to true, you can pass options to the beautify module in this object.

options: {
  prettify: true,
  prettifyOptions:{
      indentSize: 4,
      indentChar: '\t',
      maxPreserveNewlines: 1
  }
}

single

Type: boolean Default: false

If enabled and there is only one soruce file, then export the template as a single function. e.g. module.exports = function( .... );

options: {
  single: true
}

namespace

Type: String Default: 'JST'

The namespace in which the precompiled templates will be asssigned. Use dot notation (e.g. App.Templates) for nested namespaces. This is not used when module is set to true.

processName

Type: function Default: null

This option accepts a function which takes one argument (the template filepath) and returns a string which will be used as the key for the precompiled template object. The example below stores all templates on the default JST namespace in capital letters.

options: {
  processName: function(filename) {
    return filename.toUpperCase();
  }
}

templateSettings

Type: Object Default: null

The settings passed to the template engine when compiling templates. The options are template engine specific.

template-module: {
  compile: {
    options: {
      templateSettings: {
        interpolate : /\{\{(.+?)\}\}/g
      }
    },
    files: {
      "path/to/compiled/templates.js": ["path/to/source/**/*.html"]
    }
  }
}

lintExpr

Type: Object Default: null

If you want to add a comment for lint or hint declarations, you can use this setting to declare the directives.

template-module: {
  compile: {
    options: {
     lintExpr : {
        unused : false,
        asi : true,
        expr : true
     },
    },
    files: {
      "path/to/compiled/templates.js": ["path/to/source/**/*.html"]
    }
  }
}

which would produce /*jshint unused:false, asi:true, expr:true*/ and add it to the bottom of the file.

requireProvider

Type: boolean Default: true

When compiling as with module: true, by default we'll prepend var _ = require('underscore'); to the output. This is fine if you're bundling your provider (underscore, lodash, or ejs) in your build.

However, you might not want to bundle your provider, for example if you want to load lodash from a CDN. In that case, you'll want to set requireProvider: false

amdWrapper

Type: boolean | string Default: false

With Require.js and a pre-compiled template.js you want the templates to be wrapped in a define. This will wrap the output in:

define(function() {
  //Templates
  return this["NAMESPACE"];
});

Example:

options: {
  amdWrapper: true
}

If you want a specific define, you can provide it as string:

options: {
  amdWrapper: 'define("templates", ["i18n"], function(__) {'
}

Will result in:

define("templates", ["i18n"], function(__) {
  //Templates
  return this["NAMESPACE"];
});

• This is not used when module is set to true.*

Release History

• 2012-12-24 v0.1.0 Initial release
• 2012-12-25 v0.1.1 Fixed documentation and clarified names
• 2014-06-12 v0.3.0 Updated dependencies