Class Ember.Handlebars

compile (string) Function

Defined in packages/ember-handlebars-compiler/lib/main.js:243

string

String

The template to compile

returns

Function

The entry point for Ember Handlebars. This replaces the default Handlebars.compile and turns on template-local data and String parameters.

get (root, path, options)

Defined in packages/ember-handlebars/lib/ext.js:48

root

Object

The object to look up the property on

path

String

The path to be lookedup

options

Object

The template's option hash

Lookup both on root and on window. If the path starts with a keyword, the corresponding object will be looked up in the template's data hash and used to resolve the path.

helper (name, function, dependentKeys)

Defined in packages/ember-handlebars-compiler/lib/main.js:51

name

String

function

Function|Ember.View

or view class constructor

dependentKeys

String

Register a bound helper or custom view helper.

Simple bound helper example

1
2
3

Ember.Handlebars.helper('capitalize', function(value) {
  return value.toUpperCase();
});

The above bound helper can be used inside of templates as follows:

1

{{capitalize name}}

In this case, when the name property of the template's context changes, the rendered value of the helper will update to reflect this change.

For more examples of bound helpers, see documentation for Ember.Handlebars.registerBoundHelper.

Custom view helper example

Assuming a view subclass named App.CalendarView were defined, a helper for rendering instances of this view could be registered as follows:

1

Ember.Handlebars.helper('calendar', App.CalendarView):

The above bound helper can be used inside of templates as follows:

1

{{calendar}}

Which is functionally equivalent to:

1

{{view App.CalendarView}}

Options in the helper will be passed to the view in exactly the same manner as with the view helper.

precompile (string)

Defined in packages/ember-handlebars-compiler/lib/main.js:212

string

String

The template to precompile

Used for precompilation of Ember Handlebars templates. This will not be used during normal app execution.

registerBoundHelper (name, function, dependentKeys)

Defined in packages/ember-handlebars/lib/ext.js:141

name

String

function

Function

dependentKeys

String

Register a bound handlebars helper. Bound helpers behave similarly to regular handlebars helpers, with the added ability to re-render when the underlying data changes.

Simple example

1
2
3

Ember.Handlebars.registerBoundHelper('capitalize', function(value) {
  return value.toUpperCase();
});

The above bound helper can be used inside of templates as follows:

1

{{capitalize name}}

In this case, when the name property of the template's context changes, the rendered value of the helper will update to reflect this change.

Example with options

Like normal handlebars helpers, bound helpers have access to the options passed into the helper call.

1
2
3
4
5
6
7
8

Ember.Handlebars.registerBoundHelper('repeat', function(value, options) {
  var count = options.hash.count;
  var a = [];
  while(a.length < count) {
      a.push(value);
  }
  return a.join('');
});

This helper could be used in a template as follows:

1

{{repeat text count=3}}

Example with bound options

Bound hash options are also supported. Example:

1

{{repeat text countBinding="numRepeats"}}

In this example, count will be bound to the value of the numRepeats property on the context. If that property changes, the helper will be re-rendered.

Example with extra dependencies

The Ember.Handlebars.registerBoundHelper method takes a variable length third parameter which indicates extra dependencies on the passed in value. This allows the handlebars helper to update when these dependencies change.

1
2
3

Ember.Handlebars.registerBoundHelper('capitalizeName', function(value) {
  return value.get('name').toUpperCase();
}, 'name');

Example with multiple bound properties

Ember.Handlebars.registerBoundHelper supports binding to multiple properties, e.g.:

1
2
3
4

Ember.Handlebars.registerBoundHelper('concatenate', function() {
  var values = Array.prototype.slice.call(arguments, 0, -1);
  return values.join('||');
});

Which allows for template syntax such as {{concatenate prop1 prop2}} or {{concatenate prop1 prop2 prop3}}. If any of the properties change, the helpr will re-render. Note that dependency keys cannot be using in conjunction with multi-property helpers, since it is ambiguous which property the dependent keys would belong to.

Use with unbound helper

The {{unbound}} helper can be used with bound helper invocations to render them in their unbound form, e.g.

1

{{unbound capitalize name}}

In this example, if the name property changes, the helper will not re-render.

Use with blocks not supported

Bound helpers do not support use with Handlebars blocks or the addition of child views of any kind.