handlebars-helperized

Opinionated handlebars based templating engine for rendering HTML and other text based formats. It's especially suited for e-mail content as it supports style inlining.

The following helpers are injected by default:

• Handlebars layouts
• numbro for number formatting
• moment-timezone for proper date/time handling

Additionally, a lightweight localization plug-in is provided through a handlebars extension t.

Additional custom helpers can be provided from the service which makes use of this module by passing an array which contains the file's path relative to the root folder on class initialization.

// example
const filePathList = ['./test/handlebars/helper-loud.js'];
const renderer = new Renderer(tpl, '', '', {}, filePathList );

Usage

This renderer can be used standalone in any node.js project on the server side. Due to the heavy weight, this pre-charged template renderer is mainly intended for server side usage.

The simplest use case looks like this:

// require the library
const Renderer = require('handlebars-helperized');

// initialize a renderer instance with a template string
const tpl = `<h1>Hello {{name}}</h1>`;
const renderer = new Renderer(tpl);

// use the renderer with arbitrary contextual data
const result = renderer.render({ name: 'John' });
// result === '<h1>Hello John</h1>';

If you want to use an additional layout template to enclose your main template, just pass the renderer an additional parameter, like this:

// require the library
const Renderer = require('handlebars-helperized');

// initialize a renderer instance with a template string
const tpl = `
{{#extend "layout"}}
  {{#content "main"}}
    Hello, <i>{{name}}</i>
  {{/content}}
{{/extend}}`;
const layout = `
<p>
  {{#block main}}
    stuff
  {{/block}}
</p>`;
const renderer = new Renderer(tpl, layout);

// use the renderer with arbitrary contextual data
const result = renderer.render({ name: 'John' });
// result === '<p>Hello, <i>John</i></h1>';

It is also possible to provide CSS content to be inlined in the produced HTML. Such is done by using the Renderer's third parameter. Style inling is performed using juice.

...
const style = 'div { color: red, text-align: center }';
const renderer = new Renderer(tpl, layout, style);
const result = renderer.render({ name: 'John' });
// result === '<div style="color: red; text-align: center;">Hello, <i>John</i></div>'

For localized content, the t helper can be used like shown below. Translation texts can be provided as third parameter of the renderer.

// require the library
const Renderer = require('handlebars-helperized');

// template string with translation placeholder
const tpl = `<h1>{{t 'greeting'}} {{name}}</h1>`;

// options object with translation texts included
const opts = {
  texts: {
    'greeting': 'Hallo'
  }
}

// renderer instance without a layout but with translation options
const renderer = new Renderer(tpl, null, null, opts);

// use the renderer with arbitrary contextual data
const result = renderer.render({ name: 'John' });
// result === '<h1>Hallo John</h1>';

It is also possible to have data placeholders within the translation texts as well, like this:

// require the library
const Renderer = require('handlebars-helperized');

// template string with translation placeholder
const tpl = `<h1>{{t 'greeting' name=name}}</h1>`;

// options object with translation texts included
const opts = {
  texts: {
    'greeting': 'Hallo {{name}}'
  }
}

// renderer instance without a layout but with translation options
const renderer = new Renderer(tpl, null, null, opts);

// use the renderer with arbitrary contextual data
const result = renderer.render({ name: 'John' });
// result === '<h1>Hallo John</h1>';

Additionally, the injected extensions for formatting date, time and numbers may be used. Have a look at the extensions itself for an overview of the provided helpers, or see a summary below. An example for these formatting capabilities looks like this:

// require the libraries
const Renderer = require('handlebars-helperized');
const moment = require('moment-timezone');

// initialize a renderer instance with a template string
const tpl = '<p>You paid {{nfc price}} on {{df date}}</p>';
const renderer = new Renderer(tpl);

// create a timestamp & use the renderer with arbitrary contextual data
const ts = '07-22-2018 13:37:00';
const format = 'MM-DD-YYYY HH:mm:ss';
const tz = moment.tz.guess();
const yesterday = moment.parseZone(ts, format, tz);
const result = renderer.render({ price: 1.99, date: yesterday });
// result: '<p>You paid $1.99 on 07/22/2018</p>';

If you want to display these helperized information with localized formatting, just set the locale setting (default: en_US) to the desired cultural area like this:

// require the libraries
const Renderer = require('handlebars-helperized');
const moment = require('moment-timezone');

// initialize a renderer instance with a template string
const tpl = '<p>You paid {{nfc price cs="$" csPos="postfix"}} on {{df date}}</p>';
const renderer = new Renderer(tpl, null, null, { locale: 'de_DE' });

// create a timestamp & use the renderer with arbitrary contextual data
const ts = '07-22-2018 13:37:00';
const format = 'MM-DD-YYYY HH:mm:ss';
const tz = moment.tz.guess();
const yesterday = moment.parseZone(ts, format, tz);
const result = renderer.render({ price: 1.99, date: yesterday });
// result: '<p>You paid 1,99€ on 22.07.2018</p>';

Injected Extensions Overview