grunt-swigtemplates

Grunt plugin for working with swig templates.

grunt-swigtemplates

Use grunt-swigtemplates to create grunt tasks for processing your swig templates. It'll be most useful when using swig as the templating engine for static sites, but should be general enough to be useful in other scenarios as well. The plugin includes methods for defining template variables with JSON files on the filesystem, or by defining them in the Grunt config. It also includes a simple mechanism for building localized versions of your static site using whatever internationalization tools you prefer.

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-swigtemplates --save-dev

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

grunt.loadNpmTasks('grunt-swigtemplates');

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

grunt.initConfig({
  swigtemplates: {
    options: {
      defaultContext: {
        pageTitle: 'My Title'
      },
      templatesDir: 'src/swig'
    },
    production: {
      dest: 'build/',
      src: ['src/swig/**/*.swig']
    },
    staging: {
      context: {
        pageTitle: 'My Title (staging)'
      },
      dest: 'build/',
      src: ['src/swig/**/*.swig']
    }
  }
});
  1. Define a file called globals.json in your templatesDir, and any values you set there will be added into context
  2. For a given file, myfile.html.swig, you can define file-specific context values by creating a companion file,myfile.html.json in the same folder with values that will override anything set in globals.json
  3. Context values set in options.defaultContext will override anything in filesystem JSON files
  4. Target-specific context values will replace anything else
  • Type: Object
  • Default value: {}

A default context object passed into swig templates during processing. These values will override any that were set on the file system with global.json or myfile.html.json, and can be overridden by the context property on individual swigtemplates targets.

  • Type: String
  • Default value: '.'

Use templatesDir to define where grunt-swigtemplates will look for globals.json and file-specific JSON context.

  • Type: Object
  • Default value: {}

Set local values that will be available in all swig templates. This can be especially useful if you want to add a callable function into the context without having to build a custom tag.

swigtemplates {
  options: {
    locals: {
      reversefunction(msg) {
        return msg.split('').reverse().join('');
      }
    }
  }
}
<p>{{ reverse('Racecar!') }}</p>
<p>!racecaR</p>
  • Type: Object
  • Default value: {}

Adds custom swig filters. See the swig documentation on extending swig with custom filters for more information.

  • Type: Boolean
  • Default value: true
  • Type: Array
  • Default value: ['{%', '%}']
  • Type: Array
  • Default value: ['{{', '}}']
  • Type: Array
  • Default value: ['{#', '#}']
  • Type: Array
  • Default value: []
  • Type: String
  • Default value:
  • Type: Function
  • Default value: function(locale, msg) { return msg; }
  • Type: String
  • Default value: '__'
grunt.initConfig({
  swigtemplates: {
  }
});
 

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.

  • 2013-12-08   v0.0.1   Initial version
  • 2014-08-25   v0.0.2   Updated context precedence
  • 2014-08-25   v0.0.3   Filters and locals
  • 2014-08-27   v0.0.4   Simple internationalization
  • 2014-08-27   v0.0.5   Minor change