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 ornew 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
- 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
- Add the script to your HTML document:
Or if you're in a Node.js environment:<script src="path/to/templater.min.js"></script>
var templater = require("templater.js");
- Create the template you'd like to use:
var tmpl = "Hi, my name is {{ name }}."
- 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:
{{contents}}
{{ contents}}
{{contents }}
{{ contents }}
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 #if
s
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:
-
Property names cannot contain periods
-
Accessing an array requires use of dot-notation:
{{array[0]}}
→{{array.0}}
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.