Ember.Templates.helpers Class

The {{action}} helper provides a way to pass triggers for behavior (usually just a function) between components, and into components from controllers.

Passing functions with the action helper

There are three contexts an action helper can be used in. The first two contexts to discuss are attribute context, and Handlebars value context.

1
2
3
4
5

{{! An example of attribute context }}
<div onclick={{action "save"}}></div>
{{! Examples of Handlebars value context }}
{{input on-input=(action "save")}}
{{yield (action "refreshData") andAnotherParam}}

In these contexts, the helper is called a "closure action" helper. Its behavior is simple: If passed a function name, read that function off the actions property of the current context. Once that function is read (or if a function was passed), create a closure over that function and any arguments.

The resulting value of an action helper used this way is simply a function. For example, in the attribute context:

1
2

{{! An example of attribute context }}
<div onclick={{action "save"}}></div>

The resulting template render logic would be:

1
2
3
4
5
6
7

var div = document.createElement('div');
var actionFunction = (function(context){
  return function() {
    return context.actions.save.apply(context, arguments);
  };
})(context);
div.onclick = actionFunction;

Thus when the div is clicked, the action on that context is called. Because the actionFunction is just a function, closure actions can be passed between components and still execute in the correct context.

Here is an example action handler on a component:

1
2
3
4
5
6
7

export default Ember.Component.extend({
  actions: {
    save() {
      this.get('model').save();
    }
  }
});

Actions are always looked up on the actions property of the current context. This avoids collisions in the naming of common actions, such as destroy.

Two options can be passed to the action helper when it is used in this way.

• target=someProperty will look to someProperty instead of the current context for the actions hash. This can be useful when targetting a service for actions.
• value="target.value" will read the path target.value off the first argument to the action when it is called and rewrite the first argument to be that value. This is useful when attaching actions to event listeners.

Invoking an action

Closure actions curry both their scope and any arguments. When invoked, any additional arguments are added to the already curried list.

Actions should be invoked using the sendAction method. The first argument to sendAction is the action to be called, and additional arguments are passed to the action function. This has interesting properties combined with currying of arguments. For example:

1
2
3
4
5
6
7
8

export default Ember.Component.extend({
  actions: {
    // Usage {{input on-input=(action (action 'setName' model) value="target.value")}}
    setName(model, name) {
      model.set('name', name);
    }
  }
});

The first argument (model) was curried over, and the run-time argument (event) becomes a second argument. Action calls can be nested this way because each simply returns a function. Any function can be passed to the {{action}} helper, including other actions.

Actions invoked with sendAction have the same currying behavior as demonstrated with on-input above. For example:

1
2
3
4
5
6
7

export default Ember.Component.extend({
  actions: {
    setName(model, name) {
      model.set('name', name);
    }
  }
});

1

{{my-input submit=(action 'setName' model)}}

1
2
3
4
5
6
7

// app/components/my-component.js
export default Ember.Component.extend({
  click() {
    // Note that model is not passed, it was curried in the template
    this.sendAction('submit', 'bob');
  }
});

Attaching actions to DOM elements

The third context of the {{action}} helper can be called "element space". For example:

1
2

{{! An example of element space }}
<div {{action "save"}}></div>

Used this way, the {{action}} helper provides a useful shortcut for registering an HTML element in a template for a single DOM event and forwarding that interaction to the template's context (controller or component).

If the context of a template is a controller, actions used this way will bubble to routes when the controller does not implement the specified action. Once an action hits a route, it will bubble through the route hierarchy.

Event Propagation

{{action}} helpers called in element space can control event bubbling. Note that the closure style actions cannot.

Events triggered through the action helper will automatically have .preventDefault() called on them. You do not need to do so in your event handlers. If you need to allow event propagation (to handle file inputs for example) you can supply the preventDefault=false option to the {{action}} helper:

1
2
3
4

<div {{action "sayHello" preventDefault=false}}>
  <input type="file" />
  <input type="checkbox" />
</div>

To disable bubbling, pass bubbles=false to the helper:

1

<button {{action 'edit' post bubbles=false}}>Edit</button>

To disable bubbling with closure style actions you must create your own wrapper helper that makes use of event.stopPropagation():

1

<div onclick={{disable-bubbling (action "sayHello")}}>Hello</div>

