Template (in PrototypeJS)

Posted: 14 May, 2008 in Technical

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.

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.

Methods

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.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s