1MUSTACHE(5) Mustache Manual MUSTACHE(5)
2
6 mustache - Logic-less templates.
7
9 A typical Mustache template:
10 Hello {{name}}
14 You have just won {{value}} dollars!
15 {{#in_ca}}
16 Well, {{taxed_value}} dollars, after taxes.
17 {{/in_ca}}
18 Given the following hash:
22 {
26 "name": "Chris",
27 "value": 10000,
28 "taxed_value": 10000 - (10000 * 0.4),
29 "in_ca": true
30 }
31 Will produce the following:
35 Hello Chris
39 You have just won 10000 dollars!
40 Well, 6000.0 dollars, after taxes.
41
45 Mustache can be used for HTML, config files, source code - anything. It
46 works by expanding tags in a template using values provided in a hash
47 or object.
48 We call it "logic-less" because there are no if statements, else
50 clauses, or for loops. Instead there are only tags. Some tags are
51 replaced with a value, some nothing, and others a series of values.
52 This document explains the different types of Mustache tags.
53
55 Tags are indicated by the double mustaches. {{person}} is a tag, as is
56 {{#person}}. In both examples, we´d refer to person as the key or tag
57 key. Let´s talk about the different types of tags.
58 Variables
60 The most basic tag type is the variable. A {{name}} tag in a basic tem‐
61 plate will try to find the name key in the current context. If there is
62 no name key, the parent contexts will be checked recursively. If the
63 top context is reached and the name key is still not found, nothing
64 will be rendered.
65 All variables are HTML escaped by default. If you want to return raw
67 contents without escaping, use the triple mustache: {{{name}}}.
68 You can also use & to return its raw contents: {{& name}}. This may be
70 useful when changing delimiters (see "Set Delimiter" below).
71 By default a variable "miss" returns an empty string. This can usually
73 be configured in your Mustache library. The Ruby version of Mustache
74 supports raising an exception in this situation, for instance.
75 Template:
77 * {{name}}
81 * {{age}}
82 * {{company}}
83 * {{{company}}}
84 Hash:
88 {
92 "name": "Chris",
93 "company": "<b>GitHub</b>"
94 }
95 Output:
99 * Chris
103 *
104 * <b>GitHub</b>
105 * <b>GitHub</b>
106 Sections
110 Sections render blocks of text zero or more times, depending on the
111 value of the key in the current context.
112 A section begins with a pound and ends with a slash. That is, {{#per‐
114 son}} begins a "person" section while {{/person}} ends it.
115 The behavior of the section is determined by the value of the key.
117 False Values or Empty Lists
119 If the person key exists and has a value of false or an empty list, the
121 HTML between the pound and slash will not be displayed.
122 Template:
124 Shown.
128 {{#person}}
129 Never shown!
130 {{/person}}
131 Hash:
135 {
139 "person": false
140 }
141 Output:
145 Shown.
149 Non-Empty Lists
153 If the person key exists and has a non-false value, the HTML between
155 the pound and slash will be rendered and displayed one or more times.
156 When the value is a non-empty list, the text in the block will be dis‐
158 played once for each item in the list. The context of the block will be
159 set to the current item for each iteration. In this way we can loop
160 over collections.
161 Template:
163 {{#repo}}
167 <b>{{name}}</b>
168 {{/repo}}
169 Hash:
173 {
177 "repo": [
178 { "name": "resque" },
179 { "name": "hub" },
180 { "name": "rip" }
181 ]
182 }
183 Output:
187 <b>resque</b>
191 <b>hub</b>
192 <b>rip</b>
193 Lambdas
197 When the value is a callable object, such as a function or lambda, the
199 object will be invoked and passed the block of text. The text passed is
200 the literal block, unrendered. {{tags}} will not have been expanded -
201 the lambda should do that on its own. In this way you can implement
202 filters or caching.
203 Template:
205 {{#wrapped}}
209 {{name}} is awesome.
210 {{/wrapped}}
211 Hash:
215 {
219 "name": "Willy",
220 "wrapped": function() {
221 return function(text, render) {
222 return "<b>" + render(text) + "</b>"
223 }
224 }
225 }
226 Output:
230 <b>Willy is awesome.</b>
234 Non-False Values
238 When the value is non-false but not a list, it will be used as the con‐
240 text for a single rendering of the block.
241 Template:
243 {{#person?}}
247 Hi {{name}}!
248 {{/person?}}
249 Hash:
253 {
257 "person?": { "name": "Jon" }
258 }
259 Output:
263 Hi Jon!
267 Inverted Sections
271 An inverted section begins with a caret (hat) and ends with a slash.
272 That is {{^person}} begins a "person" inverted section while {{/per‐
273 son}} ends it.
274 While sections can be used to render text zero or more times based on
276 the value of the key, inverted sections may render text once based on
277 the inverse value of the key. That is, they will be rendered if the key
278 doesn´t exist, is false, or is an empty list.
279 Template:
281 {{#repo}}
285 <b>{{name}}</b>
286 {{/repo}}
287 {{^repo}}
288 No repos :(
289 {{/repo}}
290 Hash:
294 {
298 "repo": []
299 }
300 Output:
304 No repos :(
308 Comments
312 Comments begin with a bang and are ignored. The following template:
313 <h1>Today{{! ignore me }}.</h1>
317 Will render as follows:
321 <h1>Today.</h1>
325 Comments may contain newlines.
329 Partials
331 Partials begin with a greater than sign, like {{> box}}.
332 Partials are rendered at runtime (as opposed to compile time), so
334 recursive partials are possible. Just avoid infinite loops.
335 They also inherit the calling context. Whereas in ERB you may have
337 this:
338 <%= partial :next_more, :start => start, :size => size %>
342 Mustache requires only this:
346 {{> next_more}}
350 Why? Because the next_more.mustache file will inherit the size and
354 start methods from the calling context.
355 In this way you may want to think of partials as includes, or template
357 expansion, even though it´s not literally true.
358 For example, this template and partial:
360 base.mustache:
364 <h2>Names</h2>
365 {{#names}}
366 {{> user}}
367 {{/names}}
368 user.mustache:
370 <strong>{{name}}</strong>
371 Can be thought of as a single, expanded template:
375 <h2>Names</h2>
379 {{#names}}
380 <strong>{{name}}</strong>
381 {{/names}}
382 Set Delimiter
386 Set Delimiter tags start with an equal sign and change the tag delim‐
387 iters from {{ and }} to custom strings.
388 Consider the following contrived example:
390 * {{default_tags}}
394 {{=<% %>=}}
395 * <% erb_style_tags %>
396 <%={{ }}=%>
397 * {{ default_tags_again }}
398 Here we have a list with three items. The first item uses the default
402 tag style, the second uses erb style as defined by the Set Delimiter
403 tag, and the third returns to the default style after yet another Set
404 Delimiter declaration.
405 According to ctemplates http://google-ctemplate.google‐
407 code.com/svn/trunk/doc/howto.html, this "is useful for languages like
408 TeX, where double-braces may occur in the text and are awkward to use
409 for markup."
410 Custom delimiters may not contain whitespace or the equals sign.
412
414 Mustache is Copyright (C) 2009 Chris Wanstrath
415 Original CTemplate by Google
417
419 mustache(1), http://mustache.github.io/
420DEFUNKT February 2015 MUSTACHE(5)