The Mustache template logic-less language has five types of tags:

  1. Variables;
  2. Sections;
  3. Inverted Sections;
  4. Comments;
  5. Partials.

All those tags will be identified with mustaches, i.e. {{...}}.
Anything found in a template of this form is interpreted as a template marker.
All other text is considered formatting text and is output verbatim at template expansion time.

Marker Description
{{variable}} The variable name will be searched recursively within the current context (possibly with dotted names), and, if found, will be written as escaped HTML.
If there is no such key, nothing will be rendered.
{{{variable}}}
{{& variable}}
The variable name will be searched recursively within the current context, and, if found, will be written directly, without any HTML escape.
If there is no such key, nothing will be rendered.
{{#section}}
...
{{/section}}
Defines a block of text, aka section, which will be rendered depending of the section variable value, as searched in the current context:
- If section equals false or is an empty list [], the whole block won't be rendered;
- If section is non-false but not a list, it will be used as the context for a single rendering of the block;
- If section is a non-empty list, the text in the block will be rendered once for each item in the list - the context of the block will be set to the current item for each iteration.
{{^section}}
...
{{/section}}
Defines a block of text, aka inverted section, which will be rendered depending of the section variable inverted value, as searched in the current context:
- If section equals false or is an empty list, the whole block will be rendered;
- If section is non-false or a non-empty list, it won't be rendered.
{{! comment}} The comment text will just be ignored.
{{>partial}} The partial name will be searched within the registered partials list, then will be executed at run-time (so recursive partials are possible), with the current execution context.
{{=...=}} The delimiters (i.e. by default {{ }}) will be replaced by the specified characters (may be convenient when double-braces may appear in the text).

In addition to those standard markers, the mORMot implementation of Mustache features:

Marker Description
{{.}} This pseudo-variable refers to the context object itself instead of one of its members. This is particularly useful when iterating over lists.
{{-index}} This pseudo-variable returns the current item number when iterating over lists, starting counting at 1
{{#-first}}
...
{{/-first}}
Defines a block of text (pseudo-section), which will be rendered - or not rendered for inverted {{^-first}} - for the first item when iterating over lists
{{#-last}}
...
{{/-last}}
Defines a block of text (pseudo-section), which will be rendered - or not rendered for inverted {{^-last}} - for the last item when iterating over lists
{{#-odd}}
...
{{/-odd}}
Defines a block of text (pseudo-section), which will be rendered - or not rendered for inverted {{^-odd}} - for the odd item number when iterating over lists: it can be very usefull e.g. to display a list with alternating row colors
{{<partial}}
...
{{/partial}}
Defines an in-lined partial - to be called later via {{>partial}} - within the scope of the current template
{{"some text}} This pseudo-variable will supply the given text to a callback, which will for instance transform its content (e.g. translate it), before writing it to the output

This set of markers will allow to easily write any kind of content, without any explicit logic nor nested code.
As a major benefit, the template content could be edited and verified without the need of any Mustache compiler, since all those {{...}} markers will identify very clearly the resulting layout.

Variables

A typical Mustache template:

Hello {{name}}
You have just won {{value}} dollars!
Well, {{taxed_value}} dollars, after taxes.

Given the following hash:

{
  "name": "Chris",
  "value": 10000,
  "taxed_value": 6000
}

Will produce the following:

Hello Chris
You have just won 10000 dollars!
Well, 6000 dollars, after taxes.

You can note that variable tags are escaped for HTML by default. This is a mandatory security feature. In fact, all web applications which create HTML documents can be vulnerable to Cross-Site-Scripting (XSS) attacks unless data inserted into a template is appropriately sanitized and/or escaped. With Mustache, this is done by default. Of course, you can override it and force to not-escape the value, using variable or & variable.

For instance:

Template Context Output
* {{name}}
* {{age}}
* {{company}}
* {{{company}}}
{
"name": "Chris",
"company": "<b>GitHub</b>"
}
* Chris
*
* &lt;b&gt;GitHub&lt;/b&gt;
* <b>GitHub</b>

Variables resolve names within the current context with an optional dotted syntax, for instance:

Template Context Output
* {{people.name}}
* {{people.age}}
* {{people.company}}
* {{{people.company}}}
{
"name": "Chris",
"company": "<b>GitHub</b>"
}
* Chris
*
* &lt;b&gt;GitHub&lt;/b&gt;
* <b>GitHub</b>

Sections

Sections render blocks of text one or more times, depending on the value of the key in the current context.

In our "wining template" above, what happen if we do want to hide the tax details?
In most script languages, we may write an if ... block within the template. This is what Mustache avoids. So we define a section, which will be rendered on need.

The template becomes:

Hello {{name}}
You have just won {{value}} dollars!
{{#in_ca}}
Well, {{taxed_value}} dollars, after taxes.
{{/in_ca}}

Here, we created a new section, named in_ca.

Given the hash value of in_ca (and its presence), the section will be rendered, or not:

Context Output
{
"name": "Chris",
"value": 10000,
"taxed_value": 6000,
"in_ca": true
}
Hello Chris
You have just won 10000 dollars!
Well, 6000 dollars, after taxes.
{
"name": "Chris",
"value": 10000,
"taxed_value": 6000,
"in_ca": false
}
Hello Chris
You have just won 10000 dollars!
{
"name": "Chris",
"value": 10000,
"taxed_value": 6000
}
Hello Chris
You have just won 10000 dollars!

Sections also change the context of its inner block. It means that the section variable content becomes the top-most context which will be used to identify any supplied variable key.

Therefore, the following context will be perfectly valid: we can define taxed_value as a member of in_ca, and it will be rendered directly, since it is part of the new context.

Context Output
{
"name": "Chris",
"value": 10000,
"in_ca": {
  "taxed_value": 6000
  }
}

Hello Chris
You have just won 10000 dollars!
Well, 6000 dollars, after taxes.
{
"name": "Chris",
"value": 10000,
"taxed_value": 6000
}
Hello Chris
You have just won 10000 dollars!
{
"name": "Chris",
"value": 10000,
"taxed_value": 3000,
"in_ca": {
  "taxed_value": 6000
  }
}
Hello Chris
You have just won 10000 dollars!
Well, 6000 dollars, after taxes.

In the latest context above, there are two taxed_value variables.
The engine will use the one defined by the context in the in_ca section, i.e. in_ca.taxed_value; the one defined at the root context level (which equals 3000) is just ignored.

If the variable pointed by the section name is a list, the text in the block will be rendered once for each item in the list.
The context of the block will be set to the current item for each iteration.

In this way we can loop over collections.
Mustache allows any depth of nested loops (e.g. any level of master/details information).

Template Context Output
{{#repo}}
<b>name</b>
{{/repo}}
{
"repo": [
  {"name": "resque"},
  {"name": "hub"},
  {"name": "rip"} 
  ]
}
<b>resque</b>
<b>hub</b>
<b>rip</b>
{{#repo}}
<b>.</b>
{{/repo}}
{
"repo":
["resque", "hub", "rip"]
}
<b>resque</b>
<b>hub</b>
<b>rip</b>

The latest template makes use of the . pseudo-variable, which allows to render the current item of the list.

Inverted Sections

An inverted section begins with a caret (^) and ends as a standard (non-inverted) section.
They may render text once, based on the inverse value of the key. That is, the text block will be rendered if the key doesn't exist, is false, or is an empty list.

Inverted sections are usually defined after a standard section, to render some message in case no information will be written in the non-inverted section:

Template Context Output
{{#repo}}
<b>.</b>
{{/repo}}
{{^repo}}
No repos :(
{{/repo}}
{
"repo":
[]
}
No repos :(

Partials

Partials are some kind of external sub-templates which can be included within a main template, for instance to follow the same rendering at several places.
Just like functions in code, they do ease template maintainability and spare development time.

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, so can easily be re-used within a list section, or together with plain variables.

In practice, partials shall be supplied together with the data context - they could be seen as "template context".

For example, this "main" template uses a > user partial:

<h2>Names</h2>
{{#names}}
{{> user}}
{{/names}}

With the following template registered as "user":

<strong>{{name}}</strong>

Can be thought of as a single, expanded template:

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

In mORMot's implementations, you can also create some internal partials, defined as <partial ... /partial pseudo-sections.
It may decrease the need of maintaining multiple template files, and refine the rendering layout.

For instance, the previous template may be defined at once:

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

The same file will define both the partial and the main template. 

Note that we defined the internal partial after the main template, but we may have defined it anywhere in the main template logic: internal partials definitions are ignored when rendering the main template, just like comments.

Next article will detail the Mustache engine as implemented in mORMot's source code tree.
Now, a bit of practice!