Handlebars模板開發指南

基礎語法

Handlebars模板看起來和一般的HTML沒什麼兩樣，只不過是在HTML中嵌入了Handlebars的表達式。如下：

<div class="entry">
    <h1>{{title}}</h1>
    <div class="body">
          {{body}}
    </div>
</div>

一個Handlebars的表達式是被{{和}}包含起來的內容。瞭解更多Handlebars表達式。

你可以將模板的內容或數據放到一個<script>標籤裏，也可以直接寫在javascript裏：

<script id="entry-template" type="text/x-handlebars-template">
template content
</script>

當你寫了一個模板以後，使用Handlebars.compile方法將模板編譯爲函數，生成的執行函數接受context作爲參數，用來渲染模板。瞭解更多執行函數。

比如下面：

var source = "<p>Hello, my name is {{name}}. I am from {{hometown}}. I have " +
"{{kids.length}} kids:</p>" +
"<ul>{{#kids}}<li>{{name}} is {{age}}</li>{{/kids}}</ul>";
var template = Handlebars.compile(source);

var data = { "name": "Alan", "hometown": "Somewhere, TX",
"kids": [{"name": "Jimmy", "age": "12"}, {"name": "Sally", "age": "4"}]};
var result = template(data);

// 將被渲染爲:
// <p>Hello, my name is Alan. I am from Somewhere, TX. I have 2 kids:</p>
// <ul>
//   <li>Jimmy is 12</li>
//   <li>Sally is 4</li>
// </ul>

你還可以預編譯你的模板，它將會生成一個小一些的運行庫，這對移動設備上的web頁面非常重要。瞭解更多預編譯。

HTML轉義

