man/mustache.5.html in mustache-0.9.2 vs man/mustache.5.html in mustache-0.10.0
- old
+ new
@@ -104,27 +104,28 @@
replaced with a value, some nothing, and others a series of
values. This document explains the different types of Mustache tags.</p>
<h2>TAG TYPES</h2>
-<p>Tags are indicated by the double mustaches. <code>{{name}}</code> is a tag. Let's
-talk about the different types of tags.</p>
+<p>Tags are indicated by the double mustaches. <code>{{name}}</code> is a tag, as is
+<code>{{#name}}</code>. Let's talk about the different types of tags.</p>
<h3>Variables</h3>
<p>The most basic tag is the variable. A <code>{{name}}</code> tag in a basic
-template will try to call the <code>name</code> method on your view. If there is
-no <code>name</code> method, an exception will be raised.</p>
+template will try to find the <code>name</code> key or method on your view. If
+there is no <code>name</code> method, nothing will be rendered.</p>
<p>All variables are HTML escaped by default. If you want to return
unescaped HTML, use the triple mustache: <code>{{{name}}}</code>.</p>
<p>You can also use <code>&</code> to unescape a variable: <code>{{& name}}</code>. This may be
useful when changing delimiters (see "Set Delimter" below).</p>
<p>By default a variable "miss" returns an empty string. This can usually
-be configured in your Mustache library.</p>
+be configured in your Mustache library. The Ruby version of Mustache
+supports raising an exception in this situation, for instance.</p>
<p>Template:</p>
<pre><code>* {{name}}
* {{age}}
@@ -146,77 +147,95 @@
*
* &lt;b&gt;GitHub&lt;/b&gt;
* <b>GitHub</b>
</code></pre>
-<h3>Boolean Sections</h3>
+<h3>Sections</h3>
+<p>Sections render blocks of text one or more times, depending on the
+value of the referenced tag.</p>
+
<p>A section begins with a pound and ends with a slash. That is,
<code>{{#person}}</code> begins a "person" section while <code>{{/person}}</code> ends it.</p>
-<p>If the <code>person</code> key exists and calling it returns false, the HTML
-between the pound and slash will not be displayed.</p>
+<p>If the <code>person</code> key exists and calling it returns false or an empty
+list, the HTML between the pound and slash will not be displayed.</p>
-<p>If the <code>person</code> method exists and calling it returns true, the HTML
-between the pound and slash will be rendered and displayed.</p>
+<p>If the <code>person</code> method exists and calling it returns true or an
+object, the HTML between the pound and slash will be rendered and
+displayed exactly one time. The object that was returned by the
+<code>person</code> method will become the context of the block, as well.</p>
+<p>If the <code>person</code> method exists and calling it returns a non-empty list,
+the text in the block will be displayed 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.</p>
+
<p>Template:</p>
<pre><code>{{#person}}
Shown!
{{/person}}
{{#anything_else}}
Never shown!
{{/anything_else}}
+{{#repo}}
+ <b>{{name}}</b>
+{{/repo}}
</code></pre>
<p>Hash:</p>
<pre><code>{
- "person": true
+ "person": true,
+ "repo": [
+ { "name": "resque" },
+ { "name": "hub" },
+ { "name": "rip" },
+ ]
}
</code></pre>
<p>Output:</p>
<pre><code>Shown!
+<b>resque</b>
+<b>hub</b>
+<b>rip</b>
</code></pre>
-<h3>Enumerable Sections</h3>
+<h3>Inverted Sections</h3>
-<p>Enumerable sections are syntactically identical to boolean sections in
-that they begin with a pound and end with a slash. The difference,
-however, is in the view: if the method called returns an enumerable,
-the section is repeated as the enumerable is iterated over.</p>
+<p>An inverted section begins with a caret (hat) and ends with a
+slash. That is <code>{{^person}}</code> begins a "person" inverted section while
+<code>{{/person}}</code> ends it.</p>
-<p>Each item in the enumerable is expected to be a hash which will then
-become the context of the corresponding iteration. In this way we can
-construct loops.</p>
+<p>While sections can be used to render text one or more times based on the
+value of the key given, inverted sections may render text once based
+on the inverse value of the key given. That is, they will be rendered
+if the key doesn't exist, is false, or is an empty list.</p>
<p>Template:</p>
<pre><code>{{#repo}}
<b>{{name}}</b>
{{/repo}}
+{{^repo}}
+ No repos :(
+{{/repo}}
</code></pre>
<p>Hash:</p>
<pre><code>{
- "repo": [
- { "name": "resque" },
- { "name": "hub" },
- { "name": "rip" },
- ]
+ "repo": []
}
</code></pre>
<p>Output:</p>
-<pre><code><b>resque</b>
-<b>hub</b>
-<b>rip</b>
+<pre><code>No repos :(
</code></pre>
<h3>Comments</h3>
<p>Comments begin with a bang and are ignored. The following template:</p>
@@ -231,12 +250,28 @@
<h3>Partials</h3>
<p>Partials begin with a greater than sign, like <code>{{> box}}</code>.</p>
-<p>It is useful to think of partials as a "template expansion" - that is,
-the actual partial tag will be replaced with the content of the
-partial. Therefor partials share the current context.</p>
+<p>Partials are rendered at runtime (as opposed to compile time), so
+recursive partials are possible. Just avoid infinite loops.</p>
+
+<p>They also inherit the calling context. Whereas in ERB you may have
+this:</p>
+
+<pre><code><%= partial :next_more, :start => start, :size => size %>
+</code></pre>
+
+<p>Mustache requires only this:</p>
+
+<pre><code>{{> next_more}}
+</code></pre>
+
+<p>Why? Because the <code>next_more.mustache</code> file will inherit the <code>size</code> and
+<code>start</code> methods from the calling context.</p>
+
+<p>In this way you may want to think of partials as includes, or template
+expansion, even though it's not literally true.</p>
<p>For example, this template and partial:</p>
<pre><code>base.mustache:
<h2>Names</h2>