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

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
  }
}

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.

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

davidbeale / grunt-template-module Goto Github PK