November Perfect Moustache

    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

    Install

    npm i all-templates

    DownloadsWeekly Downloads

    15

    Version

    0.1.13

    License

    GPL-3.0

    Unpacked Size

    147 kB

    Total Files

    30

    Last publish

    Collaborators

    • apaschenko