grunt-template-render

Grunt template rendering with partial and translation support. Uses Lo-Dash template markup.

Usage no npm install needed!

<script type="module">
  import gruntTemplateRender from 'https://cdn.skypack.dev/grunt-template-render';
</script>

README

grunt-template-render

Grunt template rendering with partial and translation support. Uses Lo-Dash template markup.

Based on grunt-template.

Getting started

This plugin requires Grunt v0.4.0+.

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

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

The template task

Add a template section to your gruntfile's initConfig section.

grunt.initConfig({
  template: {
    options: {
      // Task-specific options
    },
    your-target: {
      options: {
        // Target-specific options
      },
      files: {
        // Files to process
      }
    }
  }
});

Options

data

Type: Object or Function Default: {}

This object contains the data that will be used while interpolating the template files. If you pass a function instead, it will be called when grunt-template needs the template data (lazy evaluation). This is useful if you want to load data from a file that is generated by another Grunt task, for example.

delimiters

Type: String or Function Default: config

This is the delimiters' name that will be used to interpolate and evaluate code. A function that returns this name can be used too. This property is useful when you want to generate JSP/ERB like code and you need the default interpolation delimiters to be <% and %>. See below for an example.

cwd

Type: String or Function Default: process.cwd()

The current working from which to evaluate the render() helper from. Use if you want to reference templates in you project from anything other than your source directory (e.g., from a src/ subfolder within your project).

translations

Type: String or Function Default: {}

An object containing translations. For each translation the template will be evaluated separately. Provide a flex paramter % in your file name (/path/to/output/file/filename-%.html for allowing multiple outputs to be generated. Without the flex parameter all output will be generated to the same file destination.

Templating

Basic template syntax

Uses grunt.template.process, which in turn relies on Lo-Dash’s _.template() method. Here’s a quick reminder of the default delimiters:

  • Use <%= value %> to interpolate any values directly, i.e. inject them into the template without any modifications.

For more details and examples, see the Lo-Dash’s API documentation for the _.template() method.

Rendering partials

Render partials into templates using the <%= render('path/to/file.html') %> helper method. Replaces the helper with the file contents at the specified location, evaluating the partial with the same parameters provided to this task's config (i.e., data, translations)

Rendering translations

Evaluate translations in templates using the <%= translate('translation.key') %> helper method. Replaces the helper with the translation contents for the specified key for every translation provided.

Basic usage example

src/index.tpl.html

<!DOCTYPE html>
<h1><%= heading %></h1>
<h3><%= subheading %></h3>

<%= render('path/to/content.tpl.html') %>

Gruntfile.js

module.exports = function(grunt) {

  grunt.loadNpmTasks('grunt-template');

  grunt.initConfig({
    template: {
      build: {
        options: {
          data: {
            heading: 'Hello User',
            subheading: 'Welcome to my world'
          }
        },
        'files': {
          'dist/index.html': ['src/index.tpl.html']
        }
      }
    }
  });

  grunt.registerTask('default', [
    'template'
  ]);
};

Usage example using translations

src/index.tpl.html

<!DOCTYPE html>
<h1><%= heading %></h1>
<h3><%= subheading %></h3>

<%= render('path/to/content.tpl.html') %>

Gruntfile.js

module.exports = function(grunt) {

  grunt.loadNpmTasks('grunt-template');

  grunt.initConfig({
    template: {
      build: {
        options: {
          translations: {
            en: {
              heading: 'Hello User',
              subheading: 'Welcome to my world'
            },
            de: {
              heading: 'Hallo Benutzer',
              subheading: 'Willkommen in meiner Welt'
            }
          }
        },
        'files': {
          'dist/%/index.html': ['src/index.tpl.html']
        }
      }
    }
  });

  grunt.registerTask('default', [
    'template'
  ]);
};

Will result in two html pages being rendered located at:

dist/en/index.html
dist/de/index.html

License

grunt-template-render is available under the MIT license.