grunt-hogan

a grunt task to compile/precompile hogan templates

npm install grunt-hogan
17 downloads in the last day
85 downloads in the last week
249 downloads in the last month

grunt-hogan

a grunt task to precompile hogan templates

Getting Started

NOTE: This documentation is for grunt version 0.4+. To work with version 0.3.x, see here

Install this grunt plugin next to your project's Gruntfile.js with: npm install grunt-hogan --save-dev

Then add this line to your project's Gruntfile.js:

grunt.loadNpmTasks('grunt-hogan');

To precompile a single template into a single output file:

grunt.initConfig({
    //...
    hogan: {
        //desired target name
        mytarget : {
          //path to input template
          template : "view/chair.hogan",
          //output path, relative to Gruntfile.js
          output : "bandanna.js"
        }
    },
    //...
});

Multiple input templates via patterns

grunt.initConfig({
    //...
    hogan: {
        //desired target name
        mytarget : {
          //Wildcard of desired templates
          templates : "view/**/*.hogan",
          //output destination
          output : "hulkingup.js"
        }
    },
    //...
});

Multiple input template patterns

//...
mytarget : {
    //...
    templates : ["view/wwf/*.hogan", "view/wcw/*.hogan"],
    //...
}
//...

"Binders"

By default, the all compiled templates in a single grunt target will be "bound" together by the default "binder" (which is itself a pre-compiled template). The "default" binder generates javascript that is designed to work both as a node.js module and in the browser via a <script/> tag. Other built-in binders are:

  • "hulk" - should output similarly to hogan's "hulk" command line tool...which is "vanilla" javascript
  • "nodejs" - exposes compiled templates as a node.js module
  • "amd" - exposes compiled templates in amd format
  • "revealing" - exposes compile templates via the revealing module pattern

You can also create your own binder templates to support other usages. See "Custom Binders" section below.

To specify a binder, use a "binderName" directive:

//...
mytarget : {
    templates : "view/**/*.hogan",
    output : "hulkingup.js",
    binderName : "hulk"
}
//...

Custom Binders

To specify a custom binder, supply a path for the "binder" attribute (note that this differs from the "binderName" in examples above) that resolves to a binder module:

//...
binder : __dirname + "/my/custom/binder.js"
//...

See the custombinder_bootstrap and multi_custombinder targets in the example gruntfile for futher detail on creating and using custom binders.

Using precompiled templates

As of version 0.2.2, all built in binders create javascript that functions similarly in intention, but varies with respect to the target use.

Given a precompile task like:

mytarget : {
  templates : ['view/fist.html', 'view/foe.html', 'view/what.you.gonna.do.html'],
  output : "templates.js",
  binderName : 'nodejs'
}

A node.js application could:

//Load the module
var templates = require('./templates.js');

//Render a template with a context object
var html1 = templates.fist({knuckles: true});

//Render a template with context and partial templates
var html2 = templates.foe({}, {partialName: partialTemplateFromSomewhere});

//Render a template with a non-variable-like name
var html3 = templates['what.you.gonna.do']({context:'catchphrase'});

All of the binders (with the exceptions of special case binders like the bootstrap and "hulk") seek to expose the full api of the template render in this manner.

Also, if a partial parameter is not specified, the default render behavior is to make all the other templates in the binder ("sibling templates") available as partials in the render.

Other templates will vary slightly in their syntax to support their purpose.

Examples

Contributing

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.

Release History

  • 0.2.- - in progress
  • 0.2.2 - Binder template overhaul
    • Added partial support on render functions
    • Sibling partials by default
    • Breaking changes for precompiled template API
  • 0.2.1 - AMD Binder
    • Now supports use of "sibling templates" (defined within the same binder) as partials
    • Breaking change - Now exports a render function instead of the full template
  • 0.1.1 - Breaking Changes and Custom Binder Support
    • "render" directive has been discarded
    • "options" notation has been discarded (supply attributes directly as keys on the target)

Acknowledgements

  • a comment by "baz" here pointed me in the right direction

License

Copyright (c) 2013 Elliott B. Edwards
Licensed under the MIT license.

npm loves you