1MUSTACHE(5)                     Mustache Manual                    MUSTACHE(5)
2
3
4

NAME

6       mustache - Logic-less templates.
7

SYNOPSIS

9       A typical Mustache template:
10
11
12
13           Hello {{name}}
14           You have just won {{value}} dollars!
15           {{#in_ca}}
16           Well, {{taxed_value}} dollars, after taxes.
17           {{/in_ca}}
18
19
20
21       Given the following hash:
22
23
24
25           {
26             "name": "Chris",
27             "value": 10000,
28             "taxed_value": 10000 - (10000 * 0.4),
29             "in_ca": true
30           }
31
32
33
34       Will produce the following:
35
36
37
38           Hello Chris
39           You have just won 10000 dollars!
40           Well, 6000.0 dollars, after taxes.
41
42
43

DESCRIPTION

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
49       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

TAG TYPES

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
59   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
66       All variables are HTML escaped by default. If you want  to  return  raw
67       contents without escaping, use the triple mustache: {{{name}}}.
68
69       You  can also use & to return its raw contents: {{& name}}. This may be
70       useful when changing delimiters (see "Set Delimiter" below).
71
72       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
76       Template:
77
78
79
80           * {{name}}
81           * {{age}}
82           * {{company}}
83           * {{{company}}}
84
85
86
87       Hash:
88
89
90
91           {
92             "name": "Chris",
93             "company": "<b>GitHub</b>"
94           }
95
96
97
98       Output:
99
100
101
102           * Chris
103           *
104           * &lt;b&gt;GitHub&lt;/b&gt;
105           * <b>GitHub</b>
106
107
108
109   Sections
110       Sections render blocks of text zero or more  times,  depending  on  the
111       value of the key in the current context.
112
113       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
116       The behavior of the section is determined by the value of the key.
117
118       False Values or Empty Lists
119
120       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
123       Template:
124
125
126
127           Shown.
128           {{#person}}
129             Never shown!
130           {{/person}}
131
132
133
134       Hash:
135
136
137
138           {
139             "person": false
140           }
141
142
143
144       Output:
145
146
147
148           Shown.
149
150
151
152       Non-Empty Lists
153
154       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
157       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
162       Template:
163
164
165
166           {{#repo}}
167             <b>{{name}}</b>
168           {{/repo}}
169
170
171
172       Hash:
173
174
175
176           {
177             "repo": [
178               { "name": "resque" },
179               { "name": "hub" },
180               { "name": "rip" }
181             ]
182           }
183
184
185
186       Output:
187
188
189
190           <b>resque</b>
191           <b>hub</b>
192           <b>rip</b>
193
194
195
196       Lambdas
197
198       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
204       Template:
205
206
207
208           {{#wrapped}}
209             {{name}} is awesome.
210           {{/wrapped}}
211
212
213
214       Hash:
215
216
217
218           {
219             "name": "Willy",
220             "wrapped": function() {
221               return function(text, render) {
222                 return "<b>" + render(text) + "</b>"
223               }
224             }
225           }
226
227
228
229       Output:
230
231
232
233           <b>Willy is awesome.</b>
234
235
236
237       Non-False Values
238
239       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
242       Template:
243
244
245
246           {{#person?}}
247             Hi {{name}}!
248           {{/person?}}
249
250
251
252       Hash:
253
254
255
256           {
257             "person?": { "name": "Jon" }
258           }
259
260
261
262       Output:
263
264
265
266           Hi Jon!
267
268
269
270   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
275       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
280       Template:
281
282
283
284           {{#repo}}
285             <b>{{name}}</b>
286           {{/repo}}
287           {{^repo}}
288             No repos :(
289           {{/repo}}
290
291
292
293       Hash:
294
295
296
297           {
298             "repo": []
299           }
300
301
302
303       Output:
304
305
306
307           No repos :(
308
309
310
311   Comments
312       Comments begin with a bang and are ignored. The following template:
313
314
315
316           <h1>Today{{! ignore me }}.</h1>
317
318
319
320       Will render as follows:
321
322
323
324           <h1>Today.</h1>
325
326
327
328       Comments may contain newlines.
329
330   Partials
331       Partials begin with a greater than sign, like {{> box}}.
332
333       Partials  are  rendered  at  runtime  (as  opposed to compile time), so
334       recursive partials are possible. Just avoid infinite loops.
335
336       They also inherit the calling context. Whereas  in  ERB  you  may  have
337       this:
338
339
340
341           <%= partial :next_more, :start => start, :size => size %>
342
343
344
345       Mustache requires only this:
346
347
348
349           {{> next_more}}
350
351
352
353       Why?  Because  the  next_more.mustache  file  will inherit the size and
354       start methods from the calling context.
355
356       In this way you may want to think of partials as includes, or  template
357       expansion, even though it´s not literally true.
358
359       For example, this template and partial:
360
361
362
363           base.mustache:
364           <h2>Names</h2>
365           {{#names}}
366             {{> user}}
367           {{/names}}
368
369           user.mustache:
370           <strong>{{name}}</strong>
371
372
373
374       Can be thought of as a single, expanded template:
375
376
377
378           <h2>Names</h2>
379           {{#names}}
380             <strong>{{name}}</strong>
381           {{/names}}
382
383
384
385   Set Delimiter
386       Set  Delimiter  tags start with an equal sign and change the tag delim‐
387       iters from {{ and }} to custom strings.
388
389       Consider the following contrived example:
390
391
392
393           * {{default_tags}}
394           {{=<% %>=}}
395           * <% erb_style_tags %>
396           <%={{ }}=%>
397           * {{ default_tags_again }}
398
399
400
401       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
406       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
411       Custom delimiters may not contain whitespace or the equals sign.
412
414       Mustache is Copyright (C) 2009 Chris Wanstrath
415
416       Original CTemplate by Google
417

SEE ALSO

419       mustache(1), http://mustache.github.io/
420
421
422
423DEFUNKT                          November 2016                     MUSTACHE(5)
Impressum