mustache.js (hogan.js) API中文版
翻译API文档，如有疏漏，还望读者不吝赐教。
英文原文地址
名称
mustache - Logic-less模板.
概要
典型Mustache模板示例:
Hello {{name}}
You have just won {{value}} dollars!
{{#in_ca}}
Well, {{taxed_value}} dollars, after taxes.
{{/in_ca}}
hash:
{
"name": "Chris",
"value": 10000,
"taxed_value": 10000 - (10000 * 0.4),
"in_ca": true
}
输出:
Hello Chris
You have just won 10000 dollars!
Well, 6000.0 dollars, after taxes.
引言
Mustache 可用于HTML,配置文件，源代码等，通过扩展标签(Tags)来渲染模板，标签的值一般是hash或者js对象。
之所以称为"logic-less”，是因为它既没有if-else，也没有for循环，Mustache只有标签。一些标签会被值来替换，有些不会，还有些会被系列的值替换。本文主要介绍不同类型的Mustache标签。
TAG类型
标签(Tags) 使用{{ }}来描述. {{person}}是一个标签, {{#person}}也是标签. 在上面两个示例中，我们将person作为key值或者标签key，下面我们来看看不同类型的tag。
变量
变量是最基本的Tag类型，模板中的{{name}} 标签会尝试在上下文中寻找名称键值，如果没有找到，则不进行渲染。
所有的变量默认都进行了HTML转义，如果你想返回未转义的HTML，请使用三个花括号{{{name}}}。
另外你也可以使用&来跳过转义：{{& name}}，当改变分隔符的时候，这种方式比较有用。（见设置分隔符部分）。
默认情况下，变量缺失会返回一个空字符串。这通常由你所使用的Mustache库设置决定，但是Ruby版本的Mustache则会引发一个异常。例如：
模板:
* {{name}}
* {{age}}
* {{company}}
* {{{company}}}
hash:
{
"name": "Chris",
"company": "<b>GitHub</b>"
}
输出:
* Chris
*
* <b>GitHub</b>
* <b>GitHub</b>
块「Sections」
一次或者多次渲染大段的文本使用块，这依赖于上下文的键值。
块使用#起始，以/结束。即{{#person}}表示person块起始，而{{/person}}表示结束。块的表现由键值来决定。
假值以及空列表
如果person键存在假值或者空列表，在#，/之间的HTML则不会显示。
模板:
Shown.
{{#nothin}}
Never shown!
{{/nothin}}
Hash:
{
"person": true
}
输出:
Shown.
非空列表
如果person键存在，并且值为真，在#，/之间的HTML则会被渲染，并且进行一次或者多次渲染。
当值为非空列表时，列表中的文本则会被遍历展示。段落的内容则会被赋予到当前的列表项的for each迭代器。通过这种方式，我们可以遍历集合。
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.
模板:
{{#repo}}
<b>{{name}}</b>
{{/repo}}
Hash:
{
"repo": [
{ "name": "resque" },
{ "name": "hub" },
{ "name": "rip" }
]
}
输出:
<b>resque</b>
<b>hub</b>
<b>rip</b>
Lambdas表达式
当值是可调用的对象，例如function或者lambda，那么对象会被调用并且跳过文本。
被跳过的文字不进行渲染。{{tags}}讲不会被展开——由lambda自身来决定。通过这种方式，可以实现过滤器以及缓存。
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. {{tags}} will not have been expanded - the lambda should do that on its own. In this way you can implement filters or caching.
模板:
{{#wrapped}}
{{name}} is awesome.
{{/wrapped}}
Hash:
{
"name": "Willy",
"wrapped": function() {
return function(text, render) {
return "<b>" + render(text) + "</b>"
}
}
}
输出:
<b>Willy is awesome.</b>
真值
当值为真但不是一个列表的时候，渲染一次。
模板:
{{#person?}}
Hi {{name}}!
{{/person?}}
Hash:
{
"person?": { "name": "Jon" }
}
输出:
Hi Jon!
反向块「Inverted Sections」
反向块由^起始，/结束。即{{^person}} 表示person开始一个反向块，而{{/person}}结束。
While sections can be used to render text one or more times based on the 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.
Template:
{{#repo}}
<b>{{name}}</b>
{{/repo}}
{{^repo}}
No repos :(
{{/repo}}
Hash:
{
"repo": []
}
Output:
No repos :(
注释
Comments begin with a bang and are ignored. The following template:
<h1>Today{{! ignore me }}.</h1>
Will render as follows:
<h1>Today.</h1>
Comments may contain newlines.
Partials
Partials begin with a greater than sign, like {{> box}}.
Partials are rendered at runtime (as opposed to compile time), so recursive partials are possible. Just avoid infinite loops.
They also inherit the calling context. Whereas in ERB you may have this:
<%= partial :next_more, :start => start, :size => size %>
Mustache requires only this:
{{> next_more}}
Why? Because the next_more.mustache file will inherit the size and start methods from the calling context.
In this way you may want to think of partials as includes, or template expansion, even though it's not literally true.
For example, this template and partial:
base.mustache:
<h2>Names</h2>
{{#names}}
{{> user}}
{{/names}}
user.mustache:
<strong>{{name}}</strong>
Can be thought of as a single, expanded template:
<h2>Names</h2>
{{#names}}
<strong>{{name}}</strong>
{{/names}}
Set Delimiter
Set Delimiter tags start with an equal sign and change the tag delimiters from {{ and }} to custom strings.
Consider the following contrived example:
* {{default_tags}}
{{=<% %>=}}
* <% erb_style_tags %>
<%={{ }}=%>
* {{ default_tags_again }}
Here we have a list with three items. The first item uses the default tag style, the second uses erb style as defined by the Set Delimiter tag, and the third returns to the default style after yet another Set Delimiter declaration.
According to ctemplates, this “is useful for languages like TeX, where double-braces may occur in the text and are awkward to use for markup.”
自定义分隔符不能包含空格或者等号。
版权
Mustache is Copyright © 2009 Chris Wanstrath
Original CTemplate by Google