Gaikan (2.0.0)

Gaikan is the fastest JavaScript template engine and has been designed to use data-* attributes to implement most template features. Due to this design, the templates are completely designer- and tooling friendly. The template engine is compatible with nodejs, expressjs (a popular web application framework for nodejs) and modern browsers (IE7+). Test the template engine in the browser with the interactive Gaikan (work in progress, IE9+) tool.

1. Quickstart
1.1. NodeJS
1.2. ExpressJS
1.3. Browser
2. Benchmarks
2.1. Linux Ubuntu 12.04, NodeJS 0.10.26 (100.000x)
2.2. Windows 7 x64 SP1, NodeJS 0.10.26 (100.000x)
3. Introduction
4. Variables
4.1. Escaping
4.2. Alterant
4.2.1. Break
4.2.2. Decode
4.2.3. Encode
4.2.4. Lower
4.2.5. Title
4.2.6. Upper
4.2.7. Url
4.3. Set
4.3.1. Empty
4.3.2. Sort
5. Attributes
5.1. If
5.2. For
5.3. Attribute
5.4. Extract
5.5. Include/Fragment
5.6. Evaluate
6. Tips/Tricks
6.1. Inline CSS
6.2. If/Else
7. Server API
7.1. Options
7.1.1. Caching
7.1.2. Compression
7.1.3. Directories
7.1.4. Extensions
7.1.5. Layout
8. Browser API
8.1. Configuration
8.1.1. Compression
9. Runtime
9.1 Alterant
9.2 Set
10. Security
11. Planned Future Additions

1. Quickstart

1.1. NodeJS

npm install gaikan

1.2. ExpressJS

var gaikan = require('gaikan');
app.engine('html', gaikan);
app.set('view engine', '.html');

1.3. Browser

<script src="gaikan-2.x.x-min.js"  type="text/javascript"></script>

2. Benchmarks

The template engine is, at the moment, the fastest JavaScript template engine. The benchmark suite has been made available at template-benchmark (forked from an unmaintained template benchmark suite). The benchmark suite was run on an AMD Phenom(tm) II X4 955 3.2GHZ processor.

2.1. Linux Ubuntu 12.04, NodeJS 0.10.26 (100.000x)

Gaikan               ( 2090ms) - fastest
ECT                  ( 2334ms) - 12% slower
Fest                 ( 2791ms) - 34% slower
Dust                 ( 3030ms) - 45% slower
doT                  ( 3940ms) - 89% slower
Hogan.js             ( 3977ms) - 90% slower
EJS without `with`   ( 5190ms) - 148% slower
Swig                 ( 5258ms) - 152% slower
Underscore           ( 6154ms) - 194% slower
Handlebars.js        ( 7255ms) - 247% slower
Eco                  ( 8315ms) - 298% slower
EJS                  ( 9059ms) - 333% slower
Jade without `with`  (10973ms) - 425% slower
CoffeeKup            (11062ms) - 429% slower
Jade                 (27295ms) - 1206% slower

2.2. Windows 7 x64 SP1, NodeJS 0.10.26 (100.000x)

Gaikan               ( 2147ms) - fastest
Fest                 ( 2535ms) - 18% slower
doT                  ( 3524ms) - 64% slower
Underscore           ( 5108ms) - 138% slower
Handlebars.js        ( 5734ms) - 167% slower
ECT                  ( 7223ms) - 236% slower
EJS without `with`   ( 8732ms) - 307% slower
Dust                 ( 9136ms) - 326% slower
Hogan.js             ( 9960ms) - 364% slower
Swig                 (10240ms) - 377% slower
Eco                  (12292ms) - 473% slower
Jade without `with`  (13510ms) - 529% slower
EJS                  (14917ms) - 595% slower
CoffeeKup            (15319ms) - 614% slower
Jade                 (34000ms) - 1484% slower

3. Introduction

It is important to understand a template engine, and this template engine is essentially quite simple. The template engine consumes a template and produces a JavaScript function. That function, representing the template, is then invoked with a runtime (__r, the helper functions), a root object (the user input) and a fragments object (__f, more on this later). The result of the function is the output. For each example in this documentation, the following object is used as root:

{
	message: '<b>Hello world!</b>',
	messageMultipleLines: 'Hello\nworld!',
    	messagePlain: 'Hello world!',
	people: [{
		age: 25,
		name: 'John'
	}, {
		age: 18,
		name: 'Jane'
	}]
}

Due to this nature of compiling the template to a JavaScript function, the template features (such as variables and attributes) produce JavaScript code and emit each line of code into the function. To demonstrate the behaviour of each feature, the examples in this documentation will show the template, the function and the output. For example:

Hello world!

function anonymous(__r, root, __f) {
	var __o = '';
	__o += 'Hello world!';
	return __o;
}

Hello world!

