Handlebars学习（8）- API参考

Handlebars为应用和helpers提供一系列的APIs和有效的方法。

 

8.1 基础

1. Handlebars.compile(template, options)

编译一个模板以使其可以马上运行。

  var template = Handlebars.compile('{{foo}}');
  template({});

支持一系列会改变模板运行的可选参数：

（1）data：设置为false将会使@data无法追踪；

（2）compat：设置为true enable recursive field lookup.

（3）knownHelpers：在模板运行过程中存在包含helpers列表的hash。传递这个参数会允许编译器优化很多cases。内置helpers会被自动的包含在列表中，另外，如果省略，会被设置为false。

（4）knownHelpersOnly：设置为true时，允许基于已知helpers列表更深层次的优化；

（5）trackIds：设置为true时，包含的id名会被用于解析helpers的参数。

（6）noEscape：Set to true to not HTML escape any content.

 

2. Handlebars.precompile(template, options)

预编译一个模板，使得该模板在发送到客户端时不需要编译就可以直接运行。

  var templateSpec = Handlebars.precompile('{{foo}}');

支持和Handlebars.compile方法完全一样的可选参数。

 

3. Handlebars.template(templateSpec)

创建一个可以被Handlebars.precompile预编译的模板

  var template = Handlebars.precompile(templateSpec);
  template({});

 

4. Handlebars.registerPartial(name, partial)

通过环境中的任意模板实现注册部分。

  Handlebars.registerPartial('foo', partial);

同样支持一次注册多个部分：

  Handlebars.registerPartial({
    foo: partial,
    bar: partial
  });

假如加载整个库，而局部模板可能是需要按需编译的字符串。假如仅仅加载运行时间，局部模板就必须是一个预编译模板，这个预编译模板已经采用Handlebars.template方法正确设置。

 

5. Handlebars.unregisterPartial(name)

注销一个先前注册的局部模板。

  Handlebars.unregisterPartial('foo');

 

6. Handlebars.registerHelper(name, helper)

通过环境中的任意模板注册helpers。

  Handlebars.registerHelper('foo', function() {
  });

同样支持一次注册多个helpers：

  Handlebars.registerHelper({
    foo: function() {
    },
    bar: function() {
    }
  });

 

7. Handlebars.unregisterHelper(name)

注销一个之前注册的helper：

  Handlebars.unregisterHelper('foo');

 

8. Handlebars.SafeString(string)

当模板输出时阻止字符串被转义。

  new Handlebars.SafeString('<div>HTML Content!</div>')

构建时会被标记为安全字符串，任何外部的内容都应该使用Handlebars.escapeExpression方法正确的转义以避免潜在的安全问题。

 

9. Handlebars.escapeExpression(string)

转移至传递字符串的HTML，使其可以安全的作为HTML内容中的文本输出。

  Handlebars.Utils.escapeExpression(string)

使用等价的实体值替换&, <, >, ", ', `为字符串值，SafeString则可以幸免。

除了三重大括号"{{{}}}"包装的表达式，所以表达式的输出都通过这种方法。另外，当通过一个SafeString实例阻止可能的代码注入返回HTML代码时，helpers应该使用这种方法。

这个方法有个别名是：Handlebars.Utils.escapeExpression

 

10. Handlebars.createFrame(data)

被块helpers用于创建一个子data对象。

  if (options.data) {
    var data = Handlebars.createFrame(options.data);
    data.foo = 'bar';
    options.data = data;
  }

当为了分离它们而这样做以及避免损伤任何父元素数据状态时，修改数据状态的helpers应该创建一个新的框架。通常，每一个helper执行时，只需要创建一个框架，例如，each迭代器仅仅创立一个框架，这个框架会被所有的子处理重用。

 

11. Handlebars.create()

创建一个独立的Handlebars环境。

  var OtherHandlebars = Handlebars.create();

每一个环境尤其自己的helpers和局部模板。这是唯一需要确切的helpers或局部模板的使用环境。大多数的使用环境可以直接使用根Handlebars环境。

为特定环境创建的模板属于其环境。也就是说，需要在多重环境中运行的模板需要被使用Handlebars.template为每一个环境重编译或者重建。应用到局部模板的也是一样。

 

12. Handlebars.log(level, message)

被log helper使用的记录器。

需要的时候可以被改写。

 

8.2 Utilities

通过定义Handlebars.Utils对象，Handlebars提供一系列的功能方法。

1. Handlebars.Utils.isEmpty(value)

判断传递的值是否为空。

  Handlebars.Utils.isEmpty(value)

它被if和with helpers用于控制执行流程，下面的任何一种情况将被识为空：

（1）长度为0的数组；

（2）除0以外的falsy value

Handlebars.Utils.isEmpty()可以匹配Mustache behavior。

 

2. Handlebars.Utils.extend(obj, value)

使用value来扩展obj对象，与jQuery的$.extentd()类似。

  Handlebars.Utils.extend(foo, {bar: true})

将会在foo对象中设置值为true的新属性bar。

 

3. Handlebars.Utils.toString(obj)

通用的toString方法。

 

4. Handlebars.Utils.isArray(obj)

判断obj对象是否是个数组

 

5. Handlebars.Utils.isFunction(obj)

判断obj对象是否是个函数。

 

6. Handlebars.Utils.appendContextPath(contextPath, id)

使id继承contextPath的上下文路径。

  Handlebars.Utils.appendContextPath('foo.bar', 'baz')

将会返回foo.bar.baz.

 

8.3 @data变量

在handlebars和它的内置helpers中可以使用下面的@data变量。

1. @root

模板执行的初始上下文。

  {{#each array}}
    {{@root.foo}}
  {{/each}}

这个值在页面渲染的所有部分都是一致的，除非被显式的修改；这意味着：他可以被用在更深层次的参数里（引用它的父级template）。

 

2. @first

在each helper的第一次迭代中，这个值为true；非第一次迭代中，这个值为false。

  {{#each array}}
    {{#if @first}}
      First!
    {{/if}}
  {{/each}}

 

3. @index

在each helper中设置，从0开始的当前迭代次数。

  {{#each array}}
    {{@index}}
  {{/each}}

 

4. @key

在each helper中迭代对象时，该值表示当前迭代的键值（key值）。

  {{#each array}}
    {{@key}}
  {{/each}}

 

5. @last

在each helper的最后一次迭代中，这个值为true；非最后一次迭代中，这个值为false。

  {{#each array}}
    {{#if @last}}
      Last :(
    {{/if}}
  {{/each}}

 

6. @contextPath

在trackIds木块中设置，用于记录当前上下文的查询路径。

任何应用用户自定义上下文的用户自定义helpers都应该尽可能合适的设置这个值。假如新的上下文是已存在某个上下文的子元素，就可以使用Handlebars.Utils.appendContextPath helper去执行这个运算。

  if (options.data && options.ids) {
    var data = Handlebars.createFrame(options.data);
    data.contextPath = Handlebars.Utils.appendContextPath(data.contextPath, 'foo');
    options.data = data;
  }

 

7. @level

指定记录等级。

  template({}, {data: {level: Handlebars.logger.WARN}})

可以被设置为Handlebars.logger.DEBUG , Handlebars.logger.INFO , Handlebars.logger.WARN , 或Handlebars.logger.ERROR中的一个。

当设置了该值，在Handlebars.logger.level值与设置值相同，或者更冗长时，记录器才会输出。这个值的默认模式是仅仅记录error模式。