1
2
3
4
5
6
7
8
9
10
11
12

// app/helpers/disable-bubbling.js
import Ember from 'ember';

export function disableBubbling([action]) {
  return function(event) {
    event.stopPropagation();

    return action(event);
  };
}

export default Ember.Helper.helper(disableBubbling);

If you need the default handler to trigger you should either register your own event handler, or use event methods on your view class. See "Responding to Browser Events" in the documentation for Ember.View for more information.

Specifying DOM event type

{{action}} helpers called in element space can specify an event type.

By default the {{action}} helper registers for DOM click events. You can supply an on option to the helper to specify a different DOM event name:

1
2
3

<div {{action "anActionName" on="doubleClick"}}>
  click me
</div>

See "Event Names" for a list of acceptable DOM event names.

Specifying whitelisted modifier keys

{{action}} helpers called in element space can specify modifier keys.

By default the {{action}} helper will ignore click events with pressed modifier keys. You can supply an allowedKeys option to specify which keys should not be ignored.

1
2
3

<div {{action "anActionName" allowedKeys="alt"}}>
  click me
</div>

This way the action will fire when clicking with the alt key pressed down.

Alternatively, supply "any" to the allowedKeys option to accept any combination of modifier keys.

1
2
3

<div {{action "anActionName" allowedKeys="any"}}>
  click me with any key pressed
</div>

Specifying a Target

A target option can be provided to the helper to change which object will receive the method call. This option must be a path to an object, accessible in the current context:

1
2
3
4

{{! app/templates/application.hbs }}
<div {{action "anActionName" target=someService}}>
  click me
</div>

1
2
3
4

// app/controllers/application.js
export default Ember.Controller.extend({
  someService: Ember.inject.service()
});

The {{component}} helper lets you add instances of Ember.Component to a template. See Ember.Component for additional information on how a Component functions. {{component}}'s primary use is for cases where you want to dynamically change which type of component is rendered as the state of your application changes. The provided block will be applied as the template for the component. Given an empty <body> the following template:

1
2

{{! application.hbs }}
{{component infographicComponentName}}

And the following application code:

1
2
3
4
5
6
7
8
9
10
11

export default Ember.Controller.extend({
  infographicComponentName: computed('isMarketOpen', {
    get() {
      if (this.get('isMarketOpen')) {
        return 'live-updating-chart';
      } else {
        return 'market-close-summary';
      }
    }
  })
});

The live-updating-chart component will be appended when isMarketOpen is true, and the market-close-summary component will be appended when isMarketOpen is false. If the value changes while the app is running, the component will be automatically swapped out accordingly. Note: You should not use this helper when you are consistently rendering the same component. In that case, use standard component syntax, for example:

1
2

{{! application.hbs }}
{{live-updating-chart}}

Nested Usage

The component helper can be used to package a component path with initial attrs. The included attrs can then be merged during the final invocation.

For example, given a person-form component with the following template:

1
2

{{yield (hash
    nameInput=(component "my-input-component" value=model.name placeholder="First Name"))}}

The following snippet:

1
2
3

