At the Forge

The past few articles, I've looked at a number of uses for JavaScript, on both the server and the client. I hope to continue my exploration of such systems, particularly on the client side, in the coming months.

But for now, I want to tackle a more mundane problem that JavaScript programmers encounter all the time: the fact that JavaScript doesn't have any native string-interpolation mechanism. Sure, you always can use the + operator to concatenate strings:

"hello, " + "world"

which gives you the string:

"hello, world"

which is what you might expect. But, what if you have a variable "username", and you want to say "hello" to the user in a friendly way? In Ruby, you would use:

"hello, #{username}"

And in Python, you would write:

"hello, %s" % username

But in JavaScript, you're basically stuck typing:

"hello, " + username

which isn't so terrible if you have one variable at the end of the string. But the more I'm working with JavaScript, the more I'd like to have more sophisticated string interpolation.

While I'm wishing, I'd like to have all sorts of text-formatting and templating capabilities that I'm used to from other languages or from various Web frameworks.

Now, this doesn't sound like a tall order. And heaven knows, I've used a lot of templating systems during the years, so I know that it's not very hard to create one—especially if the standards aren't very high. But as Web applications become more heavily focused on the browser, and on JavaScript, you'll need a templating solution that allows you to work easily in that environment.

Fortunately, several templating systems exist. One of the most prominent and interesting is Mustache.js, a JavaScript implementation of the Mustache templating system that is available for many different languages. In contrast with most other templates I've used, Mustache.js is not a fully fledged programming language, as you might expect. Rather, it's a tightly defined domain-specific language that describes the page, but that doesn't have the potential to make templates into another code repository.

So, this article explores Mustache.js—how to install and use it, as well as when it's appropriate and how to use a few of the more-advanced features that come with it.

Many readers probably are familiar with a typical sort of template, with a style used by PHP, ASP, JSP and Ruby's ERb. Anything that should be executed goes in braces that look like this:

<% varname = 5 %>

And, anything you want to display on the screen gets nearly the same sort of tag, but with an = sign on the left:

<%= varname %>

The good news with such templates is that they're rather easy to use. You don't have to worry about which symbols mean what, or set up a file just to see some interpolated variables. But on the other hand, they're too simple for producing large-scale reports and certainly for doing serious text manipulation.

The other problem is that as soon as you put code into your template, you're violating the rule of MVC, which is that you don't want to put very much executable code in your template. Assigning variables isn't a good idea, but calling methods, not to mention retrieving rows from the database, is something you normally don't want to be doing within your views. But, you can be even stricter in how you interpret this no-execution policy. What if you could avoid all executable code, including if/then statements, loops and other things to which you're accustomed?

