Permalink
Browse files

updated

  • Loading branch information...
1 parent b6c6159 commit 3e504148c5fb4d3851e6893f4fe1dd3d1c4c6420 @defunkt defunkt committed Apr 1, 2010
Showing with 65 additions and 30 deletions.
  1. +65 −30 mustache.5.html
View
@@ -106,14 +106,14 @@ <h2 id='NAME'>NAME</h2>
<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>
@@ -122,7 +122,8 @@ <h2 id='NAME'>NAME</h2>
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>
@@ -148,16 +149,26 @@ <h2 id='NAME'>NAME</h2>
* &lt;b&gt;GitHub&lt;/b&gt;
</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 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 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 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>
@@ -167,54 +178,62 @@ <h2 id='NAME'>NAME</h2>
{{#anything_else}}
Never shown!
{{/anything_else}}
+{{#repo}}
+ &lt;b&gt;{{name}}&lt;/b&gt;
+{{/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!
+&lt;b&gt;resque&lt;/b&gt;
+&lt;b&gt;hub&lt;/b&gt;
+&lt;b&gt;rip&lt;/b&gt;
</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}}
&lt;b&gt;{{name}}&lt;/b&gt;
{{/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>&lt;b&gt;resque&lt;/b&gt;
-&lt;b&gt;hub&lt;/b&gt;
-&lt;b&gt;rip&lt;/b&gt;
+<pre><code>No repos :(
</code></pre>
<h3>Comments</h3>
@@ -233,9 +252,25 @@ <h2 id='NAME'>NAME</h2>
<p>Partials begin with a greater than sign, like <code>{{&gt; 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>&lt;%= partial :next_more, :start =&gt; start, :size =&gt; size %&gt;
+</code></pre>
+
+<p>Mustache requires only this:</p>
+
+<pre><code>{{&gt; 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>

0 comments on commit 3e50414

Please sign in to comment.