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 :(

##註釋 註釋由一個!開始，以下面的模板所示：

<h1>Today{{! ignore me }}.</h1>

將會被渲染成下面的HTML:

<h1>Today.</h1>

註釋支持換行.

##Partials

Partials由一個>開始，如{{> box}}.

Partials 僅在運行時(同編譯時相反)被渲染，因此（模板）支持循環的Partials，但要避免支持死循環。

Partials 能夠繼承調用上下文calling context，在 ERB 中，你可能有以下代碼：

<%= partial :next_more, :start => start, :size => size %>

Mustache 僅須要以下:

{{> next_more}}

爲何？由於next_more.mustache文件將會從調用上下文中繼承size 和 start 方法

經過這種方式，你能夠將partials看做includes，或者模板的擴展，儘管這可能不必定是正確。

例如, 以下的模板和partial：

base.mustache:

<h2>Names</h2>
{{#names}}
  {{> user}}
{{/names}}

user.mustache:

<strong>{{name}}</strong>

能夠被看出一個文件，擴展的模板：

<h2>Names</h2>
{{#names}}
  <strong>{{name}}</strong>
{{/names}}

設置分隔符

設置分隔符采用 = 開始，能夠將原始的{{ 和 }}修改成自定義的字符

考慮以下的人造示例:

* {{default_tags}}
{{=<% %>=}}
* <% erb_style_tags %>
<%={{ }}=%>
* {{ default_tags_again }}

Here we have a list with three items. 下面咱們分別解釋三個例子： 第一個使用了默認的分隔標記，第二個經過設置分隔符使用erb style ，第三個經過設置分隔符聲明又繼續使用默認的分隔符標記

According to ctemplates, this "is useful for languages like TeX, where {{ may occur in the text and are awkward to use for markup."

自定義分隔符不能包含空格或者等號。

版權 Mustache is Copyright (C) 2009 Chris Wanstrath

Original CTemplate by Google