minimal.js: HTML+JSON template engine

(skip directly to Usage, a complex example usage, and learn how to extend with new features)

version 0.2.1
- default renderer for non-textual and non-array values is "children"
version 0.2.0
- pre and post processing filters
- exception handling
version 0.1.2
- npm compatibility (installable via npm install minimal)
version 0.1.1
- Fixed SERIOUS bug on minimal-node that prevented multiple templates to coexist
- Performance improvements
version 0.1.0
- Initial version

Why?

Yes, the current landscape for HTML templating is very rich. However, there are severe problems that create impedance on their usage, including:

Complex or proprietary/alien DSL syntax (e.g., almost all template engines listed as Node.js modules);
Complex data binding for non-trivial scenarios (e.g., PURE, Chain.js);
Dependent on specific Javascript libraries (e.g., jQuery template, Chain.js);
Difficult (or impossible) to be extended.

Design goals

Developers deserve a good UX, too. Libraries and APIs should be rich, yet simple to use. Hence, minimal.js is designed to achieve the following goals:

No proprietary/alien DSL syntax. HTML is the template, JSON is the data. There's no need to reinvent the wheel, nor to complicate when there's no need to;
Minimal syntax in both HTML and JSON counterparts. Extra fluff should be present only when it is strictly impossible to infer the bindings, and this fluff must be minimal as well;
Independent from Javascript libraries, but friendly to any of them;
Dynamic. Afford reapplication of new data into an existing template (e.g., for AJAX re-binding of JSON data);
Fast. Examples: support caching; no eval-style directives;
Extendable to new functionality;
Small. Currently clocking 167 lines + 13 for node.js support, including comments and whitespace.

Usage

minimal.js relies on two core functionalities, rendering and iterations, and an auxiliary functionality, modes. A description of these functionalities is provided below. For further information and examples, check the test directory in this project.

Setup

Browser

Simplest of the setups, just add minimal.js to your HTML document:

<script src="minimal.js" type="text/javascript" charset="utf-8"></script>

Afterwards, an object named $m is available at the window scope (and its alias window.minimal as well). This object provides two functions:

$m.render, to support rendering (including iterations and modes functionalities).

Note: Since it's the most common task to be done with this library, $m is also a function alias to $m.render.

$m.custom, to extend minimal.js with new renderers (discussed further below).

Node.js

minimal.js is now available via npm. To install it (and dependencies), execute the following command:

npm install jsdom minimal

Now minimal.js is ready to be used, by importing the minimal module, as follows:

var minimal = require("minimal");

Since we're outside a browser's context, the actual HTML template has to be loaded. For that, the minimal-node.js library provides the template function to load a string-based template, which returns the $m object:

var $m = minimal.template("<html>...</html>");

Afterwards, the $m object is available to be used just like in the browser. Additionally, the rendering of the HTML template can be accessed through the special function $m.html() available at this object:

var html = $m.html();

Custom CSS Selector

minimal.js comes bundled with a predefined CSS selector (basically, a wrapper on Element.querySelector). Since several JS libraries, such as jQuery, provide their own custom CSS selector, minimal.js can be configured to use appropriate implementations. To accomplish this, override the $m.querySelector function with a function that takes a base and a selector parameters. Example implementations for some well-known libraries follow:

jQuery

$m.querySelector = function(base, selector) { return $(selector, base)[0]; };

Dojo

$m.querySelector = function(base, selector) { return dojo.query(base).query(selector)[0]; };

Prototype

$m.querySelector = function(base, selector) { return base.select(selector)[0]; };

Sizzle

$m.querySelector = function(base, selector) { return Sizzle(selector, base)[0]; };

Custom exception handler

By default, minimal.js does not fail in the case of encountering incorrect JSON bindings. However, it is possible to handle these exceptions with a custom exceptionHandler function:

$m.exceptionHandler = function() { ... };

Rendering

The function signature to render JSON data is:

$m(json)

json is a hashmap of key/value pairs. Each key must represent a valid reference to an HTML element, in the following way:

if key is a valid id (i.e., analogous to document.getElementById), it defines the scope of applicability of its value counterpart;
if it is a valid class (i.e., analogous to document.getElementsByClassName), it applies the value to the first matched element;
otherwise, the key is interpreted as a CSS selector (i.e., analogous to document.querySelector).

