Moustache is good. Easy HTML Templates with Mustache

Learn how to create HTML templates using Mustache, the easy-to-use, logic-less template system. Types of moustaches list.

Templates are a great way to separate your website's code from its design. There are many great web template systems available for different languages and platforms, including Smarty for PHP and the Django template language for Python.

In this tutorial you'll explore Mustache, a relatively new and very simple template system that you can easily use to create HTML templates. You'll look at various topics, including:

The advantages of using Mustache

How to install and use the Mustache processor

How Mustache tags, variables, and data objects work

Using sections to create conditions and loops

Including one Mustache template inside another

Along the way, you'll see plenty of code examples that show you how Mustache works. At the end of the tutorial, there's a complete example that uses Mustache, along with jQuery, to create a simple Ajax-based product list page.

What is Mustache?

Mustache is a simple template system that you can use when building websites and web apps. By using a template system, you can keep your back-end code separate from the markup that displays the front end to the user. This clean separation gives you many advantages. For example, it makes it easy for a designer to work on a website's visual design without the risk of messing up the site's code. It also makes it easy for you to change the design at a later point without impacting the back-end code.

One of Mustache's big plus points is that is logic-less, which means it keeps your templates very neat and tidy. There are no messy

or looping constructs embedded within a Mustache template; it's all just markup and simple Mustache tags. All the logic is hidden away inside your data objects (and the code that creates or fetches them).

Another advantage of Mustache is that you're not tied to any particular language. Mustache processors are available in many languages, including JavaScript, PHP, Perl, Ruby, Python, Java and lots more.

You can use Mustache for practically any kind of template, including config files and even source code. However, this article concentrates on using Mustache to build HTML templates, which is a very popular use of the system.

Mustache is used by a lot of popular websites and web apps, including Twitter and OMGPOP (maker of the ever-popular Draw Something game). Here's a list of sites that use Mustache.js, the JavaScript version of Mustache.

A basic Mustache example

What does a Mustache template look like? Here's a simple example:

