grunt-flats
Grunt task for generating static pages from templated partials.
Getting Started
This plugin requires Grunt ~0.4.5
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, you may install this plugin with this command:
npm install grunt-flats --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt;
The "flats" task
Overview
In your project's Gruntfile, add a section named flats
to the data object passed into grunt.initConfig()
.
grunt;
Options
options.basePath
Type: String
Default value: '_templates'
Working path for all templating, relative to root
options.layoutPath
Type: String
Default value: 'layouts'
Directory where individual layouts are kept, relative to basePath
options.partialPath
Type: String
Default value: 'partials'
Directory where individual partials are kept, relative to basePath
options.masterSrc
Type: String
Default value: 'masterpage/master.html'
Path to masterpage, relative to basePath
options.destPath
Type: String
Default value: '_templates'
Directory where individual layouts are compiled to, same as basePath
by default
Note: Grunt-flats includes grunt-contrib-clean as a dependency, and will clean all *.html
files from this directory on build (excluding masterSrc
, should you want to keep that in the basePath
directory).
File structure
Grunt-flats attempts to be as flexible as possible. The file structure based off the tasks' default options would follow:
_templates/
masterpage/
master.html
layouts/
(individual layout templates)
partials/
(partials and/or user-defined sub-directories)
(compiled templates)
However, each of these directories and paths are configurable to match your existing workflow. If you're a fan of Pattern Lab's Atomic Design Patterns or Lonely Planet's Rizzo Styleguide you can folderize your partials accordingly.
The grunt-flats Git repo contains an example _templates
directory. This includes a master, layouts and partials to demonstrate how the plugin could be utilised.
It is especially effective when wanting to produce a living styleguide for a site; ensuring all code snippets are maintained in a single place and any changes are automatically propogated through all templates.
Master page
See: /_templates/masterpage/master.html
The master should contain all of your site-wide template markup. It contains a single {{>content}}
partial to act as a placeholder; this is where each individual layout's markup will be rendered.
Partials/include pattern
Grunt-flats uses Hogan.js under the hood. It's built against Mustache's test suite, so you can easily port your existing Mustache or Handlebars templates and retain the same partial syntax.
To include a partial, reference it using an extensionless path. This should be relative to the options.partialPath
directory. E.g.
{{>components/header}}
Partials are constructed recursively, so can be infinitely nestable.
Partial-specific data
Partial rendering can be enhanced by including a partial-specific data object. This syntax is similar to that utilised by Pattern Lab:
{{>components/module-promo ("imgsrc": "/images/new-promo.jpg", "title": "New Module Title")}}
Partial data is wrapped within parenthesis ( ... )
and appended to the partial reference. Within, the data should be formatted as you would any standard JSON object. Keys and values are wrapped in double quotes, and each key/value pair separated by a single comma.
Partial default values
Once a data object has been defined and passed to a partial, we can utilise these values on their own, or pair them with defaults. Use Mustache's Inverted Sections syntax to declare a default value to use, following a standard Mustache Variable. For example, within components/module-promo:
{{title}}{{^title}}Default Module Title{{/title}}
This way we can define default dummy data for any partials throughout the templates, and be sure only one value will be rendered. It allows our partials to be more customisable and re-usable, in a very targetted way.
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
- v0.1.0 Initial setup, non-recursive partial rendering
- v0.2.0 Rewrite to support infinitely nestable partial rendering
- v0.2.1 Added error checking for incorrect/missing partials
- v0.3.0 Added partial-specific data rendering