Template

Any time you have a group of similar objects and you need to produce formatted output for these objects, maybe inside a loop, you typically resort to concatenating string literals with the object's fields. There's nothing wrong with the above approach, except that it is hard to visualize the output immediately just by glancing at the concatenation expression. The Template class provides a much nicer and clearer way of achieving this formatting.

On this page

· | Straight forwar templates

· | Templates are ment to be reused

· | Escape Sequence

· | Custom syntaxes

· | Moduleindex

Straight forward templates

The Template class users a basic formatting syntax, similar to what is used in Ruby. The templates are created from strings that have embedded symbols in the form #{fieldName} that will be replaced by actual values when the template is applied (evaluated) to an object. A simple example follows.

// the template (our formatting expression)

var myTemplate = new Template('The TV show #{title} was created by #{author}.');

// our data to be formatted by the template

var show = {title: 'The Simpsons', author: 'Matt Groening', network: 'FOX' };

// let's format our data

myTemplate.evaluate(show);

// -> The TV show The Simpsons was created by Matt Groening.

Templates are meant to be reused

As the previous example illustrated, the Template objects are not statically tied to the data. The data is bound to the template only during the evaluation of the template, without affecting the template itself. The next example shows the same template being used with a handful of distinct objects.

//creating a few similar objects

var conversion1 = {from: 'meters', to: 'feet', factor: 3.28};

var conversion2 = {from: 'kilojoules', to: 'BTUs', factor: 0.9478};

var conversion3 = {from: 'megabytes', to: 'gigabytes', factor: 1024};

//the template

var templ = new Template('Multiply by #{factor} to convert from #{from} to #{to}.');

//let's format each object

[conversion1, conversion2, conversion3].each( function(conv){

templ.evaluate(conv);

});

// -> Multiply by 3.28 to convert from meters to feet.

// -> Multiply by 0.9478 to convert from kilojoules to BTUs.

// -> Multiply by 1024 to convert from megabytes to gigabytes.

Escape sequence

There's always the chance that one day you'll need to have a literal in your template that looks like a symbol, but is not supposed to be replaced. For these situations there's an escape sequence - the backslash character ( \ .)

// note: you're seeing two backslashes here because the backslash is also a

// escaping character in JavaScript strings

var t = new Template('in #{lang} we also use the \#{variable} syntax for templates.');

var data = {lang:'Ruby', variable: '(not used)'};

t.evaluate(data);

// -> in Ruby we also use the #{variable} syntax for templates.

Custom syntaxes

The default syntax of the template strings will probably be enough for most scenarios. In the rare occasion where the default Ruby-like syntax is inadequate there's provision for customization. The Template's constructor accepts an optional second argument that is a regular expression object to match the replaceable symbols in the template string. Let's put together a template that uses a syntax similar to the ubiquitous <%= %> constructs.

var syntax = /(^|.|\r|\n)(\<%=\s*(\w+)\s*%\>)/; //matches symbols like '<%= field %>'

var t = new Template('<div>Name: <b><%= name %></b>, Age: <b><%=age%></b></div>', syntax);

t.evaluate( {name: 'John Smith', age: 26} ); // -> <div>Name: <b>John Smith</b>, Age: <b>26</b></div>

There are important constraints to any custom syntax. Any syntax must provide at least three groupings in the regular expression. The first grouping is to capture what comes before the symbol, to detect the backslash escape character (no, you cannot use a different character.) The second grouping captures the entire symbol and will be completely replaced upon evaluation. Lastly, the third required grouping captures the name of the field inside the symbol.

Moduleindex

evaluate

evaluate(object) -> String

Applies the template to the given object’s data, producing a formatted string with symbols replaced by corresponding object’s properties.

Prototype API 1.5.0 - prototypejs.org