Merge pull request #200 from paulmsmith/feature/custom_nunjucks_filters

Adds custom 'filters' to the nunjucks templating engine

app/filters.js

@@ -0,0 +1,49 @@
+module.exports = function(env) {
+
+  /**
+   * Instantiate object used to store the methods registered as a
+   * 'filter' (of the same name) within nunjucks. You can override
+   * gov.uk core filters by creating filter methods of the same name.
+   * @type {Object}
+   */
+  var filters = {};
+
+  /* ------------------------------------------------------------------
+    add your methods to the filters obj below this comment block:
+    @example:
+
+    filters.sayHi = function(name) {
+        return 'Hi ' + name + '!';
+    }
+
+    Which in your templates would be used as:
+
+    {{ 'Paul' | sayHi }} => 'Hi Paul'
+
+    Notice the first argument of your filters method is whatever
+    gets 'piped' via '|' to the filter.
+
+    Filters can take additional arguments, for example:
+
+    filters.sayHi = function(name,tone) {
+      return (tone == 'formal' ? 'Greetings' : 'Hi') + ' ' + name + '!';
+    }
+
+    Which would be used like this:
+
+    {{ 'Joel' | sayHi('formal') }} => 'Greetings Joel!'
+    {{ 'Gemma' | sayHi }} => 'Hi Gemma!'
+
+    For more on filters and how to write them see the Nunjucks
+    documentation.
+
+  ------------------------------------------------------------------ */
+
+
+
+  /* ------------------------------------------------------------------
+    keep the following line to return your filters to the app
+  ------------------------------------------------------------------ */
+  return filters;
+
+};

lib/core_filters.js

@@ -0,0 +1,26 @@
+module.exports = function(env) {
+
+  // if you need accss to the internal nunjucks filter you can just env
+  // see the example below for 'safe' which is used in 'filters.log'
+  var nunjucksSafe = env.getFilter('safe');
+
+  /**
+   * object used store the methods registered as a 'filter' (of the same name) within nunjucks
+   * filters.foo("input") here, becomes {{ "input" | foo }} within nunjucks templates
+   * @type {Object}
+   */
+  var filters = {};
+
+  /**
+   * logs an object in the template to the console on the client.
+   * @param  {Any} a any type
+   * @return {String}   a script tag with a console.log call.
+   * @example {{ "hello world" | log }}
+   * @example {{ "hello world" | log | safe }}  [for environments with autoescaping turned on]
+   */
+  filters.log = function log(a) {
+  	return nunjucksSafe('<script>console.log(' + JSON.stringify(a, null, '\t') + ');</script>');
+  };
+
+  return filters;
+}

server.js

@@ -39,6 +39,17 @@ nunjucks.setup({
   noCache: true
 }, app);
 
+// require core and custom filters, merges to one object
+// and then add the methods to nunjucks env obj
+nunjucks.ready(function(nj) {
+  var coreFilters = require(__dirname + '/lib/core_filters.js')(nj),
+    customFilters = require(__dirname + '/app/filters.js')(nj),
+    filters = Object.assign(coreFilters, customFilters);
+  Object.keys(filters).forEach(function(filterName) {
+    nj.addFilter(filterName, filters[filterName]);
+  });
+});
+
 // Middleware to serve static assets
 app.use('/public', express.static(__dirname + '/public'));
 app.use('/public', express.static(__dirname + '/govuk_modules/govuk_template/assets'));