Wok Nunjucks renderer

Nunjucks template renderer for @wok-cli/task-views.

| Hook types | Production only | Purpose | | ---------- | --------------- | ---------------- | | Map | no | Output rendering |

• Wok Nunjucks renderer
• Installation
• Parameters
• Usage
  • Global functions
  • Setting global helpers
  • Environment Customization

Installation

This plugin requires @wok-cli/core and @wok-cli/task-views as peer dependencies.

npm i @wok-cli/core @wok-cli/task-views @wok-cli/plugin-render-nunjucks --save-dev

Parameters

Configuration path: nunjucks.

| parameter | type | default | note | | --------- | -------- | ------- | ------------------------------------------- | | root | string | | Templates root folder(1) | | helpers | function | | Global helpers | | env | function | | Nunjucks environment customizer | | ...opts | object | | Nunjucks environment options (2) |

1. Supports environment templates. It will be used as first argument for nunjucks.configure.
2. Any other parameter will be passed as the opts argument to nunjucks.configure.

Usage

The plugin will filter files with the .njk and .nunjucks extension and output a rendered .html file.

const $ = require('@wok-cli/core');
const views = require('@wok-cli/task-views');
const nunjucks = require('@wok-cli/plugin-render-nunjucks');

const viewTask = $.task(views, {
  // multiple templates allowed
  src: ['src/**/*.{njk,hbs,html}'],
  dest: 'public',
});

viewTask.tap('engines', 'nunjucks', nunjucks);

export.views = viewTask;

Global functions

This plugin adds the following global functions:

• url(str) A function that prepends the value of the publicPath Wok environment object to the passed in string and normalizes it.

Setting global helpers

Global helpers are functions and variables available in every template on the helpers object.

To define global helpers set a helpers function on the hooks:engines -> nunjucks task parameters.

The function receives the opts parameters and the Wok environment configuration object as arguments

const $ = require('@wok-cli/core');
const views = require('@wok-cli/task-views');
const nunjucks = require('@wok-cli/plugin-render-nunjucks');

+function helpers(opts, env) {
+  return {
+    // return the name from package.json
+    projectName: () => env.pkg.name;
+  }
+}

const viewTask = $.task(views, {
  // multiple templates allowed
  src: ['src/**/*.{njk,hbs,html}'],
  dest: 'public',
+ 'hooks:engines': {
+   nunjucks: {
+     helpers
+   }
+ }
});

viewTask.tap('engines', 'nunjucks', nunjucks);

export.views = viewTask;

With the above example you can access the projectName helper function like this:

<p>This project name: {{ helpers.projectName() }}</p>

Environment Customization

You can customize the Nunjucks environment instance via the env parameter.

The following example will use addGlobal to make the lodash library available to every template under the _ global object:

const $ = require('@wok-cli/core');
const views = require('@wok-cli/task-views');
const nunjucks = require('@wok-cli/plugin-render-nunjucks');

+ function env(nunjucksEnv) {
+   nunjucksEnv.addGlobal('_', require('lodash'))
+ }

const viewTask = $.task(views, {
  // multiple templates allowed
  src: ['src/**/*.{njk,hbs,html}'],
  dest: 'public',
+ 'hooks:engines': {
+   nunjucks: {
+     env
+   }
+ }
});

viewTask.tap('engines', 'nunjucks', nunjucks);

export.views = viewTask;