README

没有什么比完全没有逻辑更合乎逻辑的了吧？

mustache.js 是一个在 JavaScript 中实现的 mustache 模板系统的实现。

Mustache 是一种无逻辑的模板语法。它可以用于 HTML、配置文件、源代码——任何东西。它通过在模板中使用哈希或对象中提供的值来展开标签来工作。

我们称它为“无逻辑”，因为没有 if 语句、else 子句或 for 循环。相反，只有标签。一些标签被替换为值，一些没有任何东西，而另一些则是一系列值。

有关 mustache 的模板语法的语言无关概述，请参阅 mustache(5) 手册页。

在哪里使用 mustache.js？

您可以在可以使用 JavaScript 的任何地方使用 mustache.js 来渲染 mustache 模板。这包括网络浏览器、服务器端环境，如 node 和 CouchDB 视图。

mustache.js 同时支持 CommonJS 模块 API 和异步模块定义 API，或 AMD。

使用 Mustache 后，这将是你模板的样子

安装

您可以通过 npm 获取 Mustache。

$ npm install mustache --save

或者使用 bower 安装

$ bower install --save mustache

命令行工具

mustache.js 随附一个基于 node 的命令行工具。它可能已安装为计算机上的全局工具以渲染某种类型的 mustache 模板

$ npm install -g mustache

$ mustache dataView.json myTemplate.mustache > output.html

也支持 stdin。

$ cat dataView.json | mustache - myTemplate.mustache > output.html

或者作为 build 过程中的 package.json devDependency？

$ npm install mustache --save-dev

{
  "scripts": {
    "build": "mustache dataView.json myTemplate.mustache > public/output.html"
  }
}

$ npm run build

命令行工具基本上是 Mustache.render 的包装器，因此您可以得到所有功能。

如果您的模板使用部分，应使用 -p 标志传递部分的路径

$ mustache -p path/to/partial1.mustache -p path/to/partial2.mustache dataView.json myTemplate.mustache

谁使用 mustache.js？

在 Github wiki 上维护着一个 mustache.js 用户的更新列表这里。如果您使用 mustache.js，请添加自己或您的公司！

贡献

mustache.js 是一个成熟的项目，但它继续积极邀请维护者。您可以帮助一个在网络上被广泛使用的知名项目。有很多工作可以做。不需要大的承诺，如果您只审查一个 Pull Request，您就是维护者。而且是一个英雄。

您的第一次贡献

审查一个 Pull Request
修复一个 Issue
更新文档
制作一个网站
编写一个教程

用法

以下是一个快速示例，说明如何使用 mustache.js

var view = {
  title: "Joe",
  calc: function () {
    return 2 + 4;
  }
};

var output = Mustache.render("{{title}} spends {{calc}}", view);

在这个示例中，Mustache.render 函数接受两个参数：1）mustache 模板和2）一个包含渲染模板所需数据和代码的 view 对象。

API

以下是最常用函数的 rtype 签名。

Mustache.render(
  template  : String,
  view      : Object,
  partials? : Object,
) => String

Mustache.parse(
  template              : String,
  tags = ['{{', '}}']   : Tags,
) => String

interface Tags [String, String]

模板

