man/mustache.5.html in mustache-0.10.0 vs man/mustache.5.html in mustache-0.11.0
- old
+ new
@@ -1,10 +1,10 @@
<!DOCTYPE html>
<html>
<head>
<meta http-equiv='content-type' value='text/html;charset=utf8'>
- <meta name='generator' value='Ronn/v0.4.1'>
+ <meta name='generator' value='Ronn/v0.5'>
<title>mustache(5) -- Logic-less templates.</title>
<style type='text/css'>
body {margin:0}
#man, #man code, #man pre, #man tt, #man kbd, #man samp {
font-family:consolas,monospace;
@@ -104,24 +104,25 @@
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, as is
-<code>{{#name}}</code>. Let's talk about the different types of tags.</p>
+<p>Tags are indicated by the double mustaches. <code>{{person}}</code> is a tag, as
+is <code>{{#person}}</code>. In both examples, we'd refer to <code>person</code> as the key
+or tag key. 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 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>The most basic tag type is the variable. A <code>{{name}}</code> tag in a basic
+template will try to find the <code>name</code> key in the current context. If
+there is no <code>name</code> key, 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>
+useful when changing delimiters (see "Set Delimiter" below).</p>
<p>By default a variable "miss" returns an empty string. This can usually
be configured in your Mustache library. The Ruby version of Mustache
supports raising an exception in this situation, for instance.</p>
@@ -150,70 +151,142 @@
</code></pre>
<h3>Sections</h3>
<p>Sections render blocks of text one or more times, depending on the
-value of the referenced tag.</p>
+value of the key in the current context.</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 or an empty
-list, the HTML between the pound and slash will not be displayed.</p>
+<p>The behavior of the section is determined by the value of the key.</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><strong>False Values or Empty Lists</strong></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>If the <code>person</code> key exists and has a value of false or an empty
+list, the HTML between the pound and slash will not be displayed.</p>
<p>Template:</p>
-<pre><code>{{#person}}
- Shown!
-{{/person}}
-{{#anything_else}}
+<pre><code>Shown.
+{{#nothin}}
Never shown!
-{{/anything_else}}
-{{#repo}}
+{{/nothin}}
+</code></pre>
+
+<p>Hash:</p>
+
+<pre><code>{
+ "person": true,
+}
+</code></pre>
+
+<p>Output:</p>
+
+<pre><code>Shown.
+</code></pre>
+
+<p><strong>Non-Empty Lists</strong></p>
+
+<p>If the <code>person</code> key exists and has a non-false value, the HTML between
+the pound and slash will be rendered and displayed one or more times.</p>
+
+<p>When the value is 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>{{#repo}}
<b>{{name}}</b>
{{/repo}}
</code></pre>
<p>Hash:</p>
<pre><code>{
- "person": true,
"repo": [
{ "name": "resque" },
{ "name": "hub" },
{ "name": "rip" },
]
}
</code></pre>
<p>Output:</p>
-<pre><code>Shown!
-<b>resque</b>
+<pre><code><b>resque</b>
<b>hub</b>
<b>rip</b>
</code></pre>
+<p><strong>Lambdas</strong></p>
+
+<p>When the value is a callable object, such as a function or lambda, the
+object will be invoked and passed the block of text. The text passed
+is the literal block, unrendered. <code>{{tags}}</code> will not have been expanded
+- the lambda should do that on its own. In this way you can implement
+filters or caching.</p>
+
+<p>Template:</p>
+
+<pre><code>{{#wrapped}}
+ {{name}} is awesome.
+{{/wrapped}}
+</code></pre>
+
+<p>Hash:</p>
+
+<pre><code>{
+ "name": "Willy",
+ "wrapped": function() {
+ return function(text) {
+ return "<b>" + render(text) + "</b>"
+ }
+ }
+}
+</code></pre>
+
+<p>Output:</p>
+
+<pre><code><b>Willy is awesome.</b>
+</code></pre>
+
+<p><strong>Non-False Values</strong></p>
+
+<p>When the value is non-false but not a list, it will be used as the
+context for a single rendering of the block.</p>
+
+<p>Template:</p>
+
+<pre><code>{{#person?}}
+ Hi {{name}}!
+{{/person?}}
+</code></pre>
+
+<p>Hash:</p>
+
+<pre><code>{
+ "person?": { "name": "Jon" }
+}
+</code></pre>
+
+<p>Output:</p>
+
+<pre><code>Hi Jon!
+</code></pre>
+
<h3>Inverted Sections</h3>
<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>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
+value of the key, inverted sections may render text once based
+on the inverse value of the key. 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}}
@@ -246,10 +319,12 @@
<p>Will render as follows:</p>
<pre><code><h1>Today.</h1>
</code></pre>
+<p>Comments may contain newlines.</p>
+
<h3>Partials</h3>
<p>Partials begin with a greater than sign, like <code>{{> box}}</code>.</p>
<p>Partials are rendered at runtime (as opposed to compile time), so
@@ -274,34 +349,34 @@
<p>For example, this template and partial:</p>
<pre><code>base.mustache:
<h2>Names</h2>
-{{# names }}
- {{> user }}
-{{/ names }}
+{{#names}}
+ {{> user}}
+{{/names}}
user.mustache:
-<strong>{{ name }}</strong>
+<strong>{{name}}</strong>
</code></pre>
<p>Can be thought of as a single, expanded template:</p>
<pre><code><h2>Names</h2>
-{{# names }}
- <strong>{{ name }}</strong>
-{{/ names }}
+{{#names}}
+ <strong>{{name}}</strong>
+{{/names}}
</code></pre>
<h3>Set Delimiter</h3>
<p>Set Delimiter tags start with an equal sign and change the tag
-delimiters from {{ and }} to custom strings.</p>
+delimiters from <code>{{</code> and <code>}}</code> to custom strings.</p>
<p>Consider the following contrived example:</p>
-<pre><code>* {{ default_tags }}
+<pre><code>* {{default_tags}}
{{=<% %>=}}
* <% erb_style_tags %>
<%={{ }}=%>
* {{ default_tags_again }}
</code></pre>
@@ -323,16 +398,16 @@
<p>Original CTemplate by Google</p>
<h2>SEE ALSO</h2>
-<p>mustache(1), mustache(7), gem(1),
-<a href="http://defunkt.github.com/mustache/">http://defunkt.github.com/mustache/</a></p>
+<p>mustache(1), mustache(7),
+<a href="http://mustache.github.com/">http://mustache.github.com/</a></p>
<ol class='foot man'>
<li class='tl'>DEFUNKT</li>
- <li class='tc'>March 2010</li>
+ <li class='tc'>April 2010</li>
<li class='tr'>mustache(5)</li>
</ol>
</div>
</body>