xplates v0.9.6
XPlates
What is this?
XPlates is a powerful but tiny and superfast string template library. It compiles templates into lightweight, portable JS functions.
Quick reference
Template creation:
XPlates(language, template)
XPlates(language, template, arguments)
XPlates(language, template, arguments, name)
XPlates(language, template, arguments, name, parameters)Template calling:
var t = XPlates('html', '<%= greeting %>, world!', ['greeting']);
t('Hello'); //Returns "Hello, world!"Template forms:
<% code %> //Code execution
<%= value %> //Escaped output
<%== value %> //Unescaped output
<%% func() %> //Unescaped template call; equivilent to <%== this.func() %>
<%? condition %>...<%?? condition %>...<%??%>...<%?%> //If, Else If, Else
<%~ array : index : value %>...<%~%> //Array iteration
<%~~ array : index : value %>...<%~~%> //Reverse array iteration
<%+ object : key : value %>...<%+%> //Object iteration
<%@ varname %>...<%@%> //Capture output in variable
<%! option=value %> //Template option Preprocessing:
<# code #> //Code execution
<#= value #> //Escaped output
<#== value #> //Unescaped output
<#? condition #>...<#?? condition #>...<#??#>...<#?#> //If, Else If, Else
<#~ array : index : value #>...<#~#> //Array iteration
<#~~ array : index : value #>...<#~~#> //Reverse array iteration
<#+ object : key : value #>...<#+#> //Object iteration
<#@ varname %>...<#@#> //Capture output in variable
<#! option=value #> //Template option Template Bundles
//Create a bundle
var b = new XPlates.bundle();
//Create some templates
b('text', '<%= greeting %>, world!', ['greeting'], 'welcome');
b('html', '<h1><%= text %></h1>', ['text'], 'header');
//Call templates
b.welcome('Hello'); //Returns "Hello, world!"
b.header('Hello'); //Returns "<h1>Hello</h1>"
b.header(b.welcome('Hello')); //Returns "<h1>Hello, world!</h1>
//Create a portable bundle of code
b.toString('my_bundle'); //Returns a string of JavaScript codeUsage
Compiling templates
Compiling a template returns a JavaScript function that returns a string.
var t = XPlates('html', '<div>Hello, world!</div>');
//t() returns "<div>Hello, world!</div>"Using arguments with templates
You can add arguments to templates, named however you'd like.
var t = XPlates('html', '<div><%= x %>, <%= y %>!</div>', ['x','y']);
//t('Hello','World') returns "<div>Hello, World!</div>"If you don't specify argument names, every template is assumed to have a single argument named "arg".
Operations
<% code %> Code execution
You can execute arbitrary code inside a template:
var t = XPlates('html', '<div><% for (var i = 0; i < 5; i++) { %>X<% } %></div>');
//t() returns "<div>XXXXX</div>"You can also use the "out" variable to append directly to the output:
var t = XPlates('html', '<div><% out += "hello!" %></div>');
//t() returns "<div>hello!</div>"<%= value %> Escaped output
Escaped output can be generated easily for the current langauge (in this case, HTML).
var t = XPlates('html', '<div><%= "I like apples & bananas!" %></div>');
//t() returns "<div>I like apples & bananas</div>"You can use variables, code, or anything that can be converted to a string inside this block:
var t = XPlates('html', '<div><%= Math.floor(x.y) %></div>');
//t({ y: 12.34 }) returns "<div>12</div>"<%== value %> Unescaped output
If you don't want your output escaped, use a double-equals:
var t = XPlates('html', '<div><%== "I like apples & bananas!" %></div>');
//t() returns "<div>I like apples & bananas</div>"
<%? condition %>...<%??%>...<%?%> Conditionals
You can add conditional statements easily:
var t = XPlates('html', '<div><%? x %>Yes!<%?%></div>', ['x']);
//t(true) returns "<div>Yes!</div>"
//t(false) returns "<div></div>"Here's how to do if, else if, else conditionals:
var t = XPlates('html', '<%? x < 0 %>Negative!<%?? x > 0 %>Positive!<%??%>Zero!<%?%>',['x']);
//t(1) returns "Positive!"
//t(-1) returns "Negative!"
//t(0) returns "Zero!"<%~ array : index : value %>...<%~%> Array iteration
Iterating over arrays is easy, and gives you quick access to the index and value:
var t = XPlates('html', '<%~ x : index : value %><%= index %> is <%= value %>! <%~%>',['x']);
//t(['A','B','C']) returns "0 is A! 1 is B! 2 is C! "The following forms are supported:
<%~ array : index : value %>...<%~%>
<%~ array : index %>...<%~%> //No value variable is okay! You can still use array[index].
<%~ array : : value %>...<%~%> //No index varaible is okay if you don't care about the index!
<%~ array %>...<%~%> //No index or value variables are still okay if you don't need either!<%~~ array : index : value %>...<%~~%> Reverse array iteration
Reverse array iteration works just like array iteration, but traverses it backwards:
var t = XPlates('html', '<%~~ x : index : value %><%= index %> is <%= value %>! <%~~%>',['x']);
//t(['A','B','C']) returns "2 is C! 1 is B! 0 is A! "All the same forms apply here as in forward iteration.
<%+ object : key : value %>...<%+%> Object iteration
This will iterator over the keys of an object:
var t = XPlates('html', '<%+ x : key : value %><%= key %> is <%= value %>! <%+%>',['x']);
//t({ A: 1, B: 2, C: 3 }) returns "A is 1! B is 2! C is 3! "The following forms are supported:
<%+ object : key : value %>...<%+%>
<%+ object : key %>...<%+%> //No value variable is okay! You can still use object[key].
<%+ object : : value %>...<%+%> //No key varaible is okay if you don't care about the key!
<%+ object %>...<%+%> //No key or value variables are still okay if you don't need either!<%@ varname %>...%@% Capture output as variable
This will capture string output in between the two tags into a variable:
var t = XPlates('html', '<%@ x %>Hello, <%= name %>!<%@%><%== x %> <%== x %>',['name']);
//t("World") returns "Hello, World! Hello, World!"<%! option=value %> Template options
<%! noparse=boolean %>
You can turn off template parsing if you want. This is useful when you have templates inside templates:
var t = XPlates('html', 'Hello, <%! noparse = true %><%= name %><%! noparse = false %>!');
//t() returns "Hello, <%= name %>!"Preprocessing
To make your templates a little faster, you can pre-compile your template with variables and operations, so only necessary work is done at the last minute.
To use this, add a "preprocess" object to the parameters, and use <# #> blocks:
var t = XPlates('html', '<div><#= greeting #>, <%= name %>!</div>', ['name'], null, { preprocess: { greeting: 'Hello' } });
//t('World') returns 'Hello, World!';Use the same template format, but with a <# #> instead of <% %>:
<# code #> //Code execution
<#= value #> //Escaped output
<#== value #> //Unescaped output
<#? condition #>...<#?? condition #>...<#??#>...<#?#> //If, Else If, Else
<#~ array : index : value #>...<#~#> //Array iteration
<#~~ array : index : value #>...<#~~#> //Reverse array iteration
<#+ object : key : value #>...<#+#> //Object iteration
<#@ varname %>...<#@#> //Capture output in variable
<#! option=value #> //Template optionPre-defined variables
Your template can be compiled with variable references pre-defined, making things available later on without explicit argument.
To use this, add a "predefined" object to the parameters:
var t = XPlates('html', '<div><%= greeting %>, <%= name %>!</div>', ['name'], null, { predefined: { greeting: 'Hello' } });
//t('World') returns 'Hello, World!';This is different from pre-processing: pre-processing variables are available only at compile time, while predefined variables are available at runtime.
Template Bundles
Creating and using bundles
Multiple templates can be packaged into a bundle:
//Create a bundle
var b = new XPlates.bundle();
//Create some templates
b('text', '<%= greeting %>, world!', ['greeting'], 'welcome');
b('html', '<h1><%= text %></h1>', ['text'], 'header');
//Call templates
b.welcome('Hello'); //Returns "Hello, world!"
b.header('Hello'); //Returns "<h1>Hello</h1>"
b.header(b.welcome('Hello')); //Returns "<h1>Hello, world!</h1>
Making bundles into portable JavaScript code
Bundles can be tranformed into portable JavaScript code that will run anywhere by calling toString(name)
b.toString('my_bundle'); //Returns a compact JavaScript stringThis code can run anywhere, and will include all the necessary code to do so - for example, escape functions.
For example, the bundle in the section above would look like this:
var my_bundle = new (function() {
var __xplates_html_chars = {"&":"&","<":"<",">":">","\"":""","'":"'"};
var __xplates_html_escape = function (s) { return s.replace(/[&<>"']/g, __xplates_html_replace); };
var __xplates_html_replace = function (c) { return __xplates_html_chars[c]; };
this["welcome"] = function welcome(greeting){var out="";out+=(""+(greeting))+", world!";return out; };
this["header"] = function header(text){var out="";out+="<h1>"+__xplates_html_escape(""+(text))+"</h1>";return out; };
return this; })();Multiple Language Support
XPlates supports multiple langauges, and can be easily extended to support more.
Language "html"
The "html" language includes escape characters for <>&"' characters:
var t = XPlates('html', '<%= message %>', ['message']);
t('Peanut Butter & Jelly'); //Returns "Peanut Butter & Jelly"For HTML, whitespace stripping functionality can be enabled for this language:
var t = XPlates('html', ' <div class=" <%= c %> " > Hello </div > ', ['c'], null, { strip: true });
t('red'); //Returns '<div class="red">Hello</div>'Language "text"
The "text" language is plain text - it includes no escape functionality and no special support.
var t = XPlates('text', '<%= message %>', ['message']);
t('Peanut Butter & Jelly'); //Returns "Peanut Butter & Jelly"Language "url"
The "url" language escapes all non-URL safe characters with encodeURLComponent
var t = XPlates('url', 'I like <%= message %>', ['message']);
t('Peanut Butter & Jelly'); //Returns "Peanut%20Butter%20%26%20Jelly"Language "md"
The "md" (Markdown) language escapes the < and & characters:
var t = XPlates('url', 'I like <%= message %>', ['message']);
t('Peanut Butter & Jelly'); //Returns "Peanut Butter & Jelly"