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


Show:

_triageMustache

(property, options) String private

'_triageMustache' is used internally select between a binding, helper, or component for the given context. Until this point, it would be hard to determine if the mustache is a property reference or a regular helper reference. This triage helper resolves that.

This would not be typically invoked by directly.

Parameters:

property String
Property/helperID to triage
options Object
hash of template/rendering options

Returns:

String
HTML string

bind

(property, fn) String private

bind can be used to display a value, then update that value if it changes. For example, if you wanted to print the title property of content:

1
{{bind "content.title"}}

This will return the title property as a string, then create a new observer at the specified path. If it changes, it will update the value in DOM. Note that if you need to support IE7 and IE8 you must modify the model objects properties using Ember.get() and Ember.set() for this to work as it relies on Ember's KVO system. For all other browsers this will be handled for you automatically.

Parameters:

property String
Property to bind
fn Function
Context to provide for rendering

Returns:

String
HTML string

bind-attr

(options) String

bind-attr allows you to create a binding between DOM element attributes and Ember objects. For example:

1
<img {{bind-attr src="imageUrl" alt="imageTitle"}}>

The above handlebars template will fill the <img>'s src attribute with the value of the property referenced with "imageUrl" and its alt attribute with the value of the property referenced with "imageTitle".

If the rendering context of this template is the following object:

1
2
3
4
{
  imageUrl: 'http://lolcats.info/haz-a-funny',
  imageTitle: 'A humorous image of a cat'
}

The resulting HTML output will be:

1
<img src="http://lolcats.info/haz-a-funny" alt="A humorous image of a cat">

bind-attr cannot redeclare existing DOM element attributes. The use of src in the following bind-attr example will be ignored and the hard coded value of src="/failwhale.gif" will take precedence:

1
<img src="/failwhale.gif" {{bind-attr src="imageUrl" alt="imageTitle"}}>

bind-attr and the class attribute

bind-attr supports a special syntax for handling a number of cases unique to the class DOM element attribute. The class attribute combines multiple discrete values into a single attribute as a space-delimited list of strings. Each string can be:

  • a string return value of an object's property.
  • a boolean return value of an object's property
  • a hard-coded value

A string return value works identically to other uses of bind-attr. The return value of the property will become the value of the attribute. For example, the following view and template:

1
2
3
4
5
  AView = View.extend({
    someProperty: function() {
      return "aValue";
    }.property()
  })
