Skip to content

Latest commit

 

History

History
253 lines (201 loc) · 8.04 KB

README.md

File metadata and controls

253 lines (201 loc) · 8.04 KB
Raw

grunt-mustache-render v1.9.0

Build Status NPM version

This is a grunt plugin to render mustache templates. It takes data in static JSON, static YAML, JS module, or a POJO (Plain Ol' JavaScript Object) format. It allows you to specify a folder for partials, instead of needing to list them individually.

Getting Started

This plugin requires Grunt ~0.4.1

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-mustache-render --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-mustache-render');

The "mustache_render" task

Overview

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

grunt.initConfig({
  mustache_render: {
    options: {
      // Task global options go here
    },
    your_target: {
      options: {
        // Target specific options go here
      },
      files : [
        {
          data: // Path to JS module, path or URL to JSON or YAML, or POJO
          template: // Path or URL to template file
          dest: // Path to output destination here
        }
      ]
    },
  },
})

Note: The files parameter must be an array, and must conform to the format specified above. Each object in the file array represents one rendered template. Data files can be in either JSON, YAML format, or as either an external JS file via module.exports or a POJO (Plain Ol' JavaScript Object).

Building Long File Lists

If you want to build out a long list for the files array, perhaps dynamically as described by building the files object dynamically, you may use either data or template as the source (src) value as long as you specify the other one by its normal name. See below for some examples.

Examples:

files: [
  {data: "path/to/data/file.json",
   template: "path/to/template.mustache",
   dest: "file/to/output.html"},
  {data: "http://api.example.com/file.json",
   template: "http://docs.example.com/report.mustache",
   dest: "file/to/output.html"}
]
files: [
  {data: { greeting: "Hello", target: "world" },
   template: "path/to/template.mustache",
   dest: "file/to/output.html"},
  {data: { greeting: "Hola", target: "mundo" },
   template: "http://docs.example.com/report.mustache",
   dest: "file/to/output.html"}
]
options: {template: 'common-template.mustache'},
files: {
  'file/to/output-1.html': 'data/to/read-1.json',
  'file/to/output-2.html': 'data/to/read-2.json',
  'file/to/output-3.html': 'data/to/read-3.json'
}
files: [
  {expand: true,
   src: 'data/to/read-*.json',
   template: 'common-template.mustache',
   dest: 'dest/directory/'}
]
options: {data: 'common-data.json'},
files: {
  'file/to/output-1.html': 'template/to/read-1.mustache',
  'file/to/output-2.html': 'template/to/read-2.mustache',
  'file/to/output-3.html': 'template/to/read-3.mustache'
}
files: [
  {expand: true,
   src: 'template/to/read-*.mustache',
   data: 'common-data.js',
   dest: 'dest/directory/'}
]

Options

options.directory

Type: String
Default value: "." (i.e. relative to your Gruntfile.js)

Path to the directory in which partials can be found. Partials are looked up by name in this directory.

options.extension

Type: String
Default value: ".mustache"

mustache-render will use this extension when looking up partials.

options.prefix_file and options.prefix_dir

Type: String
Default value: ""

mustache-render will use these as common prefixes when looking up partials, with prefix_file prepended onto the filename and prefix_dir prepended onto the leading directory (if any). For example, given prefix_file: 'part_' and prefix_dir: 'sub_', a partial reference for a/hello would search for a file named sub_a/part_hello.mustache.

Note: Versions 1.6 and earlier of the plug-in use an option called prefix, which prepended onto the partial reference, regardless of whether it included a directory or not. This option is still supported for backward compatibility and maintains the same behavior.

options.glob

Type: String
Default value: ""

A glob pattern to use to search for partials. If this option is set, options.prefix_file, options.prefix_dir, options.prefix and options.extension will be ignored. The glob pattern will be expanded using grunt.file.expand and the first file found will be used. If more than one file is found, a warning will be printed.

You can use this variables in the pattern:

  • $0 The whole partial name
  • $1 The partial name's directory part
  • $2 The partial name's basename part

Examples:

  • prefix_dir$1/prefix_file$2 does the same as using options.prefix_file and options.prefix_dir
  • $0.* allows any extension
  • {images/$0.svg,partials/$0.mustache} seaches for a partial either as name.svg in the image folder or as name.mustache in the partials folder.

options.clear_cache

Type: Boolean
Default value: false

Clears the mustache cache before running the target. Mustache will cache partials by name when running multiple tasks, so this option is usefull if options.extension, options.directory, or options.prefix have been changed between tasks.

options.partial_finder

Type: Function
Default value: null

Overrides the default function for finding partials. The function will be passed the name of the partial as a parameter, and must return the text of the partial.

partial_finder: function(name) {
  return "Hello, I am a partial with name: " + name + "\n";
}

options.data and options.template

Type: anything normally accepted for a file
Default value: undefined

These two slots can be used to fill in a default data or template value for any item in your files list that does not already have one specified. This can be handy if you want to dynamically build the files list and apply the same data or template source to every item in the list.

options.escape

Type: Boolean or Function
Default value: true

By default (true), mustache will escape special HTML characters unless explicitly disabled in the template body (e.g. by using triple mustaches, {{{var}}}).

If set to false it disables default HTML escaping. That means that {{var}} will not be escaped. This is useful for templating files that are not HTML.

To implement custom escape handling specific to your needs, you may instead pass a function that accepts and returns a string.

Usage Examples

For this Grunt config:

grunt.initConfig({
  mustache_render: {
    all: {
      files: [{
        data: "data/hello_world.json",
        template: "templates/hello_world.mustache",
        dest: "public/hello_world.html"
      }]
    }
  }
})

And this json:

{
  "greeting" : "Hello",
  "target" : "World"
}

This template:

<html>
<head>
  <meta charset="UTF-8">
  <title>A greeting</title>
</head>
<body>
  <h1>{{greeting}}, {{target}}!</h1>
</body>
</html>

Will produce this output:

<html>
<head>
  <meta charset="UTF-8">
  <title>A greeting</title>
</head>
<body>
  <h1>Hello, World!</h1>
</body>
</html>

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.