all-templates

0.1.13 • Public • Published

JS Template Engine

npm version Build Status

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

Package Sidebar

Install

npm i all-templates

Weekly Downloads

1

Version

0.1.13

License

GPL-3.0

Unpacked Size

147 kB

Total Files

30

Last publish

Collaborators

  • apaschenko