1
<img {{bind-attr class="view.someProperty}}>

Result in the following rendered output:

1
<img class="aValue">

A boolean return value will insert a specified class name if the property returns true and remove the class name if the property returns false.

A class name is provided via the syntax somePropertyName:class-name-if-true.

1
2
3
AView = View.extend({
  someBool: true
})
1
<img {{bind-attr class="view.someBool:class-name-if-true"}}>

Result in the following rendered output:

1
<img class="class-name-if-true">

An additional section of the binding can be provided if you want to replace the existing class instead of removing it when the boolean value changes:

1
<img {{bind-attr class="view.someBool:class-name-if-true:class-name-if-false"}}>

A hard-coded value can be used by prepending : to the desired class name: :class-name-to-always-apply.

1
<img {{bind-attr class=":class-name-to-always-apply"}}>

Results in the following rendered output:

1
<img class="class-name-to-always-apply">

All three strategies - string return value, boolean return value, and hard-coded value – can be combined in a single declaration:

1
<img {{bind-attr class=":class-name-to-always-apply view.someBool:class-name-if-true view.someProperty"}}>

Parameters:

options Hash

Returns:

String
HTML string

bindAttr

(context, options) String deprecated

See bind-attr

Parameters:

context Function
options Hash

Returns:

String
HTML string

boundIf

(property, fn) String private

Use the boundIf helper to create a conditional that re-evaluates whenever the truthiness of the bound value changes.

1
2
3
{{#boundIf "content.shouldDisplayTitle"}}
  {{content.title}}
{{/boundIf}}

Parameters:

property String
Property to bind
fn Function
Context to provide for rendering

Returns:

String
HTML string

collection

(path, options) String deprecated

Use {{each}} helper instead.

{{collection}} is a Ember.Handlebars helper for adding instances of Ember.CollectionView to a template. See Ember.CollectionView for additional information on how a CollectionView functions.

{{collection}}'s primary use is as a block helper with a contentBinding option pointing towards an Ember.Array-compatible object. An Ember.View instance will be created for each item in its content property. Each view will have its own content property set to the appropriate item in the collection.

The provided block will be applied as the template for each item's view.

Given an empty <body> the following template:

1
2
3
{{#collection contentBinding="App.items"}}
  Hi {{view.content.name}}
{{/collection}}

And the following application code

1
2
3
4
5
6
App = Ember.Application.create()
App.items = [
  Ember.Object.create({name: 'Dave'}),
  Ember.Object.create({name: 'Mary'}),
  Ember.Object.create({name: 'Sara'})
]

Will result in the HTML structure below

1
2
3
4
5
<div class="ember-view">
  <div class="ember-view">Hi Dave</div>
  <div class="ember-view">Hi Mary</div>
  <div class="ember-view">Hi Sara</div>
</div>

Blockless use in a collection

If you provide an itemViewClass option that has its own template you can omit the block.

The following template:

1
{{collection contentBinding="App.items" itemViewClass="App.AnItemView"}}

And application code

1
2
3
4
5
6
7
8
9
10
App = Ember.Application.create();
App.items = [
  Ember.Object.create({name: 'Dave'}),
  Ember.Object.create({name: 'Mary'}),
  Ember.Object.create({name: 'Sara'})
];

App.AnItemView = Ember.View.extend({
  template: Ember.Handlebars.compile("Greetings {{view.content.name}}")
});

Will result in the HTML structure below

1
2
3
4
5
<div class="ember-view">
  <div class="ember-view">Greetings Dave</div>
  <div class="ember-view">Greetings Mary</div>
  <div class="ember-view">Greetings Sara</div>
</div>

Specifying a CollectionView subclass

By default the {{collection}} helper will create an instance of Ember.CollectionView. You can supply a Ember.CollectionView subclass to the helper by passing it as the first argument:

1
2
3
{{#collection App.MyCustomCollectionClass contentBinding="App.items"}}
  Hi {{view.content.name}}
{{/collection}}

Forwarded item.*-named Options

As with the {{view}}, helper options passed to the {{collection}} will be set on the resulting Ember.CollectionView as properties. Additionally, options prefixed with item will be applied to the views rendered for each item (note the camelcasing):

1
2
3
4
5
{{#collection contentBinding="App.items"
              itemTagName="p"
              itemClassNames="greeting"}}
  Howdy {{view.content.name}}
{{/collection}}

Will result in the following HTML structure:

1
2
3
4
5
<div class="ember-view">
  <p class="ember-view greeting">Howdy Dave</p>
  <p class="ember-view greeting">Howdy Mary</p>
  <p class="ember-view greeting">Howdy Sara</p>
</div>

Parameters:

path String
options Hash

Returns:

String
HTML string

debugger

(property)

Execute the debugger statement in the current context.

1
{{debugger}}

Before invoking the debugger statement, there are a few helpful variables defined in the body of this helper that you can inspect while debugging that describe how and where this helper was invoked:

  • templateContext: this is most likely a controller from which this template looks up / displays properties
  • typeOfTemplateContext: a string description of what the templateContext is

For example, if you're wondering why a value {{foo}} isn't rendering as expected within a template, you could place a {{debugger}} statement, and when the debugger; breakpoint is hit, you can inspect templateContext, determine if it's the object you expect, and/or evaluate expressions in the console to perform property lookups on the templateContext:

1
  > templateContext.get('foo') // -> "<value of {{foo}}>"

Parameters:

property String

each

(name, path, options)

The {{#each}} helper loops over elements in a collection, rendering its block once for each item. It is an extension of the base Handlebars {{#each}} helper:

1
Developers = [{name: 'Yehuda'},{name: 'Tom'}, {name: 'Paul'}];
1
2
3
{{#each Developers}}
  {{name}}
{{/each}}

{{each}} supports an alternative syntax with element naming:

1
2
3
{{#each person in Developers}}
  {{person.name}}
{{/each}}

When looping over objects that do not have properties, {{this}} can be used to render the object:

1
DeveloperNames = ['Yehuda', 'Tom', 'Paul']
1
2
3
{{#each DeveloperNames}}
  {{this}}
{{/each}}

{{else}} condition

{{#each}} can have a matching {{else}}. The contents of this block will render if the collection is empty.

1
2
3
4
5
{{#each person in Developers}}
  {{person.name}}
{{else}}
  <p>Sorry, nobody is available for this task.</p>
{{/each}}

Specifying a View class for items

If you provide an itemViewClass option that references a view class with its own template you can omit the block.

The following template:

1
2
3
{{#view App.MyView }}
  {{each view.items itemViewClass="App.AnItemView"}}
{{/view}}

And application code

1
2
3
4
5
6
7
8
9
10
11
12
13
App = Ember.Application.create({
  MyView: Ember.View.extend({
    items: [
      Ember.Object.create({name: 'Dave'}),
      Ember.Object.create({name: 'Mary'}),
      Ember.Object.create({name: 'Sara'})
    ]
  })
});

App.AnItemView = Ember.View.extend({
  template: Ember.Handlebars.compile("Greetings {{name}}")
});

Will result in the HTML structure below

1
2
3
4
5
<div class="ember-view">
  <div class="ember-view">Greetings Dave</div>
  <div class="ember-view">Greetings Mary</div>
  <div class="ember-view">Greetings Sara</div>
</div>

If an itemViewClass is defined on the helper, and therefore the helper is not being used as a block, an emptyViewClass can also be provided optionally. The emptyViewClass will match the behavior of the {{else}} condition described above. That is, the emptyViewClass will render if the collection is empty.

Representing each item with a Controller.

By default the controller lookup within an {{#each}} block will be the controller of the template where the {{#each}} was used. If each item needs to be presented by a custom controller you can provide a itemController option which references a controller by lookup name. Each item in the loop will be wrapped in an instance of this controller and the item itself will be set to the model property of that controller.

This is useful in cases where properties of model objects need transformation or synthesis for display:

1
2
3
4
5
App.DeveloperController = Ember.ObjectController.extend({
  isAvailableForHire: function() {
    return !this.get('model.isEmployed') && this.get('model.isSeekingWork');
  }.property('isEmployed', 'isSeekingWork')
})
1
2
3
{{#each person in developers itemController="developer"}}
  {{person.name}} {{#if person.isAvailableForHire}}Hire me!{{/if}}
{{/each}}

Each itemController will receive a reference to the current controller as a parentController property.

(Experimental) Grouped Each

When used in conjunction with the experimental group helper, you can inform Handlebars to re-render an entire group of items instead of re-rendering them one at a time (in the event that they are changed en masse or an item is added/removed).

1
2
3
4
5
{{#group}}
  {{#each people}}
    {{firstName}} {{lastName}}
  {{/each}}
{{/group}}

This can be faster than the normal way that Handlebars re-renders items in some cases.

If for some reason you have a group with more than one #each, you can make one of the collections be updated in normal (non-grouped) fashion by setting the option groupedRows=true (counter-intuitive, I know).

For example,

1
2
3
4
5
6
7
8
9
10
11
{{dealershipName}}

{{#group}}
  {{#each dealers}}
    {{firstName}} {{lastName}}
  {{/each}}

  {{#each car in cars groupedRows=true}}
    {{car.make}} {{car.model}} {{car.color}}
  {{/each}}
{{/group}}

Any change to dealershipName or the dealers collection will cause the entire group to be re-rendered. However, changes to the cars collection will be re-rendered individually (as normal).

Note that group behavior is also disabled by specifying an itemViewClass.

Parameters:

name [String]
name for item (used with `in`)
path [String]
path
options [Object]
Handlebars key/value pairs of options
itemViewClass [String]
a path to a view class used for each item
itemController [String]
name of a controller to be created for each item
groupedRows [Boolean]
enable normal item-by-item rendering when inside a `#group` helper

helperMissing

(path, options) private

Registers a helper in Handlebars that will be called if no property with the given name can be found on the current context object, and no helper with that name is registered.

This throws an exception with a more helpful error message so the user can track down where the problem is happening.

Parameters:

path String
options Hash

if

(context, options) String

See boundIf and unboundIf

Parameters:

context Function
options Hash

Returns:

String
HTML string

input

(options)

The {{input}} helper inserts an HTML <input> tag into the template, with a type value of either text or checkbox. If no type is provided, text will be the default value applied. The attributes of {{input}} match those of the native HTML tag as closely as possible for these two types.

Use as text field

An {{input}} with no type or a type of text will render an HTML text input. The following HTML attributes can be set via the helper:

readonlyrequiredautofocus
valueplaceholderdisabled
sizetabindexmaxlength
nameminmax
patternacceptautocomplete
autosaveformactionformenctype
formmethodformnovalidateformtarget
heightinputmodemultiple
stepwidthform
selectionDirectionspellcheck 

When set to a quoted string, these values will be directly applied to the HTML element. When left unquoted, these values will be bound to a property on the template's current rendering context (most typically a controller instance).

Unbound:

1
  {{input value="http://www.facebook.com"}}
1
  <input type="text" value="http://www.facebook.com"/>

Bound:

1
2
3
4
  App.ApplicationController = Ember.Controller.extend({
    firstName: "Stanley",
    entryNotAllowed: true
  });
1
  {{input type="text" value=firstName disabled=entryNotAllowed size="50"}}
1
  <input type="text" value="Stanley" disabled="disabled" size="50"/>

Actions

The helper can send multiple actions based on user events. The action property defines the action which is send when the user presses the return key. handlebars {{input action="submit"}} The helper allows some user events to send actions.

  • enter
  • insert-newline
  • escape-press
  • focus-in
  • focus-out
  • key-press For example, if you desire an action to be sent when the input is blurred, you only need to setup the action name to the event name property. handlebars {{input focus-in="alertMessage"}} See more about Text Support Actions ## Extension Internally, {{input type="text"}} creates an instance of Ember.TextField, passing arguments from the helper to Ember.TextField's create method. You can extend the capabilities of text inputs in your applications by reopening this class. For example, if you are building a Bootstrap project where data-* attributes are used, you can add one to the TextField's attributeBindings property:
1
2
3
  Ember.TextField.reopen({
    attributeBindings: ['data-error']
  });

Keep in mind when writing Ember.TextField subclasses that Ember.TextField itself extends Ember.Component, meaning that it does NOT inherit the controller of the parent view. See more about Ember components

Use as checkbox

An {{input}} with a type of checkbox will render an HTML checkbox input. The following HTML attributes can be set via the helper:

  • checked
  • disabled
  • tabindex
  • indeterminate
  • name
  • autofocus
  • form

When set to a quoted string, these values will be directly applied to the HTML element. When left unquoted, these values will be bound to a property on the template's current rendering context (most typically a controller instance).

Unbound:

1
  {{input type="checkbox" name="isAdmin"}}
1
  <input type="checkbox" name="isAdmin" />

Bound:

1
2
3
  App.ApplicationController = Ember.Controller.extend({
    isAdmin: true
  });
1
  {{input type="checkbox" checked=isAdmin }}
1
  <input type="checkbox" checked="checked" />

Extension

Internally, {{input type="checkbox"}} creates an instance of Ember.Checkbox, passing arguments from the helper to Ember.Checkbox's create method. You can extend the capablilties of checkbox inputs in your applications by reopening this class. For example, if you wanted to add a css class to all checkboxes in your application:

1
2
3
  Ember.Checkbox.reopen({
    classNames: ['my-app-checkbox']
  });

Parameters:

options Hash

loc

(str)

Calls Ember.String.loc with the provided string.

This is a convenient way to localize text. For example:

1
2
3
<script type="text/x-handlebars" data-template-name="home">
  {{loc "welcome"}}
</script>

Take note that "welcome" is a string and not an object reference.

See Ember.String.loc for how to set up localized string references.

Parameters:

str String
The string to format

log

(property)

log allows you to output the value of variables in the current rendering context. log also accepts primitive types such as strings or numbers.

1
{{log "myVariable:" myVariable }}

Parameters:

property String

partial

(partialName)

The partial helper renders another template without changing the template context:

1
2
{{foo}}
{{partial "nav"}}

The above example template will render a template named "nav", which has the same context as the parent template it's rendered into, so if the "nav" template also referenced {{foo}}, it would print the same thing as the {{foo}} in the above example.

If a "_nav" template isn't found, the partial helper will fall back to a template named "nav".

Bound template names

The parameter supplied to partial can also be a path to a property containing a template name, e.g.:

1
{{partial someTemplateName}}

The above example will look up the value of someTemplateName on the template context (e.g. a controller) and use that value as the name of the template to render. If the resolved value is falsy, nothing will be rendered. If someTemplateName changes, the partial will be re-rendered using the new template name.

Setting the partial's context with with

The partial helper can be used in conjunction with the with helper to set a context that will be used by the partial:

1
2
3
{{#with currentUser}}
  {{partial "user_info"}}
{{/with}}

Parameters:

partialName String
the name of the template to render minus the leading underscore

resolveHelper

(container, name) Handlebars Helper private

Used to lookup/resolve handlebars helpers. The lookup order is:

  • Look for a registered helper
  • If a dash exists in the name:
    • Look for a helper registed in the container
    • Use Ember.ComponentLookup to find an Ember.Component that resolves to the given name

Parameters:

container Container
name String
the name of the helper to lookup

Returns:

Handlebars Helper

template

(templateName) deprecated

template allows you to render a template from inside another template. This allows you to re-use the same template in multiple places. For example:

1
2
3
4
5
6
<script type="text/x-handlebars" data-template-name="logged_in_user">
  {{#with loggedInUser}}
    Last Login: {{lastLogin}}
    User Info: {{template "user_info"}}
  {{/with}}
</script>
1
2
3
4
<script type="text/x-handlebars" data-template-name="user_info">
  Name: <em>{{name}}</em>
  Karma: <em>{{karma}}</em>
</script>
1
2
3
4
5
{{#if isUser}}
  {{template "user_info"}}
{{else}}
  {{template "unlogged_user_info"}}
{{/if}}

This helper looks for templates in the global Ember.TEMPLATES hash. If you add <script> tags to your page with the data-template-name attribute set, they will be compiled and placed in this hash automatically.

You can also manually register templates by adding them to the hash:

1
Ember.TEMPLATES["my_cool_template"] = Ember.Handlebars.compile('<b>{{user}}</b>');

Parameters:

templateName String
the template to render

textarea

(options)

{{textarea}} inserts a new instance of <textarea> tag into the template. The attributes of {{textarea}} match those of the native HTML tags as closely as possible.

The following HTML attributes can be set:

  • value
  • name
  • rows
  • cols
  • placeholder
  • disabled
  • maxlength
  • tabindex
  • selectionEnd
  • selectionStart
  • selectionDirection
  • wrap
  • readonly
  • autofocus
  • form
  • spellcheck
  • required

When set to a quoted string, these value will be directly applied to the HTML element. When left unquoted, these values will be bound to a property on the template's current rendering context (most typically a controller instance).

Unbound:

1
{{textarea value="Lots of static text that ISN'T bound"}}

Would result in the following HTML:

1
2
3
<textarea class="ember-text-area">
  Lots of static text that ISN'T bound
</textarea>

Bound:

In the following example, the writtenWords property on App.ApplicationController will be updated live as the user types 'Lots of text that IS bound' into the text area of their browser's window.

1
2
3
App.ApplicationController = Ember.Controller.extend({
  writtenWords: "Lots of text that IS bound"
});
1
{{textarea value=writtenWords}}

Would result in the following HTML:

1
2
3
<textarea class="ember-text-area">
  Lots of text that IS bound
</textarea>

If you wanted a one way binding between the text area and a div tag somewhere else on your screen, you could use Ember.computed.oneWay:

1
2
3
4
App.ApplicationController = Ember.Controller.extend({
  writtenWords: "Lots of text that IS bound",
  outputWrittenWords: Ember.computed.oneWay("writtenWords")
});
1
2
3
4
5
{{textarea value=writtenWords}}

<div>
  {{outputWrittenWords}}
</div>

Would result in the following HTML:

1
2
3
4
5
6
7
8
9
<textarea class="ember-text-area">
  Lots of text that IS bound
</textarea>

<-- the following div will be updated in real time as you type -->

<div>
  Lots of text that IS bound
</div>

Finally, this example really shows the power and ease of Ember when two properties are bound to eachother via Ember.computed.alias. Type into either text area box and they'll both stay in sync. Note that Ember.computed.alias costs more in terms of performance, so only use it when your really binding in both directions:

1
2
3
4
App.ApplicationController = Ember.Controller.extend({
  writtenWords: "Lots of text that IS bound",
  twoWayWrittenWords: Ember.computed.alias("writtenWords")
});
1
2
{{textarea value=writtenWords}}
{{textarea value=twoWayWrittenWords}}
1
2
3
4
5
6
7
8
9
<textarea id="ember1" class="ember-text-area">
  Lots of text that IS bound
</textarea>

<-- both updated in real time -->

<textarea id="ember2" class="ember-text-area">
  Lots of text that IS bound
</textarea>

Actions

The helper can send multiple actions based on user events.

The action property defines the action which is send when the user presses the return key.

1
{{input action="submit"}}

The helper allows some user events to send actions.

  • enter
  • insert-newline
  • escape-press
  • focus-in
  • focus-out
  • key-press

For example, if you desire an action to be sent when the input is blurred, you only need to setup the action name to the event name property.

1
{{textarea focus-in="alertMessage"}}

See more about Text Support Actions

Extension

Internally, {{textarea}} creates an instance of Ember.TextArea, passing arguments from the helper to Ember.TextArea's create method. You can extend the capabilities of text areas in your application by reopening this class. For example, if you are building a Bootstrap project where data-* attributes are used, you can globally add support for a data-* attribute on all {{textarea}}s' in your app by reopening Ember.TextArea or Ember.TextSupport and adding it to the attributeBindings concatenated property:

1
2
3
Ember.TextArea.reopen({
  attributeBindings: ['data-error']
});

Keep in mind when writing Ember.TextArea subclasses that Ember.TextArea itself extends Ember.Component, meaning that it does NOT inherit the controller of the parent view.

See more about Ember components

Parameters:

options Hash

unbound

(property) String

unbound allows you to output a property without binding. Important: The output will not be updated if the property changes. Use with caution.

1
<div>{{unbound somePropertyThatDoesntChange}}</div>

unbound can also be used in conjunction with a bound helper to render it in its unbound form:

1
<div>{{unbound helperName somePropertyThatDoesntChange}}</div>

Parameters:

property String

Returns:

String
HTML string

unboundIf

(property, fn) String private
Defined in packages/ember-handlebars/lib/helpers/binding.js:379
Available since 1.4.0

Parameters:

property String
Property to bind
fn Function
Context to provide for rendering

Returns:

String
HTML string

unless

(context, options) String

Parameters:

context Function
options Hash

Returns:

String
HTML string

view

(path, options) String

{{view}} inserts a new instance of an Ember.View into a template passing its options to the Ember.View's create method and using the supplied block as the view's own template.

An empty <body> and the following template:

1
2
3
4
A span:
{{#view tagName="span"}}
  hello.
{{/view}}

Will result in HTML structure:

1
2
3
4
5
6
7
8
9
10
11
12
<body>
  <!-- Note: the handlebars template script
       also results in a rendered Ember.View
       which is the outer <div> here -->

  <div class="ember-view">
    A span:
    <span id="ember1" class="ember-view">
      Hello.
    </span>
  </div>
</body>

parentView setting

The parentView property of the new Ember.View instance created through {{view}} will be set to the Ember.View instance of the template where {{view}} was called.

1
2
3
4
5
aView = Ember.View.create({
  template: Ember.Handlebars.compile("{{#view}} my parent: {{parentView.elementId}} {{/view}}")
});

aView.appendTo('body');

Will result in HTML structure:

1
2
3
4
5
<div id="ember1" class="ember-view">
  <div id="ember2" class="ember-view">
    my parent: ember1
  </div>
</div>

Setting CSS id and class attributes

The HTML id attribute can be set on the {{view}}'s resulting element with the id option. This option will not be passed to Ember.View.create.

1
2
3
{{#view tagName="span" id="a-custom-id"}}
  hello.
{{/view}}

Results in the following HTML structure:

1
2
3
4
5
<div class="ember-view">
  <span id="a-custom-id" class="ember-view">
    hello.
  </span>
</div>

The HTML class attribute can be set on the {{view}}'s resulting element with the class or classNameBindings options. The class option will directly set the CSS class attribute and will not be passed to Ember.View.create. classNameBindings will be passed to create and use Ember.View's class name binding functionality:

1
2
3
{{#view tagName="span" class="a-custom-class"}}
  hello.
{{/view}}

Results in the following HTML structure:

1
2
3
4
5
<div class="ember-view">
  <span id="ember2" class="ember-view a-custom-class">
    hello.
  </span>
</div>

Supplying a different view class

{{view}} can take an optional first argument before its supplied options to specify a path to a custom view class.

1
2
3
{{#view "MyApp.CustomView"}}
  hello.
{{/view}}

The first argument can also be a relative path accessible from the current context.

1
2
3
4
5
6
7
8
9
MyApp = Ember.Application.create({});
MyApp.OuterView = Ember.View.extend({
  innerViewClass: Ember.View.extend({
    classNames: ['a-custom-view-class-as-property']
  }),
  template: Ember.Handlebars.compile('{{#view "view.innerViewClass"}} hi {{/view}}')
});

MyApp.OuterView.create().appendTo('body');

Will result in the following HTML:

1
2
3
4
5
<div id="ember1" class="ember-view">
  <div id="ember2" class="ember-view a-custom-view-class-as-property">
    hi
  </div>
</div>

Blockless use

If you supply a custom Ember.View subclass that specifies its own template or provide a templateName option to {{view}} it can be used without supplying a block. Attempts to use both a templateName option and supply a block will throw an error.

1
{{view "MyApp.ViewWithATemplateDefined"}}

viewName property

You can supply a viewName option to {{view}}. The Ember.View instance will be referenced as a property of its parent view by this name.

1
2
3
4
5
6
aView = Ember.View.create({
  template: Ember.Handlebars.compile('{{#view viewName="aChildByName"}} hi {{/view}}')
});

aView.appendTo('body');
aView.get('aChildByName') // the instance of Ember.View created by {{view}} helper

Parameters:

path String
options Hash

Returns:

String
HTML string

with

(context, options) String

Use the {{with}} helper when you want to scope context. Take the following code as an example:

1
2
3
4
5
6
7
8
<h5>{{user.name}}</h5>

<div class="role">
  <h6>{{user.role.label}}</h6>
  <span class="role-id">{{user.role.id}}</span>

  <p class="role-desc">{{user.role.description}}</p>
</div>

{{with}} can be our best friend in these cases, instead of writing user.role.* over and over, we use {{#with user.role}}. Now the context within the {{#with}} .. {{/with}} block is user.role so you can do the following:

1
2
3
4
5
6
7
8
9
10
<h5>{{user.name}}</h5>

<div class="role">
  {{#with user.role}}
    <h6>{{label}}</h6>
    <span class="role-id">{{id}}</span>

    <p class="role-desc">{{description}}</p>
  {{/with}}
</div>

as operator

This operator aliases the scope to a new name. It's helpful for semantic clarity and to retain default scope or to reference from another {{with}} block.

1
2
3
4
5
6
7
8
9
10
// posts might not be
{{#with user.posts as blogPosts}}
  <div class="notice">
    There are {{blogPosts.length}} blog posts written by {{user.name}}.
  </div>

  {{#each post in blogPosts}}
    <li>{{post.title}}</li>
  {{/each}}
{{/with}}

Without the as operator, it would be impossible to reference user.name in the example above.

NOTE: The alias should not reuse a name from the bound property path. For example: {{#with foo.bar as foo}} is not supported because it attempts to alias using the first part of the property path, foo. Instead, use {{#with foo.bar as baz}}.

controller option

Adding controller='something' instructs the {{with}} helper to create and use an instance of the specified controller with the new context as its content.

This is very similar to using an itemController option with the {{each}} helper.

1
2
3
{{#with users.posts controller='userBlogPosts'}}
  {{!- The current context is wrapped in our controller instance }}
{{/with}}

In the above example, the template provided to the {{with}} block is now wrapped in the userBlogPost controller, which provides a very elegant way to decorate the context with custom functions/properties.

Parameters:

context Function
options Hash

Returns:

String
HTML string

yield

(options) String

{{yield}} denotes an area of a template that will be rendered inside of another template. It has two main uses:

Use with layout

When used in a Handlebars template that is assigned to an Ember.View instance's layout property Ember will render the layout template first, inserting the view's own rendered output at the {{yield}} location.

An empty <body> and the following application code:

1
2
3
4
5
6
7
8
AView = Ember.View.extend({
  classNames: ['a-view-with-layout'],
  layout: Ember.Handlebars.compile('<div class="wrapper">{{yield}}</div>'),
  template: Ember.Handlebars.compile('<span>I am wrapped</span>')
});

aView = AView.create();
aView.appendTo('body');

Will result in the following HTML output:

1
2
3
4
5
6
7
<body>
  <div class='ember-view a-view-with-layout'>
    <div class="wrapper">
      <span>I am wrapped</span>
    </div>
  </div>
</body>

The yield helper cannot be used outside of a template assigned to an Ember.View's layout property and will throw an error if attempted.

1
2
3
4
5
6
7
8
9
10
11
BView = Ember.View.extend({
  classNames: ['a-view-with-layout'],
  template: Ember.Handlebars.compile('{{yield}}')
});

bView = BView.create();
bView.appendTo('body');

// throws
// Uncaught Error: assertion failed:
// You called yield in a template that was not a layout

Use with Ember.Component

When designing components {{yield}} is used to denote where, inside the component's template, an optional block passed to the component should render:

1
2
3
4
<!-- application.hbs -->
{{#labeled-textfield value=someProperty}}
  First name:
{{/labeled-textfield}}
1
2
3
4
<!-- components/labeled-textfield.hbs -->
<label>
  {{yield}} {{input value=value}}
</label>

Result:

1
2
3
<label>
  First name: <input type="text" />
</label>

Parameters:

options Hash

Returns:

String
HTML string