rosid-handler-njk

A function that loads a Nunjucks template and transforms it to HTML.

Install

npm install rosid-handler-njk

Usage

API

const handler = require('rosid-handler-njk')
 
handler('index.njk').then((data) => {})
handler('index.njk', { optimize: true }).then((data) => {})
handler('index.njk', { data: { key: 'value' } }).then((data) => {})
handler('index.njk', { data: 'data.json' }).then((data) => {})

Rosid

Add the following object to your rosidfile.json, rosidfile.js or routes array. rosid-handler-njk will transform all matching Nunjucks files in your source folder to HTML.

{
    "name"    : "NJK",
    "path"    : "[^_]*.{html,njk}*",
    "handler" : "rosid-handler-njk"
}

<!-- index.njk -->
<h1>Hello {{ 'World' }}</h1>

<!-- index.html (output) -->
<h1>Hello World</h1>

Parameters

• filePath {String} Path to file.
• opts {?Object} Options.
  • optimize {?Boolean} - Optimize output. Defaults to false.
  • data {?Object|String} - Data used to render the template. Defaults to {}.
  • localOverwrites {?Boolean} - Enable or disable custom data per file. Defaults to true.
  • prepend {?String} - String that will be placed in front of the content of filePath. Defaults to ''.
  • append {?String} - String that will be placed at the end of the content of filePath. Defaults to ''.
  • src {?String} - Path base for injects with the inject tag. Defaults to the current working directory.
  • shy {?RegExp} - What to replace when using the shy filter. Defaults to /\|/g.

Returns

• {Promise<String|Buffer>} The transformed file content.

Miscellaneous

Inject tag

rosid-handler-njk adds a custom Nunjucks extension you can use in your templates. The Nunjucks tag inject allows you to include other Nunjucks files with custom data. This feature is currently not part of Nunjucks.

{% inject 'button.njk' %}
{% inject 'button.njk', { color: 'purple', text: 'Button' } %}

The path to the file is always relative to the current working directory or to the path specified in opts.src. This behavior is different to Nunjucks's build-in include tag, where the path is relative to the initial file.

<!-- src/index.njk -->
{% inject 'src/includes/a.njk' %}
{% include 'includes/a.njk' %}
 
<!-- src/includes/a.njk -->
{% inject 'src/includes/b.njk' %}
{% include 'includes/b.njk' %}
 
<!-- src/includes/b.njk -->
{{ 'This is a file' }}

Shy filter

rosid-handler-njk adds a custom filter that replaces | with ­ and indicates that the string should not be auto escaped by Nunjucks (similar to the safe filter).

{{ 'Long head|lines are awe|some' | shy }}

You can customize the behaviour of the filter by passing a custom shy regexp to the module.

Data

The data in opts.data will be used to render your template. opts.data can either be an object (the data) or a string (path to data file). rosid-handler-njk tries to require the path when a string is specified instead of an object. The path must be absolute or relative to the current working directory.

Custom data per file

Create a file with the name filename.data.json or filename.data.js along your filename.njk to add or overwrite data from opts.data. You can disable this behaviour with the localOverwrites option.

Environment

rosid-handler-njk passes a variable called environment to your template. environment is prod when opts.optimize is true and dev when opts.optimize is false.