Ember.Handlebars Class packages/ember-handlebars-compiler/lib/main.js:44


Prepares the Handlebars templating library for use inside Ember's view system.

The Ember.Handlebars object is the standard Handlebars library, extended to use Ember's get() method instead of direct property access, which allows computed properties to be used inside templates.

To create an Ember.Handlebars template, call Ember.Handlebars.compile(). This will return a function that can be used by Ember.View for rendering.

Show:

bindClasses

(context, classBindings, view, bindAttrId) Array private

Helper that, given a space-separated string of property paths and a context, returns an array of class names. Calling this method also has the side effect of setting up observers at those property paths, such that if they change, the correct class name will be reapplied to the DOM element.

For example, if you pass the string "fooBar", it will first look up the "fooBar" value of the context. If that value is true, it will add the "foo-bar" class to the current element (i.e., the dasherized form of "fooBar"). If the value is a string, it will add that string as the class. Otherwise, it will not add any new class name.

Parameters:

context Ember.Object
The context from which to lookup properties
classBindings String
A string, space-separated, of class bindings to use
view View
The view in which observers should look for the element to update
bindAttrId Srting
Optional bindAttr id used to lookup elements

Returns:

Array
An array of class names to add

bootstrap

(ctx) private static

Find templates stored in the head tag as script tags and make them available to Ember.CoreView in the global Ember.TEMPLATES object. This will be run as as jQuery DOM-ready callback.

Script tags with text/x-handlebars will be compiled with Ember's Handlebars and are suitable for use as a view's template. Those with type text/x-raw-handlebars will be compiled with regular Handlebars and are suitable for use in views' computed properties.

Parameters:

ctx

compile

(string) Function static

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

Parameters:

string String
The template to compile

Returns:

Function

evaluateUnboundHelper

(fn, context, normalizedProperties, options) private

Renders the unbound form of an otherwise bound helper function.

Parameters:

fn Function
context Object
normalizedProperties Array
options String

get

(root, path, options)

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.

Parameters:

root Object
The object to look up the property on
path String
The path to be lookedup
options Object
The template's option hash

getEscaped

(root, path, options)
Defined in packages/ember-handlebars/lib/ext.js:221
Available since 1.4.0

This method uses Ember.Handlebars.get to lookup a value, then ensures that the value is escaped properly.

If unescaped is a truthy value then the escaping will not be performed.

Parameters:

root Object
The object to look up the property on
path String
The path to be lookedup
options Object
The template's option hash

helper

(name, function, dependentKeys)

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 'calendar'}}

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

Parameters:

name String
function Function|Ember.View
or view class constructor
dependentKeys String

makeBoundHelper

(function, dependentKeys)
Defined in packages/ember-handlebars/lib/ext.js:467
Available since 1.2.0

A helper function used by registerBoundHelper. Takes the provided Handlebars helper function fn and returns it in wrapped bound helper form.

The main use case for using this outside of registerBoundHelper is for registering helpers on the container:

1
2
3
4
5
var boundHelperFn = Ember.Handlebars.makeBoundHelper(function(word) {
  return word.toUpperCase();
});

container.register('helper:my-bound-helper', boundHelperFn);

In the above example, if the helper function hadn't been wrapped in makeBoundHelper, the registered helper would be unbound.

Parameters:

function Function
dependentKeys String

makeViewHelper

(ViewClass) private
Defined in packages/ember-handlebars-compiler/lib/main.js:126
Available since 1.2.0

Returns a helper function that renders the provided ViewClass.

Used internally by Ember.Handlebars.helper and other methods involving helper/component registration.

Parameters:

ViewClass Function
view class constructor

precompile

(value, asObject) static

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

Parameters:

value String|Object
The template to precompile or an Handlebars AST
asObject Boolean
optional parameter, defaulting to true, of whether or not the compiled template should be returned as an Object or a String

registerBoundHelper

(name, function, dependentKeys)

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 Ember.String.capitalize(value);
});

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 count=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 helper 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.

Parameters:

name String
function Function
dependentKeys String

template

(spec) private

Overrides Handlebars.template so that we can distinguish user-created, top-level templates from inner contexts.

Parameters:

spec String