templar

A simple, yet intuitive DOM templating engine

Usage

Template syntax is similar to your standard mustache templates with double curly braces ({{ }}) serving as delimiters to internal logic. The tokens found between the delimiters are the reference point for the value of its place in the template, Take for instance the following:

import templar from 'templar';

// Create a new template
const tpl = templar('<div id="{{id}}">{{content}}</div>');

// Set the id and content
tpl.set('id', 'foo');
tpl.set('content', 'bar');

// Append to the DOM
tpl.mount(document.body);

Outputs:

<div id="foo">bar</div>

Internally, templar updates only the parts of the DOM that have changed and makes use of requestAnimationFrame to batch DOM manipulations for increased performance.

Interpolation

Supports simple interpolation with primitive values (strings, numbers, and booleans):

const tpl = templar('<div id="{{foo}}">{{bar}} {{baz}}</div>');

tpl.set('foo', 'aaa');
tpl.set('bar', 123);
tpl.set('baz', true);

DOM nodes are also supported, including elements, text nodes, document fragments, and HTML strings:

const tpl = templar('<div>{{foo}} {{bar}} {{baz}}</div>');

tpl.set('foo', document.createElement('div'));
tpl.set('bar', document.createDocumentFragment());
tpl.set('baz', '<strong>bold</strong>');

Use simple expressions, such as basic arithmetics, the ternary operator, array access, dot-notation, and function invocations:

const tpl = templar('<div>{{foo ? foo + bar() + array[1] + obj.baz.qux : 0}}</div>');

tpl.set('foo', 2);
tpl.set('bar', () => 4);
tpl.set('array', [10, 20, 30]);
tpl.set('obj', {
    baz: {
        qux: 8
    }
});

You can even nest templates within templates:

const div = templar('<div>{{content}}</div>');
const em = templar('<em>{{text}}</em>');
div.set('foo', em);
em.set('text', 'some text');

By default, HTML strings are automatically parsed into DOM nodes. To prevent this and escape HTML characters instead, prefix a token with an ampersand (&):

const tpl = templar('<div>{{&foo}}</div>');

tpl.set('foo', '<i>foo</i>'); // &lt;i&gt;foo&lt;/i&gt;

Setting an attribute to an empty string will effectively remove the attribute from the element:

const tpl = templar('<div id="{{id}}"></div>');

tpl.set('id', '');
tpl.find('div').hasAttribute('id'); // false

API

templar(tpl[, data])

Create a new template by providing a template string and optionally provide a data object to set default values:

const tpl = templar('<div id="{{foo}}">{{bar}}</div>', {
    foo: 'abc',
    bar: 123
});

templar#set(token, value)

Set the value of a token and trigger the template to dynamically update with the new value. You can also provide an object literal to set multiple tokens at once. Returns the templar instance to support method chaining:

const tpl = templar('<div id="{{foo}}">{{bar}} {{baz}}</div>');

// Set a single value
tpl.set('foo', 'aaa');

// Set multiple values
tpl.set({
    bar: 'bbb',
    baz: 'ccc'
});

// Supports method chaining
tpl.set('foo', 123).set('bar', 456);

templar#get(token)

Get the current value of a token:

const tpl = templar('<div id="{{foo}}"></div>', {foo: 123});

tpl.get('foo'); // 123

templar#mount(root)

Append the template to an element. Returns the templar instance to support method chaining:

const tpl = templar('<div>{{foo}}</div>');
const container = document.createElement('div');

tpl.mount(container);

templar#unmount()

Remove the template from its parent element. Returns the templar instance to support method chaining:

const tpl = templar('<div>{{foo}}</div>');

tpl.mount(document.body);
tpl.unmount();

templar#getRoot()

Get the root element of the template. This is the document fragment before it has been mounted, and the parent element after:

const tpl = templar('<div>{{foo}}</div>');
const container = document.createElement('div');

tpl.getRoot(); // document fragment
tpl.mount(container);
tpl.getRoot(); // container

templar#isMounted()

Check if the template has been mounted to a parent element:

const tpl = templar('<div>{{foo}}</div>');
const container = document.createElement('div');

tpl.isMounted(); // false
tpl.mount(container);
tpl.isMounted(); // true

templar#isRendered()

Check if the template actually exists within the DOM:

const tpl = templar('<div>{{foo}}</div>');
const container = document.createElement('div');

tpl.mount(container);
tpl.isRendered(); // false

document.body.appendChild(container);
tpl.isRendered(); // true

templar#find(selector)

Query the template for the first element matching the provided CSS selector string:

const tpl = templar('<button>{{foo}}</button>');

tpl.find('button').addEventListener('click', (e) => {
    // handle event
})

templar#query(selector)

Query the template for all the elements matching the provided CSS selector string:

const tpl = templar('<span></span><span></span><span></span>');

tpl.query('span').forEach((el) => {
    // do something
});

templar#destroy()

Destroy the templar instance. This will remove the template from the DOM and nullify internal properties. This cannot be undone:

const tpl = templar('<div>{{foo}}</div>');

tpl.destroy();

templar#isDestroyed()

Check if the templar instance has been destroyed:

const tpl = templar('<div>{{foo}}</div>');

tpl.isDestroyed(); // false
tpl.destroy();
tpl.isDestroyed(); // true

Installation

templar is CommonJS and AMD compatible with no dependencies. You can download the development or minified version, or install it in one of the following ways:

npm install ryanmorr/templar

bower install ryanmorr/templar

Tests

Open test/runner.html in your browser or test with PhantomJS by issuing the following commands:

npm install
npm install -g gulp
gulp test

License

This project is dedicated to the public domain as described by the Unlicense.