Skip to content

Latest commit

 

History

History
165 lines (136 loc) · 6.83 KB

README.md

File metadata and controls

165 lines (136 loc) · 6.83 KB
Raw

grunt-compile-handlebars Build Status

Compiles handlebar templates, outputs static HTML

Getting Started

Install this grunt plugin next to your project's grunt.js gruntfile with: npm install grunt-compile-handlebars

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

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

Documentation

Who

patrick kettner - a web developer who consistently worked with large static data sets.

What

grunt-compile-handlebars takes in a handlebars tempalte (and optionally static pre and post html), runs a dataset over it, and outputs static html.

Where

inside of a grunt task. I assume you know what gruntjs is, but if not - gruntjs.com

When

You have ton of data that rarely changes that you want to template.

How

There are a lot of different ways to input data, it accepts most any dynamic and static input. Heres a few of the ways you can use it

'compile-handlebars': {
    allStatic: {
      preHTML: 'test/fixtures/pre-dev.html',
      postHTML: 'test/fixtures/post-dev.html',
      template: 'test/fixtures/template.handlebars',
      templateData: 'test/fixtures/data.json',
      output: 'tmp/allStatic.html'
    },
    dynamicTemplate: {
      template: '<h1>{{salutation}}{{punctuation}} {{location}}</h1>',
      templateData: 'test/fixtures/data.json',
      output: 'tmp/dynamicTemplate.html'
    },
    dynamicTemplateData: {
      template: 'test/fixtures/template.handlebars',
      templateData: {
          "salutation": "Hallo",
          "punctuation": ",",
          "location": "Welt"
      },
      output: 'tmp/dynamicTemplateData.html'
    },
    dynamicPre: {
      preHTML: '<header>INLINE HEADER</header>',
      template: 'test/fixtures/template.handlebars',
      templateData: 'test/fixtures/data.json',
      output: 'tmp/dynamicPre.html'
    },
    dynamicPost: {
      postHTML: '<footer>INLINE HEADER</footer>',
      template: 'test/fixtures/template.handlebars',
      templateData: 'test/fixtures/data.json',
      output: 'tmp/dynamicPost.html'
    },
    allArray: {
      template: ['test/fixtures/deep/spanish.handlebars', 'test/fixtures/deep/deeper/portuguese.handlebars'],
      templateData: ['test/fixtures/deep/spanish.handlebars', 'test/fixtures/deep/deeper/portuguese.json'],
      output: ['tmp/deep/spanish.html','tmp/deep/deeper/portuguese.html'],
      helpers: ['test/helpers/super_helper.js'],
      partials: ['test/fixtures/deep/shared/foo.handlebars']
   },
    globbedTemplateAndOutput: {
      template: 'test/fixtures/deep/**/*.handlebars',
      templateData: 'test/fixtures/deep/**/*.json',
      output: 'tmp/deep/**/*.html'
    },
    globalJsonGlobbedTemplate: {
      template: 'test/fixtures/deep/**/*.handlebars',
      templateData: 'test/fixtures/deep/**/*.json',
      output: 'tmp/deep/**/*.html',
      helpers: 'test/helpers/**/*.js',
      partials: 'test/fixtures/deep/shared/**/*.handlebars',
      globals: [
        'test/globals/info.json',
        'test/globals/textspec.json'
      ]
    }
}

The available configuration options are as follows

Unless otherwise noted, all configurable values can be represented as

  • a string representing the path to a specific file
  • a string representing the path to a globbed representation of the files, matched up against the values resolved from the template configuration
  • an array of literal paths, globbed paths, or a combination of the two

template - The template fed to handlebars. In addition to the normal configurable values, it can also be an inline string representation of a template (e.g. raw html and handlebars).

preHTML - Static text to be inserted before the compiled template postHTML - Static text to be inserted after the compiled template

__templateData ~~ The data being fed to compiled template, in addition to the normal configurable values, this can be

  • an inline string representation of a data (I don't know why you would do that though, when you can do...)
  • an inline JSON representation of a data

output - the file(s) that handlebars saves the files to. This can be globals - globals that can be included, useful for when you have template specific data, but want some data available to all templates helpers - handlebars helpers partials - handlebars partials

registerFullPath - normally, helpers and partials are registered under their basename, rather than their path (e.g. partial at partials/deep/awesomePartial.handlebars is registered as {{> awesomePartial}}). When set to true, helpers and partials are registered under their full paths (e.g. {{> partials/deep/awesomePartial}}), to prevent clobbering after resolving globbed values.

A note on globing

When you specify templates using globs, the values from template are used to create the values for output, for example, if your file structure looks like this

|-foo
  |-bar.handlebars
  |-baz.handlebars
  |-bar.json
  |-baz.json

and your configuration looks like this

{
  "template": "./foo/*.handlebars",
  "templateData": "./foo/*.json",
  "output":  "./foo/*.html"
}

the output would be ./foo/bar.html and ./foo/baz.html

Why

I had to work with several hundred repeated data structures that never changed. Keeping them all in html was silly, but pushing out a template engine for the end user to compile the same information multiple times was even sillier. This allows you to have your templated cake and eat it too.

Release History

  • 0.7.5 - Redford - add registerFullPath option to prevent partial/helper registration clobbering, update README
  • 0.7.4 - M. Jean - don't send objects to handlebars.compile, code cleanup
  • 0.7.3 - Cousin Ben - switch from require to readFile to allow for html in partials
  • 0.7.2 - Bernice - @stimmins improved handling of templateData and globals
  • 0.7.1 - Margaret - fix 0.8 compatibility
  • 0.7.0 - Rosemary - Allow for arrays instead of globbing, remove depreicated grunt methods
  • 0.6.3 - Pelé - @mattcg fixed an issue with large amounts of templates
  • 0.6.2 - Dignan - @goette added support for a global json config
  • 0.6.1 - Grace - @robinqu added support for handlebars partials
  • 0.6.0 - Future Man - added globbing, lots more test
  • 0.4.0 - Oseary - upgraded to grunt 0.4, removed extra tasks, added tests
  • 0.0.2 - Inez - changed to grunt's native json parser (thanks to @sebslomski). Updated Readme
  • 0.0.1 - Dudley - Initial commit

License

Copyright (c) 2014 Patrick Kettner Licensed under the MIT license.