Mustache

js-templates

handlebars

https://mustache.github.com/ - done reading
https://github.com/janl/mustache.js/ - done reading
https://mustache.github.io/mustache.5.html - done reading
https://mustache.github.io/mustache.1.html - done reading
http://net.tutsplus.com/tutorials/javascript-ajax/quick-tip-using-the-mustache-template-library/ - done reading

What is Mustache?

Mustache is a a logic-less templating engine with libraries available for JavaScript and a variety of other languages. We call it "logic-less" because there are no if statements, else clauses, or for loops. Instead there are only tags and views.

What is a tag and what is a tag key?

Tags are indicated by the double mustaches that surround them. {{person}} is a tag, and {{#person}} is also a tag. In both examples we refer to person as the tag's key.

What is a view?

A view is an object containing the data and code needed to render the template. For example:

var context = {
  title: "Joe",
  calc: function () {
    return 2 + 4;
  }
};

A view is also known as the context object in other template engine. It is the object that contains the data that is to be processed by the template.

If mustache is logic-less, how can we iterate over arrays or do advanced processing?

If we need to use loop or conditional logic, we need to put our code into the view object itself. We will see more on this below.

How can we download, install or load mustache into our application?

  1. Download from the web site: Go to https://github.com/janl/mustache.js and click on the Download Zip button, extract the downloaded file, find the mustache.min.js file, copy it to your server and include it into your application using <script type="text/javascript" src="…"></script>
  2. npm
  3. bower

npm:

npm install mustache --save

bower:

bower install --save mustache

How can we use Mustache?

A quick example usage:

var context = {
  title: "Joe",
  calc: function () {
    return 2 + 4;
  }
};

var output = Mustache.render("{{title}} spends {{calc}}", view);

Another example, using the script tag to contain the text for the template:

<script id="template" type="x-tmpl-mustache">
Hello {{ name }}!
</script>

var template = $('#template').html();
Mustache.parse(template);   // optional, speeds up future uses
var result = Mustache.render(template, {name: "Luke"});
$('#target').html(result);

How can we load a template file from a server?

If your templates reside in individual files, you can load them asynchronously and render them when they arrive. Using jQuery:

$.get('template.mst', function(template) {
    var rendered = Mustache.render(template, {name: "Luke"});
    $('#target').html(rendered);
});

Can we use dot with mustache tag?

Yes. JavaScript's dot notation may be used to access keys that are properties of objects.

{
  "name": {
    "first": "Michael",
    "last": "Jackson"
  },
  "age": "RIP"
}

{{name.first}} {{name.last}}

What are the different tags types?

  1. {{tag_key}}: This is the typical variable tag
  2. {{{tag_key}}}: This is the typical variable tag without HTML escaping
  3. {{#tag_key}} ... {{/tag_key}}: This pair of tags define a section block
  4. {{^tag_key}} ... {{/tag_key}}: This pair of tags define an inverted section block
  5. {{> tag_key}}: partials
  6. {{! comment }}: comments

What is the definition of sections and section blocks?

{{#tag_key}} ... {{/tag_key}}

Sections render blocks of text one or more times, depending on the value of the key in the current context. A section begins with a pound and ends with a slash. That is, {{#person}} begins a person section, while {{/person}} ends it. The text between the two tags is referred to as that section's "block".

View:
{
  "stooges": [
    { "name": "Moe" },
    { "name": "Larry" },
    { "name": "Curly" }
  ]
}

Template:
{{#stooges}}
<b>{{name}}</b>
{{/stooges}}

In the above template, {{#stooges}} ... {{/stooges}} define the block. Notice that the tag key "stooges" also exists in the view object. The behavior of the section block enclosed inside {{#stooges}} ... {{/stooges}} depends on the value inside the view object.

If the key does not exist, or exists and has a value of null, undefined, false, 0, or NaN, or is an empty string or an empty list, the block will not be rendered.

View:

{
  "person": false
}

Template:

Shown.
{{#person}}
Never shown!
{{/person}}

Output:

Shown.

If the key exists and is not null, undefined, or false, and is not an empty list the block will be rendered one or more times.

When the value of a section is a list, the block is rendered once for each item in the list. The context of the block is set to the current item in the list for each iteration. In this way we can loop over collections.

View:

{
  "stooges": [
    { "name": "Moe" },
    { "name": "Larry" },
    { "name": "Curly" }
  ]
}

Template:

{{#stooges}}
<b>{{name}}</b>
{{/stooges}}

Output:

<b>Moe</b>
<b>Larry</b>
<b>Curly</b>

In the above code, the block is rendered once for each item in the list. The context for the block is set to the current item in the list for each iteration. The name inside the block is just a typical variable tag.

If the block reference a function, it will be called in the context of the current item in the list on each iteration.

View:

{
  "beatles": [
    { "firstName": "John", "lastName": "Lennon" },
    { "firstName": "Paul", "lastName": "McCartney" },
    { "firstName": "George", "lastName": "Harrison" },
    { "firstName": "Ringo", "lastName": "Starr" }
  ],
  "name": function () {
    return this.firstName + " " + this.lastName;
  }
}

Template:

{{#beatles}}
* {{name}}
{{/beatles}}

Output:

* John Lennon
* Paul McCartney
* George Harrison
* Ringo Starr

In the above template, "beatles" define the section block which use the {{name}} tag, which is a function defined in the view object. The {{name}} function will be invoke once for each item in the list. Notice that "beatles" in the view object is still an array, just like "stooges" in the previous example. And in the above example, name is a function defined in the view object, but in the previous example, {{name}} does not exist in the view object itself, but exists as individual objects in the "stooges" array.

If the value of a section key is a function, it is called with the section's literal block of text, un-rendered, as its first argument. The second argument is a special rendering function that uses the current view as its view argument. It is called in the context of the current view object.

{
  "name": "Tater",
  "bold": function () {
    return function (text, render) {
      return "<b>" + render(text) + "</b>";
    }
  }
}

{{#bold}}Hi {{name}}.{{/bold}}

<b>Hi Tater.</b>

In the above template, "bold" defines the section block, and it is also the key in the view object, and its value in the view object is a function which returns a function. Mustache.js requires a function that returns the function to be used. That function gets passed the text to be rendered (all the text within the section) and a function that will render the section block. Whatever that function returns will be the result of that section.

You can think of a section as a sub-template. The render function is the compiled template function for that block or section.

What is {{.}}?

When looping over an array of strings, a . can be used to refer to the current item in the list.

{{.}}

In other words, the above construct just displays the individual strings within the array.

View:

{
  "musketeers": ["Athos", "Aramis", "Porthos", "D'Artagnan"]
}

Template:

{{#musketeers}}
* {{.}}
{{/musketeers}}

Output:

* Athos
* Aramis
* Porthos
* D'Artagnan

What is an inverted section?

An inverted section opens with {{^section}} instead of {{#section}}. The block of an inverted section is rendered only if the value of that section's tag is null, undefined, false, or an empty list.

{
  "repos": []
}

{{#repos}}<b>{{name}}</b>{{/repos}}
{{^repos}}No repos :({{/repos}}

No repos :(

How can we comment out a block of template?

Comments begin with a bang and are ignored.

<h1>Today{{! ignore me }}.</h1>

<h1>Today.</h1>

Can we have newlines inside our comments?

Yes.

What are partials?

The concept of partials come from the Ruby community.

Partials begin with a greater than sign, like {{> box}}. Partials are rendered at runtime (as opposed to compile time), so recursive partials are possible. Just avoid infinite loops. They also inherit the calling context.

ERB you may have this:

<%= partial :next_more, :start => start, :size => size %>

Mustache requires only this:

{{> next_more}}

Because the next_more.mustache file will inherit the size and start variables from the calling context. In this way you may want to think of partials as includes, or template expansion, even though it's not literally true.

For example, this template and partial:

base.mustache:
<h2>Names</h2>
{{#names}}
  {{> user}}
{{/names}}

user.mustache:
<strong>{{name}}</strong>

Can be thought of as a single, expanded template:

<h2>Names</h2>
{{#names}}
  <strong>{{name}}</strong>
{{/names}}

In mustache.js an object of partials may be passed as the third argument to Mustache.render. The object should be keyed by the name of the partial, and its value should be the partial text.

Mustache.render(template, view, {
  user: userTemplate
});

What is a Set Delimiter?

Set Delimiter tags start with an equals sign and change the tag delimiters from {{ and }} to custom strings. Consider the following contrived example:

* {{ default_tags }}
{{=<% %>=}}
* <% erb_style_tags %>
<%={{ }}=%>
* {{ default_tags_again }}

The ability to use custom delimiter is useful for languages like TeX, where double-braces may occur in the text and are awkward to use for markup.

Custom delimiters may not contain whitespace or the equals sign.

How can we pre-parse and cache templates?

By default, when mustache.js first parses a template it keeps the full parsed token tree in a cache. The next time it sees that same template it skips the parsing step and renders the template much more quickly. If you'd like, you can do this ahead of time using mustache.parse.

Mustache.parse(template);

// Then, sometime later.
Mustache.render(template, view);

How can we prevent mustache from doing HTML escaping?

The most basic tag type is a simple variable. A {{name}} tag renders the value of the name key in the current context. If there is no such key, nothing is rendered. All variables are HTML-escaped by default. If you want to render unescaped HTML, use the triple mustache: {{{name}}}. You can also use & to unescape a variable.

{{&company}}

How can we prevent mustache from interpreting a tag?

If you want name not to be interpreted as a mustache tag, but rather to appear exactly as name in the output, you must change and then restore the default delimiter. See the "Set Delimiter' section for more information about custom delimiters:

{{=<% %>=}}
* {{company}}
<%={{ }}=%>

Can we use mustache on the server side?

Yes. You can use mustache on the server side with Node or any other language. See http://mustache.github.io/

How can we install and use the command-line tool?

mustache.js is shipped with a node based command line tool. It might be installed as a global tool on your computer to render a mustache template of some kind:

npm install -g mustache
mustache dataView.json myTemplate.mustache > output.html
cat dataView.json | mustache - myTemplate.mustache > output.html

as a package.json devDependency in a build process maybe:

npm install mustache --save-dev

{
  "scripts": {
    "build": "mustache dataView.json myTemplate.mustache > public/output.html"
  }
}

npm run build

The command line tool is basically a wrapper around Mustache.render so you get all the features. If your templates use partials you should pass paths to partials using -p flag:

mustache -p path/to/partial1.mustache -p path/to/partial2.mustache dataView.json myTemplate.mustache
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License