Afterwards, the value is applied to the corresponding HTML element.

Note: due to the way minimal.js is implemented, this function can only be executed after the DOM tree is fully loaded (e.g., DOMContentLoaded event in Opera and Gecko-based browsers).

Example

Consider the following HTML template snippet:

<h1></h1>
<p></p>
<p id="footer"></p>

and the following Javascript:

$m({
	h1: "this is a title",
	p: "this is a paragraph",
	footer: "this is a footer"
});

will result in the following transformed HTML:

<h1>this is a title</h1>
<p>this is a paragraph</p>
<p id="footer">this is a footer</p>

h1 and p are interpreted as CSS selectors, whereas footer is interpreted as an id.

Iteration

Iterations extend the value counterpart of the core rendering functionality. This is achieved by specifying a child HTML element as the template, and an Array instance as its JSON data.

Example

Consider the following HTML template snippet:

<ul>
	<li></li>
</ul>

and the following Javascript:

$m({
	ul: ["foo", "bar", "baz"]
});

will result in the following transformed HTML:

<ul>
	<li>foo</li>
	<li>bar</li>
	<li>baz</li>
</ul>

Modes

minimal.js provides several modes to modify template processing behaviour: replace, append, and prepend. These modes are detected through the data-mode attribute. If this attribute is not found, the replace behaviour is assumed.

Note: minimal.js supports all modes on both rendering and iteration core functionalities.

Replace (default)

The replace mode is the default behaviour for template processing, where templates always reflect the binding to the latest corresponding JSON data.

Example

Consider the following HTML template snippet:

<ul>
	<li></li>
</ul>

and the following Javascript:

$m({
	ul: ["foo", "bar"]
});

$m({
	ul: ["baz"]
});

will result in the following transformed HTML:

<ul>
	<li>baz</li>
</ul>

Append

The append mode allows for the attachment of new JSON data to the end of a given HTML template.

Example

Consider the following HTML template snippet:

<ul data-mode="append">
	<li></li>
</ul>

and the following Javascript:

$m({
	ul: ["foo", "bar"]
});

$m({
	ul: ["baz"]
});

will result in the following transformed HTML:

<ul>
	<li>foo</li>
	<li>bar</li>
	<li>baz</li>
</ul>

Prepend

The prepend mode allows for the attachment of new JSON data to the beginning of a given HTML template.

Example

Consider the following HTML template snippet:

<ul data-mode="prepend">
	<li></li>
</ul>

and the following Javascript:

$m({
	ul: ["foo", "bar"]
});

$m({
	ul: ["baz"]
});

will result in the following transformed HTML:

<ul>
	<li>baz</li>
	<li>foo</li>
	<li>bar</li>
</ul>

Builtin custom renderers

minimal.js comes with three custom renderers in addition to its core functionality: attr, children, and nano. These are provided to cover more complex (real) template scenarios. Custom renderers are identified by the data-render attribute on HTML elements.

Attr

The attr renderer provides binding facilities to element attributes. Example:

Consider the following HTML template snippet:

<a data-render="attr"></a>

and the following Javascript:

$m({
	a: { href: "http://foo.com", content: "foo" }
});

will result in the following transformed HTML:

<a data-render="attr" href="http://foo.com">foo</a>

Note: this renderer applies the content directive to the HTML element's content.

Children

The children renderer provides delegation of JSON data to a given HTML element's child elements. The JSON data can be either an Array (as exemplified below), an Object (where keys can be id, class, or CSS selector based), or atomic values.

Consider the following HTML template snippet:

<div data-render="children">
	<h2></h2>
	<p></p>
</div>

and the following Javascript:

$m({
	div: ["header", "content"]
});

will result in the following transformed HTML:

<div data-render="children">
	<h2>header</h2>
	<p>content</p>
</div>

*As of version 0.2.1, minimal.js defaults JSON data rendering to the children renderer fo

Minimal.js

Install / Use

README

minimal.js: HTML+JSON template engine

Why?

Design goals

Usage

Setup

Browser

Node.js

Custom CSS Selector

jQuery

Dojo

Prototype

Sizzle

Custom exception handler

Rendering

Example

Iteration

Example

Modes

Replace (default)

Example

Append

Example

Prepend

Example

Builtin custom renderers

Attr

Children