{{#person-form as |form|}}
  {{component form.nameInput placeholder="Username"}}
{{/person-form}}

would output an input whose value is already bound to model.name and placeholder is "Username".

Concatenates the given arguments into a string.

Example:

1
2
3

{{some-component name=(concat firstName " " lastName)}}

{{! would pass name="<first name value> <last name value>" to the component}}

Execute the debugger statement in the current template's context.

1

{{debugger}}

When using the debugger helper you will have access to a get function. This function retrieves values available in the context of the template. 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 attempt to retrieve this value:

1

> get('foo')

get is also aware of keywords. So in this situation

1
2
3

{{#each items as |item|}}
  {{debugger}}
{{/each}}

You'll be able to get values from the current item:

1

> get('item.name')

You can also access the context of the view to make sure it is the object that you expect:

1

> context

The {{#each}} helper loops over elements in a collection. It is an extension of the base Handlebars {{#each}} helper.

The default behavior of {{#each}} is to yield its inner block once for every item in an array passing the item as the first block parameter.

1

var developers = [{name: 'Yehuda'},{name: 'Tom'}, {name: 'Paul'}];

1
2
3
4

{{#each developers key="name" as |person|}}
  {{person.name}}
  {{! `this` is whatever it was outside the #each }}
{{/each}}

The same rules apply to arrays of primitives.

1

var developerNames = ['Yehuda', 'Tom', 'Paul']

1
2
3

{{#each developerNames key="@index" as |name|}}
  {{name}}
{{/each}}

During iteration, the index of each item in the array is provided as a second block parameter.

1
2
3
4
5

<ul>
  {{#each people as |person index|}}
    <li>Hello, {{person.name}}! You're number {{index}} in line</li>
  {{/each}}
</ul>

Specifying Keys

The key option is used to tell Ember how to determine if the array being iterated over with {{#each}} has changed between renders. By helping Ember detect that some elements in the array are the same, DOM elements can be re-used, significantly improving rendering speed.

For example, here's the {{#each}} helper with its key set to id:

1
2

{{#each model key="id" as |item|}}
{{/each}}

When this {{#each}} re-renders, Ember will match up the previously rendered items (and reorder the generated DOM elements) based on each item's id property.

By default the item's own reference is used.

{{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 developers as |person|}}
  {{person.name}}
{{else}}
  <p>Sorry, nobody is available for this task.</p>
{{/each}}

The {{each-in}} helper loops over properties on an object. It is unbound, in that new (or removed) properties added to the target object will not be rendered.

For example, given a user object that looks like:

1
2
3
4

{
  "name": "Shelly Sails",
  "age": 42
}

This template would display all properties on the user object in a list:

1
2
3
4
5

<ul>
{{#each-in user as |key value|}}
  <li>{{key}}: {{value}}</li>
{{/each-in}}
</ul>

Outputting their name and age.

Dynamically look up a property on an object. The second argument to {{get}} should have a string value, although it can be bound.

For example, these two usages are equivilent:

1
2

{{person.height}}
{{get person "height"}}

If there were several facts about a person, the {{get}} helper can dynamically pick one:

1

{{get person factName}}

For a more complex example, this template would allow the user to switch between showing the user's height and weight with a click:

1
2
3

{{get person factName}}
<button {{action (mut factName) "height"}}>Show height</button>
<button {{action (mut factName) "weight"}}>Show weight</button>

The {{get}} helper can also respect mutable values itself. For example:

1
2
3

{{input value=(mut (get person factName)) type="text"}}
<button {{action (mut factName) "height"}}>Show height</button>
<button {{action (mut factName) "weight"}}>Show weight</button>

Would allow the user to swap what fact is being displayed, and also edit that fact via a two-way mutable binding.

Use the {{hash}} helper to create a hash to pass as an option to your components. This is specially useful for contextual components where you can just yield a hash:

1
2
3
4

{{yield (hash
   name='Sarah'
   title=office
)}}

Would result in an object such as:

1

{ name: 'Sarah', title: this.get('office') }

Where the title is bound to updates of the office property.

Use the if block helper to conditionally render a block depending on a property. If the property is "falsey", for example: false, undefined, null, "", 0, NaN or an empty array, the block will not be rendered.

1
2
3
4

{{! will not render if foo is falsey}}
{{#if foo}}
  Welcome to the {{foo.bar}}
{{/if}}

You can also specify a template to show if the property is falsey by using the else helper.

1
2
3
4
5
6

{{! is it raining outside?}}
{{#if isRaining}}
  Yes, grab an umbrella!
{{else}}
  No, it's lovely outside!
{{/if}}

You are also able to combine else and if helpers to create more complex conditional logic.

1
2
3
4
5
6
7

{{#if isMorning}}
  Good morning
{{else if isAfternoon}}
  Good afternoon
{{else}}
  Good night
{{/if}}

You can use if inline to conditionally render a single property or string. This helper acts like a ternary operator. If the first property is truthy, the second argument will be displayed, if not, the third argument will be displayed

1

{{if useLongGreeting "Hello" "Hi"}} Dave

Finally, you can use the if helper inside another helper as a subexpression.

1

{{some-component height=(if isBig "100" "10")}}

The {{input}} helper lets you create an HTML <input /> component. It causes an Ember.TextField component to be rendered. For more info, see the Ember.TextField docs and the templates guide.

1

{{input value="987"}}

renders as:

1

<input type="text" value="987" />

Text field

If no type option is specified, a default of type 'text' is used.

Many of the standard HTML attributes may be passed to this helper.

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).

A very common use of this helper is to bind the value of an input to an Object's attribute:

1
2

Search:
{{input value=searchWord}}

In this example, the inital value in the <input /> will be set to the value of searchWord. If the user changes the text, the value of searchWord will also be updated.

Actions

The helper can send multiple actions based on user events. The action property defines the action which is sent 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
• key-up

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

{{input focus-out="alertMessage"}}

See more about Text Support Actions

Extending Ember.TextField

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. Expect isolated component semantics, not legacy 1.x view semantics (like controller being present).

See more about Ember components

Checkbox

Checkboxes are special forms of the {{input}} helper. To create a <checkbox />:

1
2

Emberize Everything:
{{input type="checkbox" name="isEmberized" checked=isEmberized}}

This will bind checked state of this checkbox to the value of isEmberized -- if either one changes, it will be reflected in the other.

The following HTML attributes can be set via the helper:

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

Extending Ember.Checkbox

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']
});

The {{link-to}} component renders a link to the supplied routeName passing an optionally supplied model to the route as its model context of the route. The block for {{link-to}} becomes the innerHTML of the rendered element:

1
2
3

{{#link-to 'photoGallery'}}
  Great Hamster Photos
{{/link-to}}

You can also use an inline form of {{link-to}} component by passing the link text as the first argument to the component:

1

{{link-to 'Great Hamster Photos' 'photoGallery'}}

Both will result in:

1
2
3

<a href="/hamster-photos">
  Great Hamster Photos
</a>

Supplying a tagName

By default {{link-to}} renders an <a> element. This can be overridden for a single use of {{link-to}} by supplying a tagName option:

1
2
3

{{#link-to 'photoGallery' tagName="li"}}
  Great Hamster Photos
{{/link-to}}

1
2
3

<li>
  Great Hamster Photos
</li>

To override this option for your entire application, see "Overriding Application-wide Defaults".

Disabling the link-to component

By default {{link-to}} is enabled. any passed value to the disabled component property will disable the link-to component.

static use: the disabled option:

1
2
3

{{#link-to 'photoGallery' disabled=true}}
  Great Hamster Photos
{{/link-to}}

dynamic use: the disabledWhen option:

1
2
3

{{#link-to 'photoGallery' disabledWhen=controller.someProperty}}
  Great Hamster Photos
{{/link-to}}

any passed value to disabled will disable it except undefined. to ensure that only true disable the link-to component you can override the global behaviour of Ember.LinkComponent.

1
2
3
4
5
6
7
8

Ember.LinkComponent.reopen({
  disabled: Ember.computed(function(key, value) {
    if (value !== undefined) {
      this.set('_isDisabled', value === true);
    }
    return value === true ? get(this, 'disabledClass') : false;
  })
});

see "Overriding Application-wide Defaults" for more.

Handling href

{{link-to}} will use your application's Router to fill the element's href property with a url that matches the path to the supplied routeName for your router's configured Location scheme, which defaults to Ember.HashLocation.

Handling current route

{{link-to}} will apply a CSS class name of 'active' when the application's current route matches the supplied routeName. For example, if the application's current route is 'photoGallery.recent' the following use of {{link-to}}:

1
2
3

{{#link-to 'photoGallery.recent'}}
  Great Hamster Photos
{{/link-to}}

will result in

1
2
3

<a href="/hamster-photos/this-week" class="active">
  Great Hamster Photos
</a>

The CSS class name used for active classes can be customized for a single use of {{link-to}} by passing an activeClass option:

1
2
3

{{#link-to 'photoGallery.recent' activeClass="current-url"}}
  Great Hamster Photos
{{/link-to}}

1
2
3

<a href="/hamster-photos/this-week" class="current-url">
  Great Hamster Photos
</a>

To override this option for your entire application, see "Overriding Application-wide Defaults".

Keeping a link active for other routes

If you need a link to be 'active' even when it doesn't match the current route, you can use the current-when argument.

1
2
3

{{#link-to 'photoGallery' current-when='photos'}}
  Photo Gallery
{{/link-to}}

This may be helpful for keeping links active for:

• non-nested routes that are logically related
• some secondary menu approaches
• 'top navigation' with 'sub navigation' scenarios

A link will be active if current-when is true or the current route is the route this link would transition to.

To match multiple routes 'space-separate' the routes:

1
2
3

{{#link-to 'gallery' current-when='photos drawings paintings'}}
  Art Gallery
{{/link-to}}

Supplying a model

An optional model argument can be used for routes whose paths contain dynamic segments. This argument will become the model context of the linked route:

1
2
3

Router.map(function() {
  this.route("photoGallery", {path: "hamster-photos/:photo_id"});
});

1
2
3

{{#link-to 'photoGallery' aPhoto}}
  {{aPhoto.title}}
{{/link-to}}

1
2
3

<a href="/hamster-photos/42">
  Tomster
</a>

Supplying multiple models

For deep-linking to route paths that contain multiple dynamic segments, multiple model arguments can be used. As the router transitions through the route path, each supplied model argument will become the context for the route with the dynamic segments:

1
2
3
4
5

Router.map(function() {
  this.route("photoGallery", { path: "hamster-photos/:photo_id" }, function() {
    this.route("comment", {path: "comments/:comment_id"});
  });
});

This argument will become the model context of the linked route:

1
2
3

{{#link-to 'photoGallery.comment' aPhoto comment}}
  {{comment.body}}
{{/link-to}}

1
2
3

<a href="/hamster-photos/42/comments/718">
  A+++ would snuggle again.
</a>

Supplying an explicit dynamic segment value

If you don't have a model object available to pass to {{link-to}}, an optional string or integer argument can be passed for routes whose paths contain dynamic segments. This argument will become the value of the dynamic segment:

1
2
3

Router.map(function() {
  this.route("photoGallery", { path: "hamster-photos/:photo_id" });
});

1
2
3

{{#link-to 'photoGallery' aPhotoId}}
  {{aPhoto.title}}
{{/link-to}}

1
2
3

<a href="/hamster-photos/42">
  Tomster
</a>

When transitioning into the linked route, the model hook will be triggered with parameters including this passed identifier.

Allowing Default Action

By default the {{link-to}} component prevents the default browser action by calling preventDefault() as this sort of action bubbling is normally handled internally and we do not want to take the browser to a new URL (for example).

If you need to override this behavior specify preventDefault=false in your template:

1
2
3

{{#link-to 'photoGallery' aPhotoId preventDefault=false}}
  {{aPhotoId.title}}
{{/link-to}}

Overriding attributes

You can override any given property of the Ember.LinkComponent that is generated by the {{link-to}} component by passing key/value pairs, like so:

1
2
3

{{#link-to  aPhoto tagName='li' title='Following this link will change your life' classNames='pic sweet'}}
  Uh-mazing!
{{/link-to}}

See Ember.LinkComponent for a complete list of overrideable properties. Be sure to also check out inherited properties of LinkComponent.

Overriding Application-wide Defaults

{{link-to}} creates an instance of Ember.LinkComponent for rendering. To override options for your entire application, reopen Ember.LinkComponent and supply the desired values:

1
2
3
4

Ember.LinkComponent.reopen({
  activeClass: "is-active",
  tagName: 'li'
})

It is also possible to override the default event in this manner:

1
2
3

Ember.LinkComponent.reopen({
  eventName: 'customEventName'
});

Calls Ember.String.loc with the provided string. This is a convenient way to localize text within a template. For example:

1
2
3

Ember.STRINGS = {
  '_welcome_': 'Bonjour'
};

1
2
3

<div class='message'>
  {{loc '_welcome_'}}
</div>

1
2
3

<div class='message'>
  Bonjour
</div>

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

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

The mut helper lets you clearly specify that a child Component can update the (mutable) value passed to it, which will change the value of the parent component.

This is very helpful for passing mutable values to a Component of any size, but critical to understanding the logic of a large/complex Component.

To specify that a parameter is mutable, when invoking the child Component:

1

{{my-child childClickCount=(mut totalClicks)}}

The child Component can then modify the parent's value as needed:

1
2
3
4
5
6

// my-child.js
export default Component.extend({
  click() {
    this.get('childClickCount').update(this.get('childClickCount').value + 1);
  }
});

Additionally, the mut helper can be combined with the action helper to mutate a value. For example:

1

{{my-child childClickCount=totalClicks click-count-change=(action (mut "totalClicks"))}}

The child Component would invoke the action with the new click value:

1
2
3
4
5
6

// my-child.js
export default Component.extend({
  click() {
    this.get('clickCountChange')(this.get('childClickCount') + 1);
  }
});

The mut helper changes the totalClicks value to what was provided as the action argument.

See a 2.0 blog post for additional information on using {{mut}}.

The {{outlet}} helper lets you specify where a child route will render in your template. An important use of the {{outlet}} helper is in your application's application.hbs file:

1
2
3
4
5
6
7
8
9
10
11
12

{{! app/templates/application.hbs }}

<!-- header content goes here, and will always display -->
{{my-header}}

<div class="my-dynamic-content">
  <!-- this content will change based on the current route, which depends on the current URL -->
  {{outlet}}
</div>

<!-- footer content goes here, and will always display -->
{{my-footer}}

See templates guide for additional information on using {{outlet}} in application.hbs.

You may also specify a name for the {{outlet}}, which is useful when using more than one {{outlet}} in a template:

1
2
3

{{outlet "menu"}}
{{outlet "sidebar"}}
{{outlet "main"}}

Your routes can then render into a specific one of these outlets by specifying the outlet attribute in your renderTemplate function:

1
2
3
4
5
6
7

// app/routes/menu.js

export default Ember.Route.extend({
  renderTemplate() {
    this.render({ outlet: 'menu' });
  }
});

See the routing guide for more information on how your route interacts with the {{outlet}} helper.

Note: Your content will not render if there isn't an {{outlet}} for it.

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.

This is a helper to be used in conjunction with the link-to helper. It will supply url query parameters to the target route.

Example

1

{{#link-to 'posts' (query-params direction="asc")}}Sort{{/link-to}}

Calling {{render}} from within a template will insert another template that matches the provided name. The inserted template will access its properties on its own controller (rather than the controller of the parent template). If a view class with the same name exists, the view class also will be used. Note: A given controller may only be used once in your app in this manner. A singleton instance of the controller will be created for you. Example:

1
2
3

App.NavigationController = Ember.Controller.extend({
  who: "world"
});

1
2

<!-- navigation.hbs -->
Hello, {{who}}.

1
2
3

<!-- application.hbs -->
<h1>My great app</h1>
{{render "navigation"}}

1
2
3
4

<h1>My great app</h1>
<div class='ember-view'>
  Hello, world.
</div>

Optionally you may provide a second argument: a property path that will be bound to the model property of the controller. If a model property path is specified, then a new instance of the controller will be created and {{render}} can be used multiple times with the same name.

For example if you had this author template.

1
2
3
4

<div class="author">
  Written by {{firstName}} {{lastName}}.
  Total Posts: {{postCount}}
</div>

You could render it inside the post template using the render helper.

1
2
3
4
5

<div class="post">
  <h1>{{title}}</h1>
  <div>{{body}}</div>
  {{render "author" author}}
</div>

{{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. Expect isolated component semantics, not legacy 1.x view semantics (like controller being present).

See more about Ember components

The {{unbound}} helper disconnects the one-way binding of a property, essentially freezing its value at the moment of rendering. For example, in this example the display of the variable name will not change even if it is set with a new value:

1

{{unbound name}}

Like any helper, the unbound helper can accept a nested helper expression. This allows for custom helpers to be rendered unbound:

1
2
3
4

{{unbound (some-custom-helper)}}
{{unbound (capitalize name)}}
{{! You can use any helper, including unbound, in a nested expression }}
{{capitalize (unbound name)}}

The unbound helper only accepts a single argument, and it return an unbound value.

The unless helper is the inverse of the if helper. Its block will be rendered if the expression contains a falsey value. All forms of the if helper can also be used with unless.

Use the {{with}} helper when you want to alias a property to a new name. This is helpful for semantic clarity as it allows you to retain default scope or to reference a property from another {{with}} block.

If the aliased property is "falsey", for example: false, undefined null, "", 0, NaN or an empty array, the block will not be rendered.

1
2
3
4
5
6
7
8
9

{{! Will only render if user.posts contains items}}
{{#with user.posts as |blogPosts|}}
  <div class="notice">
    There are {{blogPosts.length}} blog posts written by {{user.name}}.
  </div>
  {{#each blogPosts as |post|}}
    <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|}}.