As you can see, this template is essentially HTML mixed with a few special Mustache tags. A Mustache tag begins with two opening braces (

) and ends with two closing braces (

As you might have guessed, the

delimiters are where Mustache gets its name from!

Inside each tag is the name of a variable (in this case,

). When Mustache processes the template, it replaces each variable name with an actual value.

But where does Mustache get the values for the variables in the template? The answer is that, when you pass the template to the Mustache processor, you also pass an object or hash containing the variable names and their associated values:

The exact format of the object or hash depends on the language you're using. The above example is a JavaScript (or JSON) object. But essentially you pass Mustache a list of name/value pairs.

When you pass the template and object to the Mustache processor, it combines the two and returns the final HTML, with the variable names replaced by their values:

Installing Mustache

The Mustache processor is available in a wide range of languages. As a general rule, you install Mustache like this:

Click the ZIP button to download the repository Zip file.

Unzip the downloaded file, and move the resulting folder to your website.

Include the relevant library file (such as

) in your web pages or server-side scripts.

There are some subtle differences between the Mustache implementations for different languages. Make sure you read the documentation specific to the Mustache processor you're using.

Running the Mustache processor

The syntax for calling the Mustache processor depends on the language you are using. Essentially though, you call the

method, passing in the template string followed by the data object. The processor then combines the template with the data object to produce the final markup string, which it returns.

output = Mustache.render( template, data );

$m = new Mustache; $output = $m->render( $template, $data );

use Template::Mustache; $output = Template::Mustache->render( $template, $data );

A Mustache demo page

Let's get going with a simple demo page that shows Mustache in action. We'll use

— the JavaScript implementation of Mustache — so that we can run the demo straight in the browser, without needing to write any server-side code.

The JavaScript version of Mustache is very handy for Ajax-driven web apps. Your app can pull JSON data from the server using Ajax, then combine the data with a Mustache template to create the final markup for displaying in the page. You'll learn how to do this in the complete example at the end of the tutorial.

To start building the demo page, you first need to install the JavaScript Mustache processor:

Create a folder somewhere on your computer

The HTML page

Here's the demo page — save it as

in the same folder as your

This page contains the following elements:

This contains the CSS to display the demo page. We'll create this file shortly.

We've included jQuery, the

JavaScript file (which we'll create in a moment).

This contains the Mustache template that we want to use. Notice that the template is mainly HTML markup, with a few Mustache tags, indicated by the

This contains JavaScript code that creates an object variable called

When clicked, this button calls a JavaScript function,

, which runs the Mustache processor to produce the finished HTML. We'll create this function in a moment.

This will contain the finished HTML generated by the Mustache processor, displayed as source markup.

This will contain the finished HTML generated by the Mustache processor and rendered by the browser, so that you can see how the ends result looks in the page.

The style sheet

Here's the style sheet for the page — save it as

How to keep mustache in shape

body { font-family: "Georgia", serif; line-height: 1.8em; color: #333; } #wrap { width: 57em; } textarea,.result div { font-size:.8em; width: 29em; height: 15em; margin: 1em 2em 2em 2em; padding: 1em; } textarea { font-family: Courier, fixed; }.template,.html,.data,.result { float: left; }.result div { border: 1px solid #333; } h3 { display block; margin: 2em 0 0 1.5em; }.process { display: block; clear: both; margin: 1em 0; width: 56em; text-align: center; } button { font-size: 1.5em; margin-top: 1em; }

This CSS aligns the various elements in the demo page — including the

The JavaScript

Finally, here's the JavaScript code for the demo page — save it as

function process() { var template, data, html; template = $('#template').val(); eval( $('#data').val() ); html = Mustache.render( template, data ); $('#html').text( html ); $('#result').html( html ); }

, runs when the user presses the Process Template button in the page. The function:

Extracts the template code stored in the

, and stores it in the variable

, passing in the Mustache template stored in

, as well as the data object stored in

. This generates the finished markup, which the code then stores in the

Inserts the markup stored in

, so that the markup can be both viewed by the user and rendered by the browser.

Try it out!

in your browser, or press the button below:

You'll see four boxes in the page. The Mustache Template box and the Data Object box are filled with the template code and the JavaScript code to generate the data object. The HTML Result and How It Looks boxes are initially blank.

Now press the Process Template button. This runs the Mustache processor, passing in the template and the data object. The resulting markup then appears in the HTML Result box, and is rendered in the How It Looks box:

Try editing the contents of the Mustache Template and Data Object boxes, then pressing the Process Template button again to see the results. This is a great way to play with Mustache and see what it can do.

Delving deeper into variables

So far you've learned how to create a Mustache variable by placing the variable name inside a Mustache tag, then creating a property with the same name inside your data object.

Let's look at some more features of Mustache variables. In this section you'll explore expressions and functions; how to access object properties and methods within templates; how Mustache handles missing variables; and how Mustache HTML-escapes certain characters within variable values.

Expressions and functions

With most languages, you're not limited to using literal values in your Mustache data objects. You can also use expressions and functions as values. This means your object can contain properties such as:

"price": parseFloat(netPrice+tax).toFixed(2)

is a function). Mustache then replaces the variable tag with the result of the expression, or the return value of the function, in the output.

One notable exception to this rule is JSON, which doesn't allow expressions as property values.

Accessing object properties and methods

Your data object can also contain other objects — for example:

{ "name": "SuperWidget", "colour": "Green", "price": { "regular": "19.99", "discount": "14.99" } }

To access a property or method of an object from within your Mustache template, you can use the dot (

Combining the above object and template produces the following output:

Missing variables

If you use a variable name in your template that doesn't appear in the corresponding data object, Mustache simply replaces the tag with an empty string. For example, this Mustache template:

when combined with this data object:

HTML escaping

Mustache automatically replaces certain HTML characters, such as

, with their equivalent HTML entities, such as

. If you don't want Mustache to HTML-escape a value, put triple braces around the variable name instead of double braces, like this:

Alternatively, you can place an ampersand after the opening double brace, like this:

A quick demo

Press the button below to see expressions, functions, accessing object properties, missing variables, and HTML escaping in action:

Working with sections

Sections let you add more power to your templates. Using sections, you can display a chunk of markup only if a certain condition is true (or false). You can also create repeating sections, which let you display lists and tables of data.

The basic syntax for a section looks like this:

{{#sectionName}} (more markup in here) {{/sectionName}}

Conditional sections

A conditional section is a block of markup that is displayed only if a certain condition is true. Here's an example.

Say your template looks like this:

If your data object looks like this:

the output will look like this:

On the other hand, if your data object looks like this:

Inverted sections

Inverted sections are the opposite of conditional sections. With an inverted section, the section's content is only output if the section's variable is false.

You create an inverted section by replacing the

element in the above example is only output if the value of the

To try out conditional sections and inverted sections, press the button below:

Press the Process Template button. Since the value of

, the "Buy Now!" link is displayed. Now try changing

Now when you press the Process Template button, the "Sorry, out of stock" message is displayed instead.

Repeating sections

Repeating sections are handy when you want to display a list or table of related data in the page. You create a repeating section like this:

Add a section ( for example,

) to your Mustache template.

Inside the section, place the markup and any variable tags that you want to display for each item in the list.

Add a list (or array) property to your data object. Give the property the same name as the section (for example,

Most popular facial hair styles

Each item in the list should be an object containing the properties corresponding to the variable tags you added in Step 2.

The Mustache processor then loops through the objects in the list. For each object, it replaces the variable tags in the section with the properties of the object, and outputs the section's markup.

Here's an example. First, the Mustache template:

And finally, the resulting output:

You can try out this example by pressing the button below:

Adding comments in Mustache

To insert a comment in a Mustache template, use the following syntax:

The whole comment tag is ignored by the Mustache processor.

Including Mustache templates with partials

Partials allow you to include one Mustache template inside another. This lets you keep your templates modular and organized.

In the JavaScript version of Mustache, you create an object containing all your partials:

var partials = { myPartial: "templateString", anotherPartial: "templateString"... };

Then, to insert a partial at a given point in a template, you use the syntax:

So to include the partial called

You can also include a partial within another partial, which lets you make nested includes.

Then, when you run the Mustache processor, you pass your partials object as the third argument, like this:

html = Mustache.render( template, data, partials );

Here's an example of partials in action. First, we'll create a couple of partials,

displays a product's name, colour and price, It also includes the

partial, which displays the "Buy Now!" link (or the "Sorry, out of stock" message if the product is out of stock).

Now let's create our template:

This template displays the product name inside an

element, then includes the

partial to display the product info.

Here's the data object that we'll use for our product data:

var data = { "name": "SuperWidget", "colour": "Green", "price": "19.99", "inStock": true }

Finally, we call the Mustache

method to create the final markup:

html = Mustache.render( template, data, partials ); alert( html );

This displays the following alert box:

Bringing it all together

Let's build a complete JavaScript demo that shows off some of Mustache's great features. We'll create a simple product list page with a Get Products button. When the user clicks the button, the JavaScript code uses Ajax to fetch the product data from the server, then uses a Mustache template to display the product data in an HTML table.

The HTML page

First, create the main page for the product list demo. Save the following code as

in a folder in your website. Also, copy the

files that you used earlier in the tutorial into the same folder.

<!doctype html> <html> <head> <title>Complete Mustache Demo: Product List</title> <meta charset="utf-8"> <link rel="stylesheet" href="style.css" /> <script type="text/javascript" src="http://code.jquery.com/jquery-1.7.1.min.js"></script> <script type="text/javascript" src="mustache.js"></script> <script type="text/javascript"> var template, data, html; var gotTemplate, gotData; function getProducts() { gotTemplate = gotData = false; $.get( "productListTemplate.mustache", null, function( ajaxData ) { template = ajaxData; gotTemplate = true; if ( gotData ) processTemplate(); } ); $.getJSON( "products.txt", null, function( ajaxData ) { data = ajaxData; gotData = true; if ( gotTemplate ) processTemplate(); } ); } function processTemplate() { html = Mustache.render( template, data ); $('#productList').html( html ); } </script> <style> table { width: 100%; border-spacing: 1px; border: none; } th { text-align: left; background-color: #EFEFD7; color: #000000; font-weight: bold; padding: 4px; } td { text-align: left; background-color: #F7F7E6; color: #000000; font-weight: normal; padding: 4px; } button { margin-bottom: 20px; } </style> </head> <body> <h1>Complete Mustache Demo: Product List</h1> <button >Get Products</button> <div id="productList"> </div> </body> </html>

A Get Products button that, when pressed, calls the JavaScript function

that will contain the products table.

The page also contains the JavaScript to fetch and display the product list. First the JavaScript sets up some variables:

will hold the Mustache template, the data object, and the final product list HTML respectively.

will be used to track when the JavaScript has finished fetching the Mustache template and the product data respectively. When both have been fetched, the list can be displayed.

function runs when the user presses the Get Products button. It makes two calls to jQuery Ajax methods in order to retrieve two files from the server:

productListTemplate.mustache

The function fetches this file using the jQuery

method. This is the Mustache template file for the products list; we'll create this file in a moment.

This file is fetched using the jQuery

method. This method works like

, but is specifically designed for retrieving JSON data, which it then parses and turns into a JavaScript object.

contains the product data in JSON format. Again, we'll create this in a minute.

With both Ajax requests, the code passes in an anonymous callback function that runs once the request completes. Each function does the following:

It stores the returned data in the appropriate variable (

It set the appropriate tracking variable to

If both tracking variables have been set to

to display the product list.

to create the product list markup, passing in the Mustache template stored in

, and the data object stored in

Mustache shape up

. It stores the markup in the

variable, which it then passes to jQuery's

method to insert the markup into the

, displaying the table to the user.

The Mustache template

Here's the Mustache template that displays the product list table — save it as

productListTemplate.mustache

As you can see, the template is HTML markup interspersed with Mustache tags. The template comprises:

A header row containing the column headers: Product, Colour, Price and Buy.

Mustache section. This section displays a row of product data in the table. Since the

property in our data object is an array of objects (as you'll see in a moment), this section will run repeatedly to display all the rows in the products table.

Mustache variables to display the product name, colour, and price.

Two conditional sections. The markup between

; it comprises a dummy "Buy Now!" link that uses the

variable to identify the product. The markup between

; it simply displays an "Out of Stock" message.

The data file

The last file we need to create contains the product data in JSON format. Save the following code as

{ "product": [ { "id": 1, "name": "SuperWidget", "colour": "Green", "price": "19.99", "inStock": true }, { "id": 2, "name": "WonderWidget", "colour": "White", "price": "24.99", "inStock": true }, { "id": 3, "name": "MegaWidget", "colour": "Purple", "price": "29.99", "inStock": false }, { "id": 4, "name": "HyperWidget", "colour": "Yellow", "price": "49.99", "inStock": true } ] }

This file defines a JSON object that contains a

array contains four elements, each of which is an object representing a product. Each product object contains

In a real-world site or app, this file would likely be dynamically generated by a server-side script that pulls the data from a database, rather than stored as a static file on the server.

Try it out!

To try out the product list demo, browse to the URL for the

file in your website — for example,

http://mywebsite/productList.html

— or press the button below to see it running on our server:

Since the demo uses Ajax to fetch the template and data files, you need to view the demo running on a web server. Opening the

file directly in your browser probably won't work.

Now press the Get Products button in the page. When you do this, the

function runs, retrieving the

productListTemplate.mustache

files from the server via Ajax. Once the files have been fetched,

method to combine the Mustache template with the product data and produce the product list table, which is then displayed in the page:

Summary

In this article you've explored the Mustache template system, and seen how you can easily use it to build clean, logic-less templates. You've looked at:

What Mustache is, and why it's useful.

A basic example of a Mustache template with tags and variables, as well as a data object.

How to install the Mustache processor on your website.

Running the processor by calling the

Building a simple demo page that you can use to try out various Mustache features.

Using expressions and functions in data objects.

How to access object properties and methods in your Mustache templates.

What happens when Mustache can't find a variable.

How Mustache escapes HTML characters, and how to bypass escaping.

The concept of Mustache sections, including conditional sections, inverted sections, and repeating sections (loops).

How to add comments in Mustache templates.

Including one Mustache template inside another by using partials.

A complete example that uses JavaScript, jQuery, Ajax and Mustache to build a simple product list page.

There are a few more Mustache features worth checking out, including lambdas (which let you manipulate un-parsed sections of Mustache templates) and the ability to change the default Mustache delimiters,

Related articles

Responses to this article

11 responses (oldest first):

Post a response

Want to add a comment, or ask a question about this article? Post a response.

To post responses you need to be a member. Not a member yet? Signing up is free, easy and only takes a minute. Sign up now.