It is recommended to use the interactive Gaikan (work in progress, IE9+) tool to play with each example.

4. Variables

A variable is the only feature that does not use a data-* attribute.

!{root.message}

function anonymous(__r, root, __f) {
	var __o = '';
	__o += (typeof root.message === 'undefined' ? '' : root.message);
	return __o;
}

<b>Hello world!</b>

4.1. Escaping

Escaping a variable prevents XSS and is the recommend variable usage.

#{root.message}

function anonymous(__r, root, __f) {
	var alterant = __r.alterant;
	var __o = '';
	__o += (typeof root.message === 'undefined' ? '' : alterant.encode(root.message));
	return __o;
}

&#60;b&#62;Hello world!&#60;/b&#62;

4.2. Alterant

An alterant modifies a variable. Multiple alterants can be chained.

#{root.messagePlain|upper,url}

function anonymous(__r, root, __f) {
	var alterant = __r.alterant;
	var __o = '';
	__o += (typeof root.message === 'undefined' ? '' : alterant.url(alterant.upper(alterant.encode(root.messagePlain))));
	return __o;
}

HELLO%20WORLD!

4.2.1. Break

The break alterant replaces new lines with <br />.

#{root.messageMultipleLines|break}

function anonymous(__r, root, __f) {
	var alterant = __r.alterant;
	var __o = '';
	__o += (typeof root.messageMultipleLines === 'undefined' ? '' : alterant.break(alterant.encode(root.messageMultipleLines)));
	return __o;
}

Hello<br />world!

4.2.2. Decode

The decode alterant decodes special HTML characters.

#{root.message|decode}

function anonymous(__r, root, __f) {
	var alterant = __r.alterant;
	var __o = '';
	__o += (typeof root.message === 'undefined' ? '' : alterant.decode(alterant.encode(root.message)));
	return __o;
}

<b>Hello world!</b>

4.2.3. Encode

The encode alterant encodes spcial HTML characters. The equivalent of a # variable statement.

!{root.message|encode}

function anonymous(__r, root, __f) {
	var alterant = __r.alterant;
	var __o = '';
	__o += (typeof root.message === 'undefined' ? '' : alterant.encode(root.message));
	return __o;
}

&#60;b&#62;Hello world!&#60;/b&#62;

4.2.4. Lower

The lower alterant changes the variable to lower case.

#{root.messagePlain|lower}

function anonymous(__r, root, __f) {
	var alterant = __r.alterant;
	var __o = '';
	__o += (typeof root.messagePlain === 'undefined' ? '' : alterant.lower(alterant.encode(root.messagePlain)));
	return __o;
}

hello world!

4.2.5. Title

The title alterant changes the variable to title case.

#{root.messagePlain|title}

function anonymous(__r, root, __f) {
	var alterant = __r.alterant;
	var __o = '';
	__o += (typeof root.messagePlain === 'undefined' ? '' : alterant.title(alterant.encode(root.messagePlain)));
	return __o;
}

Hello World!

4.2.6. Upper

The upper alterant changes the variable to upper case.

#{root.messagePlain|upper}

function anonymous(__r, root, __f) {
	var alterant = __r.alterant;
	var __o = '';
	__o += (typeof root.messagePlain === 'undefined' ? '' : alterant.upper(alterant.encode(root.messagePlain)));
	return __o;
}

HELLO WORLD!

4.2.7. Url

The url alterant encodes the variable as an url component.

#{root.messagePlain|url}

function anonymous(__r, root, __f) {
	var alterant = __r.alterant;
	var __o = '';
	__o += (typeof root.messagePlain === 'undefined' ? '' : alterant.url(alterant.encode(root.messagePlain)));
	return __o;
}

Hello%20world!

4.3. Set

A set operates on an array or object (with properties).

4.3.1. Empty

The empty set checks if a variable is an empty set.

#{set.empty(root.people)}

function anonymous(__r, root, __f) {
	var alterant = __r.alterant;
	var set = __r.set;
	var __o = '';
	__o += (typeof set.empty(root.people) === 'undefined' ? '' : alterant.encode(set.empty(root.people)));
	return __o;
}

false

4.3.2. Sort

The sort set can sort a variable, optionally by key and reverse.

<div data-for="person in set.sort(root.people, 'age')">
    #{person.name} is #{person.age}
</div>

function anonymous(__r, root, __f) {
	var alterant = __r.alterant;
	var set = __r.set;
	var __o = '';
	__o += '<div>';
	var __v0 = set.sort(root.people, 'age');
	if (__v0) {
		for (var __k0 = 0; __k0 < __v0.length; __k0 += 1) {
			var person = __v0[__k0];
			__o += '\n    ' + (typeof person.name === 'undefined' ? '' : alterant.encode(person.name)) + ' is ' + (typeof person.age === 'unde

Gaikan

Install / Use

README