JS Template Engine

Fast JS nested templates rendering.

The main goal

of this library is to provide you with maximum functionality while saving ease of use in simple cases of its using.

Features | Implemented --- | --- Nested layers | yes Conditional rendering | yes Qualified names | not yet Configurability | yes The ability to store data anywhere | yes, with synchronous or asynchronous loading of its on demand.

Installation

npm install all-templates --save

Using

const AT = require('all-templates');

First: yes, render is an asynchronous function.

Why?

Because it allows you not only to parse the templates defined as strings, but also to request the patterns(layers) from the file system, databases etc. (a detailed explanation is below).

Example 1: Old-school way :)

const template = 'Hello, {{ first_name }} {{ last_name }}';
const data = {
    first_name: 'John',
    last_name: 'Smith'
};

let result = await AT.render(template, data).catch( (e) => { console.log(e); } )

console.log(result);  // Hello, John Smith

Example 2: Single dataset

const data = {
    start: 'Hello, {{ first_name }} {{ last_name }}',
    first_name: 'John',
    last_name: 'Smith'
};

let result = await AT.render(data).catch( (e) => { console.log(e); } );

console.log(result);  // Hello, John Smith

Rendering always starts with a key whose default name is "start". You can change the name of this key using the options. If you use the old school way (see Example 1), before the start of rendering, the template will be inserted into the data with the given (default or redefined) key name. In the case that the data already contained this key name, its value will be ignored and overwritten by the value of the template.

Example 3: Entry point name changing

const data = {
    top_layer: 'Hello, {{ first_name }} {{ last_name }}',
    first_name: 'John',
    last_name: 'Smith'
};

const options = {
    start_name: 'top_layer'
};

let result = await AT.render(data, options).catch( (e) => { console.log(e); } );

console.log(result);  // Hello, John Smith

Example 4: Placeholders customisation

Overrides the opening and closing part of the placeholder (for European languages - left and right, respectively). Be careful: redefined values ​​will be a part of the regular expression. Therefore, if you use special characters of regular expressions for your placeholders, then each such character must be escaped with two backslashes.

const data = {
    top_layer: 'Hello, ((first_name)) ((last_name))',
    first_name: 'John',
    last_name: 'Smith'
};

const options = {
    placeholder: {
        open: '((',
        close: '))'
    }
};

let result = await AT.render(data, options).catch( 
    (e) => { console.log(e); } 
);

console.log(result);  // Hello, John Smith

Example 5: Nested layers

const data = {
    start: '{{ question }} {{ tail }}?',
    question: 'What Does',
    tail: 'The {{animal}} {{action}}',
    animal: 'Fox',
    action: 'Say'
};

let result = await AT.render(data).catch( (e) => { console.log(e); } );

console.log(result);  // What Does The Fox Say?

Example 6: Conditional rendering

const data = {
    start: 'Don’t {{ unless bully }}judge{{ else }}hit{{ end }} ' +
           'a {{ if reader }}book{{ else }}saucepan{{ end }} by its cover.',
    reader: true,
    bully: false
};

let result = await AT.render(data).catch( (e) => { console.log(e); } );

console.log(result);  // Don’t judge a book by its cover.

Parameters

AT.render(data, options, functions)

AT.render(template, data, options, functions)

Parameter | Required | Type --- | --- | --- data | Mandatory (if template don't presents) Optional (otherwise) | Object ⎮ Map template | Optional | String options | Optional | Object functions | Optional | Object ⎮ Map

Detailed description

Data is the main conception of this library. As a rule, template rendering libraries need for two parameters:

• one or many templates that must be processed;
• input data that will be inserted into templates instead corresponding placeholders in the templates.

However, this library does not distinguish between the two sets. From its point of view, "everything is a data." The "data" parameter contains both a template (a set of layers) and input data for substitutions instead of placeholders.

But how does it understand during processing whether the current element is an input data or a template? Nohow! It does not need to know this.

All-templates works very simply:

First of all, it finds the start key (if you have not redefined the name of this key in options.start_name) in the data object/map and takes its value.

If this value contains placeholders, the library finds the value of the corresponding keys in the same data parameter. If, in turn, it also contain placeholders, then the process is repeated recursively.

When the nested layer (or input data) have no more placeholders, it is substituted into layer above instead the placeholder that corresponding to its name. It's all!

Options

Option | Type | Description | Default --- | --- | --- | --- start_name | String | RegExp | Key name in the "data" parameter, from which the rendering will start | "start" mode | Object | fast: if true, each layer will be rendered once | false placeholder | Object: { open: <String>, close: <String>} | Overrides the opening and closing part of the placeholder (for European languages - left and right, respectively). | placeholder: {open: "{{", close: "}}"} undefined | String | If data source not found or undefined, it will be replaced to the defined value| 'undefined' Getters

Function | Object<String: Function> | Map<String|RegExp: Function>

Placeholders

Placeholder | Description --- | --- {{ <name> }} | The value of name will be inserted instead placeholder {{ = }} | The same as above {{ if <name> }} ... [ {{ else }} ... ] {{ end }} | if operator {{ unless <name> }} ... [ {{ else }} ... ] {{ end }} | unless operator {{ # ... some text ... }} | commentaries