Mustache.js is an implementation of the popular Mustache template system for JavaScript templating. Mustache touts itself as a logic-less template syntax. The idea behind this concept is not necessarily to have templates completely void of logic, but more to discourage the practice of including a large amount of business logic within your templates.
Mustache gets its name from the use of double curly braces, which resemble the shape of a mustache, as the default delimiter tags for templates. The major difference between Mustache templates and Underscore.js templates is that Mustache does not allow for the placement of arbitrary JavaScript within an alternate form of its tags; it only allows for expressions.
In its simplest form, a Mustache template maps values from a JavaScript object directly to their respective template expressions, represented by the keys for those object values. Take an object such as the one shown here, for example:
{
"name": {
"first": "Udis",
"last": "Petroyka"
},
"age": "82"
}
The values from this object can be represented in a Mustache template like this:
<p>{{name.first}} {{name.last}}</p>
<p>Age: {{age}}</p>
In this example, you can see that even nested object values can be accessed by using JavaScript dot notation, as shown with {{name.first}} and {{name.last}}:
<p>Udis Petroyka</p> <p>Age: 82</p>
Mustache templates also include the ability to render sections, or blocks of text. This involves using an alternate expression syntax that includes an opening and closing tag syntax. How a section is rendered depends on the value of the key being called for it.
Given a Boolean value, a section will render or not render depending on if that Boolean is true or false:
{
"name": {
"first": "Jarmond",
"last": "Dittlemore"
},
"email_subscriber": false
}
The delimiter syntax for sections consists of opening curly braces followed by the pound # symbol and the name of the property to start the section, and closing curly braces followed by the / symbol and the property name to end the section. This syntax is similar to HTML opening and closing tags:
<p>{{name.first}} {{name.last}}</p>
{{#email_subscriber}}
<p>Content here will not be shown for this user.</p>
{{/email_subscriber}}
In this example, the email_subscriber property is set to false, so the template would render the following HTML:
<p>Jarmond Dittlemore</p>
Essentially, the use of a section with a Boolean value is equivalent to an if conditional statement. Such a use case does indeed include logic, though in its most basic form. In this way, the term logic-less is proven to not be as stringent as it may initially be perceived.
Additionally, sections can be used to iterate over a list of items set as the value for a given object key. Within a section, the context, or variable scope, is shifted to that of the key that is being iterated over. Take the following parent key and corresponding list of values, for example:
{
"people": [
{ "firstName": "Peebo", "lastName": "Sanderson" },
{ "firstName": "Udis", "lastName": "Petroyka" },
{ "firstName": "Jarmond", "lastName": "Dittlemore" },
{ "firstName": "Chappy", "lastName": "Scrumdinger" }
]
}
Given a list of people and their names, a section can be used to render each person's name in an HTML unordered list:
<ul>
{{#people}}
<li>{{firstName}} {{lastName}}</li>
{{/people}}
</ul>
This template code would render the following HTML, given the preceding example object:
<ul>
<li>Peebo Sanderson</li>
<li>Udis Petroyka</li>
<li>Jarmond Dittlemore</li>
<li>Chappy Scrumdinger</li>
</ul>
Object property values can also be returned from lambdas, or functions that are passed to return values as data, to the current section's context:
{
"people": [
{ "firstName": "Peebo", "lastName": "Sanderson" },
{ "firstName": "Udis", "lastName": "Petroyka" },
{ "firstName": "Jarmond", "lastName": "Dittlemore" },
{ "firstName": "Chappy", "lastName": "Scrumdinger" }
],
"name": function() {
return this.firstName + ' ' + this.lastName;
}
}
In the case of a list, a lambda will return a value based on the context of the current list item for an iteration:
<ul>
{{#people}}
<li>{{name}}</li>
{{/people}}
</ul>
In this manner, the preceding template will produce the same output as the previous example:
<ul>
<li>Peebo Sanderson</li>
<li>Udis Petroyka</li>
<li>Jarmond Dittlemore</li>
<li>Chappy Scrumdinger</li>
</ul>
An inverted section in a Mustache template is one that is rendered only when the value for that section's key is false or falsy, such as null, undefined, 0, or an empty list []. Take the following object, for example:
{
"name": {
"first": "Peebo",
"last": "Sanderson"
},
"email_subscriber": false
}
An inverted section begins with a caret ^ symbol following the opening curly braces, rather than the pound # symbol used for a standard section. Given the preceding example object, the following template syntax can be used to render HTML for the false property value:
<p>{{name.first}} {{name.last}}</p>
{{^email_subscriber}}
<p>I am not an email subscriber.</p>
{{/email_subscriber}}
This template would render the following HTML, based on the false property value in the object:
<p>Peebo Sanderson</p> <p>I am not an email subscriber.</p>
Mustache templates also give you the ability to include comments within your templates. The advantage to using the Mustache syntax for your comments over HTML comments is that they will not be rendered in the HTML output, as would be the case with standard HTML comments:
<p>Udis likes to comment{{! hi, this comment won't be rendered }}</p>
<!- This is a standard HTML comment ->
Mustache comments are denoted by a bang, or exclamation point, following the opening curly braces. The preceding template code would render the following:
<p>Udis likes to comment</p> <!- This is a standard HTML comment ->
As shown, the Mustache template comment is not part of the rendered HTML, but the standard HTML comment is. The advantage to using Mustache template comments is in the payload size of the rendered HTML, which you want to keep as small as possible, and there are probably not many cases in which you would actually want to render comments in dynamic HTML. This allows you to have helpful comments for other developers in your template code without it putting a burden on the frontend of the application.
One of the most useful features of Mustache templates is the ability to include partials, or separate templates rendered at runtime within a compiled template. Conceptually, this feature is similar to includes for server-side template languages.
The syntax for partials uses a greater than > sign after the opening curly braces followed by the name of the partial. A common file naming convention is to prepend the uncompiled partial filenames with an underscore _. Consider the following two files:
user.hbs
<h3>{{name.first}} {{name.last}}</h3>
{{> user-details}}
_user-details.hbs
<ul>
{{^email_subscriber}}
<li>I am not an email subscriber</li>
{{/email_subscriber}}
<li>Age: {{age}}</li>
<li>Profession: {{profession}}</li>
</ul>
The call to include the partial file is indicated on the second line of user.hbs. This will parse _user-details.hbs in the same context as user.hbs. In a standard compiler setup, the underscore on the partial filename would be excluded from the key name, and the template would be stored within the partials namespace:
{
"name": {
"first": "Jarmond",
"last": "Dittlemore"
},
"email_subscriber": false,
"age": 24,
"profession": "Student"
}
Given the preceding example object, the fully rendered HTML from the template would look like the following:
<h3>Jarmond Dittlemore</h3>
<ul>
<li>I am not an email subscriber</li>
<li>Age: 24</li>
<li>Profession: Student</li>
</ul>
As you can see in the example, the key names from the object were used directly in the partial from the same context as the parent template.
One of the more unusual features of Mustache templates is the ability to set alternative delimiters from inside standard Mustache delimiter tags in a template. This is done by using an equals sign = following the opening standard delimiter tags, inserting the new opening delimiter followed by the new closing delimiter, and an equals sign followed by the standard closing delimiter tags:
{{=<% %>=}}
If this code is placed anywhere inside of a Mustache template, the delimiter tags from below that point will then use the new syntax:
{
"name": {
"first": "Chappy",
"last": "Scrumdinger"
},
"email_subscriber": false,
"age": 96,
"profession": "Oilman"
}
Given the preceding object, a template could be constructed using that data combined with alternative delimiter tags for parsing it:
<p>Standard tags: {{name.first}} {{name.last}}</p>
{{=<% %>=}}
<p>New tags - Age: <%age%></p>
<%={{ }}=%>
<p>Standard tags again - Profession: {{profession}}</p>
In this example, the standard tags are used once, then the set delimiters feature is used to change the tags to use the ERB style delimiters, then the tags are again changed back to the original standard delimiters:
<p>Standard tags: Chappy Scrumdinger</p> <p>New tags - Age: 96</p> <p>Standard tags again - Profession: Oilman</p>
The resulting HTML would look like the preceding code, rendered with two entirely different sets of delimiters inside of one template.
You can learn more about Mustache.js at github.com/janl/mustache.js, or learn about the original Mustache templates at mustache.github.io.