Skip to content

Latest commit

 

History

History
147 lines (108 loc) · 4.9 KB

README.md

File metadata and controls

147 lines (108 loc) · 4.9 KB
Raw

grunt-contrib-handlebars Build Status

Precompile Handlebars templates to JST file.

Note that this plugin has not yet been released, and only works with the latest bleeding-edge, in-development version of grunt. See the When will I be able to use in-development feature 'X'? FAQ entry for more information.

Getting Started

If you haven't used grunt before, be sure to check out the Getting Started guide.

From the same directory as your project's Gruntfile and package.json, install this plugin with the following command:

npm install grunt-contrib-handlebars --save-dev

Once that's done, add this line to your project's Gruntfile:

grunt.loadNpmTasks('grunt-contrib-handlebars');

If the plugin has been installed correctly, running grunt --help at the command line should list the newly-installed plugin's task or tasks. In addition, the plugin should be listed in package.json as a devDependency, which ensures that it will be installed whenever the npm install command is run.

The handlebars task

Overview

In your project's Gruntfile, add a section named handlebars to the data object passed into grunt.initConfig().

grunt.initConfig({
  handlebars: {
    options: {
      // Task-specific options go here.
    },
    your_target: {
      // Target-specific file lists and/or options go here.
    },
  },
})

Options

files

Type: Object

This defines what files this task will process and should contain key:value pairs.

The key (destination) should be an unique filepath (supports grunt.template) and the value (source) should be a filepath or an array of filepaths (supports minimatch).

Note: Values are precompiled to the namespaced JST array in the order passed.

namespace

Type: string Default: 'jst'

The namespace in which the precompiled templates will be assigned. Use dot notation (e.g. App.Templates) for nested namespaces.

Example:

options: {
  namespace: 'MyApp.Templates'
}

wrapped

Type: Boolean Default: false

Determine if preprocessed template functions will be wrapped in Handlebars.template function.

processName

Type: function

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();
  }
}

processPartialName

Type: function

This option accepts a function which takes one argument (the partial filepath) and returns a string which will be used as the key for the precompiled partial object when it is registered in Handlebars.partials. The example below stores all partials using only the actual filename instead of the full path.

options: {
  processPartialName: function(filePath) { // input:  templates/_header.hbs
    var pieces = filePath.split("/");
    return pieces[pieces.length - 1];      // output: _header.hbs
  }
}

Note: If processPartialName is not provided as an option the default assumes that partials will be stored by stripping trailing underscore characters and filename extensions. For example, the path templates/_header.hbs will become header and can be referenced in other templates as {{> header}}.

partialRegex

Type: Regexp Default: /^_/

This option accepts a regex that defines the prefix character that is used to identify Handlebars partial files.

// assumes partial files would be prefixed with "par_" ie: "par_header.hbs"
options: {
  partialRegex: /^par_/
}

Examples

handlebars: {
  compile: {
    options: {
      namespace: "JST"
    },
    files: {
      "path/to/result.js": "path/to/source.hbs",
      "path/to/another.js": ["path/to/sources/*.hbs", "path/to/more/*.hbs"]
    }
  }
}

Release History

  • 2012-10-11 - v0.3.2 - Rename grunt-contrib-lib dep to grunt-lib-contrib.
  • 2012-10-02 - v0.3.1 - Bugfix default processPartialName.
  • 2012-09-22 - v0.3.0 - Options no longer accepted from global config key.
  • 2012-09-15 - v0.2.3 - Support for nested namespaces.
  • 2012-09-11 - v0.2.2 - Escape single quotes in filenames.
  • 2012-09-09 - v0.2.0 - Refactored from grunt-contrib into individual repo.

-- Task submitted by Tim Branyen.

Generated on Thu Oct 18 2012 22:28:59.