爲安全起見，Handlebars表達式中的一些HTML字符將被轉義，如果你不想讓Handlebars轉義字符，使用三個花括號{{{：

//template:

<div class="entry">
    <h1>{{title}}</h1>
    <div class="body">
        {{{body}}}
    </div>
</div>

//context:

{
    title: "All about <p> Tags",
    body: "<p>This is a post about &lt;p&gt; tags</p>"
}

//results:

<div class="entry">
    <h1>All About &lt;p&gt; Tags</h1>
    <div class="body">
      <p>This is a post about &lt;p&gt; tags</p>
    </div>
</div>

Handlebars不會轉義Handlebars.SafeString，如果你想寫一個輸出自身HTML的helper，你可以使用這個方法，用來手動的輸出需要轉義的參數。

Handlebars.registerHelper('link', function(text, url) {
  text = Handlebars.Utils.escapeExpression(text);
  url  = Handlebars.Utils.escapeExpression(url);

  var result = '<a href="' + url + '">' + text + '</a>';

  return new Handlebars.SafeString(result);
});

塊級表達式

塊級表達式能讓你定義塊級helpers，它能調用模板的一部分，並且使用與當前不同的上下文。下面以一個輸出HTML列表的helper爲例：

{{#list people}}{{firstName}} {{lastName}}{{/list}}

定義如下的上下文：

{
  people: [
    {firstName: "Yehuda", lastName: "Katz"},
    {firstName: "Carl", lastName: "Lerche"},
    {firstName: "Alan", lastName: "Johnson"}
  ]
}

我們可以創建一個名爲list的helper來生成HTML列表，這個helper接受people和options參數，options包含fn屬性，可以調用上下文。

Handlebars.registerHelper('list', function(items, options) {
  var out = "<ul>";

  for(var i=0, l=items.length; i<l; i++) {
    out = out + "<li>" + options.fn(items[i]) + "</li>";
  }

  return out + "</ul>";
});

執行後，生成：

<ul>
  <li>Yehuda Katz</li>
  <li>Carl Lerche</li>
  <li>Alan Johnson</li>
</ul>

塊級helper包含更多的特性，如創建一個else部分（在內建的if helper裏有用到）。

當調用options.fn(context)時內部的內容已經被轉義，因此Handlebars不會轉義塊級helper的結果，否則會出現兩次轉義。瞭解更多塊級helper。

Handlebars路徑

和Mustache一樣，Handlebars支持簡單的路徑。

Handlebars還支持嵌套的路徑，可以在當前上下文中尋找嵌套的屬性。

<div class="entry">
  <h1>{{title}}</h1>
  <h2>By {{author.name}}</h2>

  <div class="body">
    {{body}}
  </div>
</div>

其對應的上下文如下：

var context = {
  title: "My First Blog Post!",
  author: {
    id: 47,
    name: "Yehuda Katz"
  },
  body: "My first post. Wheeeee!"
};

因此Handlebars模板能支持更多原始的JSON對象。

嵌套的handlebars路徑可以包含../字符段，可以將路徑定位到父級上下文中。

<h1>Comments</h1>

<div id="comments">
  {{#each comments}}
  <h2><a href="/posts/{{../permalink}}#{{id}}">{{title}}</a></h2>
  <div>{{body}}</div>
  {{/each}}
</div>

在這個例子中，post是comments的父級上下文，雖然a標籤處於comments的上下文裏，但permalink可以上溯到post上下文中。

更嚴密的講，../路徑指的是父級模板的作用域，而不是高一級的上下文，這是因爲塊級helper能調用任何上下文，所以“上一級”的概念在這裏並不適合。

模板註釋

在handlebars中使用{{! }}或者{{!-- --}}來包含註釋。

<div class="entry">
  {{! only output this author names if an author exists }}
  {{#if author}}
    <h1>{{firstName}} {{lastName}}</h1>
  {{/if}}
</div>

Helpers（輔助方法）

Helpers是Handlebars中最重要的概念，它能大大擴展Handlebars的使用範圍，Helper自定義函數的形式將所需要的功能註冊爲表達式，然後可以在Handlebars中使用。

Handlebars提供了Handlebars.registerHelper方法來自定義Helper，同時也提供了一些常用的內建Helper。

比如有如下模板：

<div class="post">
  <h1>By {{fullName author}}</h1>
  <div class="body">{{body}}</div>

  <h1>Comments</h1>

  {{#each comments}}
  <h2>By {{fullName author}}</h2>
  <div class="body">{{body}}</div>
  {{/each}}
</div>

其中上下文和helper如下：

var context = {
  author: {firstName: "Alan", lastName: "Johnson"},
  body: "I Love Handlebars",
  comments: [{
    author: {firstName: "Yehuda", lastName: "Katz"},
    body: "Me too!"
  }]
};

Handlebars.registerHelper('fullName', function(person) {
  return person.firstName + " " + person.lastName;
});

運行結果：

<div class="post">
  <h1>By Alan Johnson</h1>
  <div class="body">I Love Handlebars</div>

  <h1>Comments</h1>

  <h2>By Yehuda Katz</h2>
  <div class="body">Me Too!</div>
</div>

Helpers還可以接受塊級元素當前的上下文，就像函數中的this上下文一樣。

<ul>
  {{#each items}}
  <li>{{agree_button}}</li>
  {{/each}}
</ul>

上下文及helper如下：

var context = {
  items: [
    {name: "Handlebars", emotion: "love"},
    {name: "Mustache", emotion: "enjoy"},
    {name: "Ember", emotion: "want to learn"}
  ]
};

Handlebars.registerHelper('agree_button', function() {
  return new Handlebars.SafeString(
    "<button>I agree. I " + this.emotion + " " + this.name + "</button>"
  );
});

運行結果：

<ul>
  <li><button>I agree. I love Handlebars</button></li>
  <li><button>I agree. I enjoy Mustache</button></li>
  <li><button>I agree. I want to learn Ember</button></li>
</ul>

內建Helpers

Handlebars提供了一系列的內建Helper供直接調用。

with：切換上下文

each：循環輸出上下文中的內容，用this表達式指代單條內容，else表達式當上下文爲空時激活

if：條件表達式

unless：與if表達式功能相反

log：輸出log