templater.js

A tiny JS library for minimal {{templating}}.

Download → GitHub →

tl;dr

templater.js is a teeny JavaScript library for minimal (String + JSON → Template) templating. Its templating expression syntax mimics that of {{mustache}}. Barebones conditional logic included.

Features

  • No eval()s or new Function() { … }s
  • HTML characters automatically escaped
  • Node.js and browser compatible
  • < 1KB minified + gzipped
  • Zero dependencies

Limitations

  • Cannot nest #if statements
  • Property names cannot contain periods
  • Use dot-notation for arrays (e.g. {{array[0]}}{{array.0}})

Demo

See the Pen templater.js Demo by Paul Esch-Laurent (@Pinjasaur) on CodePen.

Getting Started

  1. Install the script:

    You can install it with Bower, npm/yarn, or from the latest release on GitHub.

    bower install templaterjs # for Bower
    npm install templater.js # for npm
  2. Add the script to your HTML document:
    <script src="path/to/templater.min.js"></script>
    Or if you're in a Node.js environment:
    var templater = require("templater.js");
  3. Create the template you'd like to use:
    var tmpl = "Hi, my name is {{ name }}."
  4. Parse the template against some data and render it:
    var template = templater(tmpl),
        data = {
          name: "Paul"
        };
    
    template(data); // Hi, my name is Paul.

API

templater.js exposes a very simple and minimal API. In the following code snippets, tmpl and data will be referenced, which are simply the template as a string and the data as an object, respectively.

Parsing

To load a template into templater.js, simply call templater and pass in the template. This will return a function, so the return value needs to be assigned to a variable.

var template = templater(tmpl);

Rendering

To render the parsed template against some data, simply call the function returned when the template was parsed and pass in the data. It will return the rendered template as a string. It can be called multiple times, against different sets of data, if desired.

template(data); // Returns rendered template, as a string

All At Once

Of course, you can combine the two function calls into one step, if desired.

templater(tmpl)(data); // Rendered template

Syntax

Expressions

Syntax mimics {{mustache}} et al.: {{ contents }} where contents represents what you'd like to replace when the template is rendered against some data. Note that the amount of whitespace between contents and the two braces is limited to zero (0) or one (1). For example, the following are all valid:

However, for the sake of readability I would recommend consistently sticking to 0 or 1 spaces.

Nested properties

You can access nested properties like so: {{foo.bar.baz}}. If it's an array, use dot-notation: {{array[0]}}{{array.0}}.

Note: properties cannot contain periods, as it will be evaluated as a nested property.

Functions

If the property referenced corresponds to a function, the evaluated function will be used in the template.

For example, given the following data

{
  fn: function() {
    return 2 + 2;
  }
}

and referenced in a template like {{fn}}, then the rendered result would be 4.

Conditionals

You can use an #if directive to conditionally render template contents based on the truthy value of the arguments. The syntax looks like:

{{ #if (condition) }}
  <!-- this only renders if `condition` evaluates to a truthy value -->
{{ /if }}

To provide multiple arguments to the condition, just separate them by commas: {{ #if (foo, bar, baz) }}. The comma acts as an AND operator: all the operands must evaulate to truthy for the condition to be considered true.

If desired, you can NOT the entire conditon by using a bang (e.g. {{ #if !(foo, bar, baz) }} ).

For example, given the following data

{
  name: "John",
  age: 27,
  likesCookies: false
}

the following conditionals will evaluate to truthy (and thus be rendered)

{{ #if !(likesCookies) }}
{{ #if (name, age)}}

however, the following will evaluate to falsy (and will not be rendered)

{{ #if (name, age, likesCookies) }}
{{ #if (likesCookies) }}

Limitations

Nested #ifs

Due to how the templating is handled (regular expressions) nested #if statements will not work.

Nested properties

Due to how nested properties are evaluated, the following should be taken into consideration:

Contributing

Have an idea for improvement? Could this documentation be clarified? Is there an optimization to the templating logic that could be made?

Read the contributing guidelines then fork the repository and submit a pull request on GitHub.