mustache 模板是一个包含任意数量 mustache 标签的字符串。标签由围绕它们的双大括号表示。{{person}} 是一个标签，同样 {{#person}} 也是。在这两个例子中，我们将 person 称为标签的键。mustache.js 提供了多种类型的标签，下面将进行描述。

可以使用几种技术来加载模板并将其传递给 mustache.js，以下是两种。

包含模板

如果您需要为静态网站中的动态部分创建模板，可以考虑将其包含在静态 HTML 文件中，以避免单独加载模板。以下是一个使用 jQuery 的小例子。

<html>
<body onload="loadUser">
<div id="target">Loading...</div>
<script id="template" type="x-tmpl-mustache">
Hello {{ name }}!
</script>
</body>
</html>

function loadUser() {
  var template = $('#template').html();
  Mustache.parse(template);   // optional, speeds up future uses
  var rendered = Mustache.render(template, {name: "Luke"});
  $('#target').html(rendered);
}

加载外部模板

如果您的模板位于单个文件中，可以异步加载它们，并在它们到达时进行渲染。以下是一个使用 jQuery 的另一个示例。

function loadUser() {
  $.get('template.mst', function(template) {
    var rendered = Mustache.render(template, {name: "Luke"});
    $('#target').html(rendered);
  });
}

变量

最基本的标签类型是简单的变量。一个 {{name}} 标签渲染当前上下文中 name 键的值。如果不存在这样的键，则不进行渲染。

默认情况下，所有变量都会进行 HTML 转义。如果您想渲染未转义的 HTML，请使用三个大括号：{{{name}}}。您还可以使用 & 来取消转义变量。

如果您想 {{name}} 不被解释为 mustache 标签，而要在输出中精确显示为 {{name}}，您必须更改并恢复默认分隔符。有关自定义分隔符的更多信息，请参阅 "Set Delimiter" 部分。

视图

{
  "name": "Chris",
  "company": "<b>GitHub</b>"
}

模板

* {{name}}
* {{age}}
* {{company}}
* {{{company}}}
* {{&company}}
{{=<% %>=}}
* {{company}}
<%={{ }}=%>

输出

* Chris
*
* &lt;b&gt;GitHub&lt;/b&gt;
* <b>GitHub</b>
* <b>GitHub</b>
* {{company}}

可以使用 JavaScript 的点表示法来访问视图对象中对象的属性键。

视图

{
  "name": {
    "first": "Michael",
    "last": "Jackson"
  },
  "age": "RIP"
}

模板

* {{name.first}} {{name.last}}
* {{age}}

输出

* Michael Jackson
* RIP

部分

部分可以渲染文本块一次或多次，具体取决于当前上下文中键的值。

部分从井号开始，以斜杠结束。也就是说，{{#person}} 开始一个 person 部分，而 {{/person}} 结束它。两个标签之间的文本称为该部分的 "块"。

部分的行为由键的值决定。

假值或空列表

如果 person 键不存在，或者存在但其值为 null、undefined、false、0 或 NaN，或者是一个空字符串或空列表，则不会渲染块。

视图

{
  "person": false
}

模板

Shown.
{{#person}}
Never shown!
{{/person}}

输出

Shown.

非空列表

如果 person 键存在且不是 null、undefined 或 false，并且不是一个空列表，则块将渲染一次或多次。

当值是列表时，块将针对列表中的每个项目渲染一次。每次迭代都将设置块的上下文为列表中的当前项目。这样，我们可以遍历集合。

视图

{
  "stooges": [
    { "name": "Moe" },
    { "name": "Larry" },
    { "name": "Curly" }
  ]
}

模板

{{#stooges}}
<b>{{name}}</b>
{{/stooges}}

输出

<b>Moe</b>
<b>Larry</b>
<b>Curly</b>

当遍历字符串数组时，可以使用 . 来引用列表中的当前项。

视图

{
  "musketeers": ["Athos", "Aramis", "Porthos", "D'Artagnan"]
}

模板

{{#musketeers}}
* {{.}}
{{/musketeers}}

输出

* Athos
* Aramis
* Porthos
* D'Artagnan

如果部分变量的值是一个函数，则它将在每次迭代中调用，并在列表中的当前项的上下文中执行。

视图

{
  "beatles": [
    { "firstName": "John", "lastName": "Lennon" },
    { "firstName": "Paul", "lastName": "McCartney" },
    { "firstName": "George", "lastName": "Harrison" },
    { "firstName": "Ringo", "lastName": "Starr" }
  ],
  "name": function () {
    return this.firstName + " " + this.lastName;
  }
}

模板

{{#beatles}}
* {{name}}
{{/beatles}}

输出

* John Lennon
* Paul McCartney
* George Harrison
* Ringo Starr

函数

如果部分键的值是一个函数，则它将作为第一个参数使用部分的文本块（未渲染）调用。第二个参数是一个特殊的渲染函数，它使用当前视图作为其视图参数。它在当前视图对象的上下文中调用。

视图

{
  "name": "Tater",
  "bold": function () {
    return function (text, render) {
      return "<b>" + render(text) + "</b>";
    }
  }
}

模板

{{#bold}}Hi {{name}}.{{/bold}}

输出

<b>Hi Tater.</b>

反转部分

倒置部分以 {{^section}} 开头，而不是以 {{#section}} 开头。只有在该部分的标签值是 null、undefined、false、空值或空列表时，倒置部分才会渲染。

视图

{
  "repos": []
}

模板

{{#repos}}<b>{{name}}</b>{{/repos}}
{{^repos}}No repos :({{/repos}}

输出

No repos :(

注释

注释以感叹号开头并会被忽略。以下模板

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

将渲染如下

<h1>Today.</h1>

注释可以包含换行符。

局部模板

局部模板以大于号开头，例如 {{> box}}。

局部模板在运行时渲染（而不是编译时），因此可能存在递归的局部模板。只需避免无限循环。

它们也继承了调用上下文。在 ERB 中，您可能有这样的

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

Mustache 只需要这样

{{> next_more}}

为什么？因为 next_more.mustache 文件将从调用上下文中继承 size 和 start 变量。这样您可以将局部模板视为包含、导入、模板扩展、嵌套模板或子模板，尽管在这里这并不是字面上的情况。

例如，此模板和局部模板

base.mustache:
<h2>Names</h2>
{{#names}}
  {{> user}}
{{/names}}

user.mustache:
<strong>{{name}}</strong>

可以被视为一个单一的、展开的模板

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

在 mustache.js 中，可以传递一个对象作为 Mustache.render 的第三个参数，该对象包含局部模板。对象应按局部模板的名称键入，其值应为局部模板文本。

Mustache.render(template, view, {
  user: userTemplate
});

设置分隔符

设置分隔符标签以等号开头，并更改标签分隔符从 {{ 和 }} 到自定义字符串。

考虑以下虚构的示例

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

这里有三个项目的列表。第一个项目使用默认的标签样式，第二个项目使用由设置分隔符标签定义的 ERB 样式，第三个项目在另一个设置分隔符声明之后返回到默认样式。

根据 ctemplates，这对于像 TeX 这样的语言很有用，因为文本中可能存在双花括号，并且使用它们作为标记会很awkward。

自定义分隔符不能包含空格或等号。

预解析和模板缓存

默认情况下，当 mustache.js 首次解析模板时，它将完整的解析令牌树保存在缓存中。下次看到相同的模板时，它会跳过解析步骤并快速渲染模板。如果您愿意，可以使用 mustache.parse 提前这样做。

Mustache.parse(template);

// Then, sometime later.
Mustache.render(template, view);

JavaScript 库插件

mustache.js 可以专门为以下不同的客户端库构建

这些可以使用 Rake 和以下命令之一构建

$ rake jquery
$ rake mootools
$ rake dojo
$ rake yui3
$ rake qooxdoo

测试

为了运行测试，您需要安装 node。

您还需要在项目根目录中安装包含 Mustache 规范的子模块。

$ git submodule init
$ git submodule update

安装依赖项。

$ npm install

然后运行测试。

$ npm test

测试套件包括单元测试和集成测试。如果模板无法正确渲染，您可以按照以下步骤创建测试

在 test/_files 目录中创建一个名为 mytest.mustache 的模板文件。将 mytest 替换为您的测试名称。
在同一个目录中创建一个相应的视图文件，名为 mytest.js。此文件应包含一个括号内的 JavaScript 对象字面量。请参见其他视图文件中的示例。
在同一个目录中创建一个包含预期输出的文件，名为 mytest.txt。

然后，您可以使用以下命令运行测试

$ TEST=mytest npm run test-render

浏览器测试

浏览器测试不包括在npm test中，因为它们运行时间过长，尽管它们在合并到master时会自动在Travis上运行。在任何浏览器中本地运行浏览器测试

$ npm run test-browser-local

然后将浏览器指向https://:8080/__zuul

故障排除

npm安装失败

请确保已安装最新版本的npm。在开发此项目时需要支持^版本范围的npm。

$ npm install -g npm

感谢

如果没有这些优秀的灵魂，mustache.js就无法如此出色

Chris Wanstrath / defunkt
Alexander Lang / langalex
Sebastian Cohnen / tisba
J Chris Anderson / jchris
Tom Robinson / tlrobinson
Aaron Quint / quirkey
Douglas Crockford
Nikita Vasilyev / NV
Elise Wood / glytch
Damien Mathieu / dmathieu
Jakub Kuźma / qoobaa
Will Leinweber / will
dpree
Jason Smith / jhs
Aaron Gibralter / agibralter
Ross Boucher / boucher
Matt Sanford / mzsanford
Ben Cherry / bcherry
Michael Jackson / mjackson
Phillip Johnsen / phillipj
David da Silva Contín / dasilvacontin

ftlmars / mustache.js

维护者

详细信息