Mustache adopts this philosophy in that it allows for a limited set of things to take place within the template. You could argue (and I'd probably believe you) that it's going too far to say, as the Mustache slogan says, that they're “logic-less templates”. Indeed, Mustache templates do have a fair amount of logic in them. But the nature of the templating language ensures that the special functions cannot be abused too terribly. If you want to execute code, you'll have to do it outside the realm of Mustache.

(If you're wondering, it's called Mustache because it uses double-curly braces, {{ and }}, as delimiters. Double-curly braces indicate where you want interpolation to take place, and they also delimit various control structures.)

Installing Mustache.js couldn't be easier. Download the single mustache.js file from GitHub, put it in an appropriate directory inside the JavaScript directory for your Web application—or alongside your HTML file, if you're just experimenting with it outside a framework—and you're ready to go.

Note that the inclusion of Mustache.js doesn't turn your HTML file (or your JavaScript file, for that matter) into a Mustache template. Rather, it provides you with a number of functions that can be applied to text strings. You then can do whatever you want with those text strings, from inserting them into a file to using them for further processing.

Listing 1 contains a simple example of using Mustache.js. At the top of the <head> section, I include both the jQuery library and Mustache.js, as I often would in an HTML file. I then have a bit of JavaScript code executing in the standard $(document).ready function call, ensuring that it will be executed only after jQuery has detected that the entire HTML document has loaded. This avoids a race condition, in which the JavaScript might or might not run before the HTML has been rendered.

<!DOCTYPE html>
<html>
<head>
<title>Testing</title>

<script src="jquery.js"></script>
<script type="text/javascript" src="mustache.js"></script>

<script type="text/javascript">
     $(document).ready(
     function () {
     var template_vars = {
     name: 'Reuven',
     number_of_children: 3
     }

     var template = "<b>{{name}}</b> has 
     ↪{{number_of_children}} children.";
     var html = Mustache.to_html(template, template_vars);
     $('#target').html(html);
     });
</script>

</head>
<body>
<h1>Testing testing</h1>
<p>This is a paragraph</p>
<p id="target">This space for rent</p>
</body>
</html>

I then define a variable (template_vars), a JavaScript object with two properties, “name” and “number_of_children”. These properties can be of any data type, including a function. If a property is a function, it is evaluated when interpolated, and the result of the function's evaluation is inserted into the template.

I've then broken up the interpolation into three distinct parts. First, I define the text (the “template” variable) into which I want to interpolate variables. Notice how the string is a tiny template, and that anything within {{ }} (double-curly braces) is evaluated as a variable by Mustache.js.

Next, you apply your template_vars to the template, getting some HTML back. You then can do whatever you want with that HTML, including (most easily) replacing the text from an existing HTML tag. You also could have created a new node, replaced an existing one or modified the text even further.

In the end, I did something fairly simple, namely using jQuery's “html” function to replace the existing HTML with the improved version.

For something a bit more complex, which resembles traditional HTML templates a bit more, consider Listing 2. In this example, I decided to do a Mad Libs sort of replacement, but instead of changing text in a string, I changed it in the document itself. Using jQuery's selectors, I chose all elements with a “template” class. (This allows the author of the page to decide whether the {{ }} tags will be used on a particular tag.)

<!DOCTYPE html>
<html>
<head>
<title>Testing</title>

<script src="jquery.js"></script>
<script type="text/javascript" src="mustache.js"></script>

<script type="text/javascript">
     $(document).ready(
     function () {
     var template_vars = {
     proper_noun: 'Reuven',
     color: 'green',
     food: 'ice cream'
     }

     $(".template").each(function(index, value) {
     var current_html = $(this).html();
     var translated = Mustache.to_html(current_html, template_vars);
     $(this).html(translated);
     });

     });
</script>

</head>
<body>
<h1>Testing testing</h1>
<p>This is a paragraph</p>
<p class="template">My name is {{proper_noun}}.</p>
<p class="template">I like to wear {{color}} shirts, 
and eat {{food}} for breakfast.</p>
</body>
</html>

Perhaps the most interesting and important part of this code is the callback function I used to do the translation. Rather than using a typical jQuery loop, which would have turned into a rat's nest of code, I decided to use the “each” function, which iterates over a collection. In each iteration, $(this) refers to the item, and you next use the Mustache.to_html function to translate it, and then replace the text with its transformed self. In this way, your JavaScript easily can affect the text on the page.

What happens if you ask Mustache to use a variable value that you have not defined? It continues silently, using an empty string. This means that if your template_vars variable contains one or more keys with misspelled names, you won't get any warnings.

Remember when I wrote that I wouldn't call Mustache.js “logic-less templates”, because the templating language still includes conditionals? Well, now you can see what I meant. (I should add that I'm fairly convinced I normally don't want code to be evaluated/executed in the template. But, conditionals and loops are two things that every useful templating system I've had has incorporated, and they are a necessary piece of logic for templates to be useful.)

If you look at Listing 3, you'll see how to create loops. I have added an array (“children”) inside my template_vars variable. But instead of saying {{children}} to retrieve the contents of the array, you instead say {{#children} at the beginning of the loop and {{/children} at its end. Mustache.js is smart enough to know what to do, and it repeats the block within these delimiters, once for each element of the array. To get the current array element itself, you use the special syntax {{.}}.

<!DOCTYPE html>
<html>
<head>
<title>Testing</title>

<script src="jquery.js"></script>
<script type="text/javascript" src="mustache.js"></script>

<script type="text/javascript">
     $(document).ready(
     function () {
     var template_vars = {
     name: 'Reuven',
     children: ['Atara', 'Shikma', 'Amotz']
     }

     var template = "<b>{{name}}</b> has children
     ↪named:<ul>{{#children}}<li>{{.}}</li>{{/children}}.</ul>";
     var html = Mustache.to_html(template, template_vars);
     $('#target').html(html);
     });
</script>


</head>
<body>
<h1>Testing testing</h1>
<p>This is a paragraph</p>
<p id="target">This space for rent</p>
</body>
</html>

That's certainly some degree of logic, but it's nothing compared with the {{#mycondition}} tag, which begins the equivalent of an if-then statement. But wait, what are you checking? Well, if you're starting your condition with {{#mycondition}}, that means you're going to treat “mycondition” as a function, evaluating it at runtime and then displaying only the contents of the block (that is, the stuff between {{#mycondition}} and {{/#mycondition}} if the function returns “true”).

Mustache has a bunch of other features too. It automatically escapes HTML by default, but it has a mechanism, {{{ }}}, that uses raw HTML, without cleaning up the < and > symbols that can be both annoying and potentially dangerous. So, you have the flexibility to replace text as appropriate in your application.

The examples I have provided obviously are somewhat contrived and simple. Fortunately, the syntax of Mustache.js is simple enough that it shouldn't take very long at all to incorporate it into your work.

Mustache is a straightforward, but powerful, templating system for JavaScript. If you're starting to put together a Web application that needs to rewrite parts of the text based on AJAX calls or JavaScript output, or if you're writing a one-page JavaScript-based application, you certainly should look into Mustache.js. The home page on GitHub has good documentation, and other tutorials and documents are linked from there as well.