Writing Custom Helpers

编写自定义助手方法

Sometimes, you may use the same HTML in your application multiple times. In those cases, you can register a custom helper that can be invoked from any Handlebars template.

For example, imagine you are frequently wrapping certain values in a <span> tag with a custom class. You can register a helper from your JavaScript like this:

有时，你想在程序里多次使用同一段 HTML 代码。这种情况下，你就可以自定义一个任何 Handlebars 模板都能调用的助手方法。

比如，你频繁地用一个拥有 class（译注：这个class为css中的class，非JavaScript中的类） 的 <span>来包裹特定的值。你可以这样注册一个助手方法：

  1. Ember.Handlebars.helper('highlight', function(value, options) {
  2.   var escaped = Handlebars.Utils.escapeExpression(value);
  3.   return new Handlebars.SafeString('<span class="highlight">' + escaped + '</span>');
  4. });

If you return HTML from a helper, and you don’t want it to be escaped, make sure to return a new SafeString. Make sure you first escape any user data!

如果你想从助手方法返回 HTML，并且你不想转义，那你就要保证返回的结果是新的 SafeString。首先要确保已经转义了用户数据。

Anywhere in your Handlebars templates, you can now invoke this helper:

你可以从Handlebars模板的任何地方调用此助手方法：

  1. {{highlight name}}

and it will output the following:

输出如下：

  1. <span class="highlight">Peter</span>

If the name property on the current context changes, Ember.js will automatically execute the helper again and update the DOM with the new value.

如果当前上下文中的 name 属性发生变化， Ember.js会自动重新执行此助手方法，并用新的值去更新 DOM。

Dependencies

依赖

Imagine you want to render the full name of an App.Person. In this case, you will want to update the output if the person itself changes, or if the firstName or lastName properties change.

想象另一种情况，如果要渲染App.Person的全名，而希望在person本身变化或者其firstName和lastName属性值发生变化时，都能自动更新输出，那么，我们可以像下面这样做：

  1. Ember.Handlebars.helper('fullName', function(person) {
  2.   return person.get('firstName') + ' ' + person.get('lastName');
  3. }, 'firstName', 'lastName');

You would use the helper like this:

你可以这样用助手方法：

  1. {{fullName person}}

Now, whenever the context’s person changes, or when any of the dependent keys change, the output will automatically update.

现在，一旦上下文中的 person 变化了，或任何 依赖的键值 发生变化，输出都会自动更新。

Both the path passed to the fullName helper and its dependent keys may be full property paths (e.g. person.address.country).

传递给 fullName 助手方法的路径以及它的依赖键值都可以是完整的 属性路径 （如person.address.country）

Custom View Helpers

自定义视图助手

You may also find yourself rendering your view classes in multiple places using the {{view}} helper. In this case, you can save yourself some typing by registering a custom view helper.

有时需要经常在多个地方使用{{view}}来渲染视图类。其实在这样的情况下，可以通过注册一个自定义的视图助手来简化。

For example, let’s say you have a view called App.CalendarView. You can register a helper like this:

例如，假设有一个视图名为App.CalendarView，那么可以注册一个如下的助手：

  1. Ember.Handlebars.helper('calendar', App.CalendarView);

Using App.CalendarView in a template then becomes as simple as:

这样在模板中使用App.CalendarView就变成：

  1. {{calendar}}

Which is functionally equivalent to, and accepts all the same arguments as:

该助手提供了与视图助手相同的功能，并且可以接收相同的参数：

  1. {{view App.CalendarView}}