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

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.

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 targeting 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:

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:

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:

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 Component 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:

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.

componentpublic

The {{component}} helper lets you add instances of Component to a
template. See 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. This helper has three modes: inline, block, and nested.

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:

app/templates/application.hbs

1

<LiveUpdatingChart />

or

app/templates/application.hbs

1

{{live-updating-chart}}

Block Form

Using the block form of this helper is similar to using the block form
of a component. Given the following application template:

The Last Update: {{this.lastUpdateTimestamp}} will be rendered in place of the {{yield}}.

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:

debuggerpublic

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 this.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:

Specifying Keys

In order to improve rendering speed, Ember will try to reuse the DOM elements
where possible. Specifically, if the same item is present in the array both
before and after the change, its DOM output will be reused.

The key option is used to tell Ember how to determine if the items in the
array being iterated over with {{#each}} has changed between renders. By
default the item's object identity is used.

This is usually sufficient, so in most cases, the key option is simply not
needed. However, in some rare cases, the objects' identities may change even
though they represent the same underlying data.

For example:

1
2
3

people.map(person => {
return { ...person, type: 'developer' };
});

In this case, each time the people array is map-ed over, it will produce
an new array with completely different objects between renders. In these cases,
you can help Ember determine how these objects related to each other with the
key option:

By doing so, Ember will use the value of the property specified (person.name
in the example) to find a "match" from the previous render. That is, if Ember
has previously seen an object from the @developers array with a matching
name, its DOM elements will be re-used.

There are two special values for key:

@index - The index of the item in the array.

@identity - The item in the array itself.

{{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
6
7

<ul>{{#each @developers as |person|}}<li>{{person.name}} is available!</li>{{else}}<li>Sorry, nobody is available for this task.</li>{{/each}}</ul>

fnpublic

The fn helper allows you to ensure a function that you are passing off
to another component, helper, or modifier has access to arguments that are
available in the template.

For example, if you have an each helper looping over a number of items, you
may need to pass a function that expects to receive the item as an argument
to a component invoked within the loop. Here's how you could use the fn
helper to pass both the function and its arguments together:

In this case the display-item component will receive a normal function
that it can invoke. When it invokes the function, the handleSelected
function will receive the item and any arguments passed, thanks to the
fn helper.

Let's take look at what that means in a couple circumstances:

When invoked as this.args.select() the handleSelected function will
receive the item from the loop as its first and only argument.

When invoked as this.args.select('foo') the handleSelected function
will receive the item from the loop as its first argument and the
string 'foo' as its second argument.

In the example above, we used @action to ensure that handleSelected is
properly bound to the items-list, but let's explore what happens if we
left out @action:

In this example, when handleSelected is invoked inside the display-item
component, it will not have access to the component instance. In other
words, it will have no this context, so please make sure your functions
are bound (via @action or other means) before passing into fn!

hash
(options)
Objectpublic

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.

Note that the hash is an empty object with no prototype chain, therefore
common methods like toString are not available in the resulting hash.
If you need to use such a method, you can use the call or apply
approach:

ifpublic

The if helper allows you to conditionally render one of two branches,
depending on the "truthiness" of a property.
For example the following values are all falsey: false, undefined, null, "", 0, NaN or an empty array.

This helper has two forms, block and inline.

Block form

You can use the block form of if to conditionally render a section of the template.

To use it, pass the conditional value to the if helper,
using the block form to wrap the section of template you want to conditionally render.
Like so:

app/templates/application.hbs

1

<Weather />

app/components/weather.hbs

1
2
3
4

{{! will not render because greeting is undefined}}{{#if @isRaining}}
Yes, grab an umbrella!
{{/if}}

You can also define what to show if the property is falsey by using
the else helper.

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

The mut helper, when used with fn, will return a function that
sets the value passed to mut to its first argument. As an example, we can create a
button that increments a value passing the value directly to the fn:

capture -- a true value indicates that events of this type will be dispatched
to the registered listener before being dispatched to any EventTarget beneath it
in the DOM tree.

once -- indicates that the listener should be invoked at most once after being
added. If true, the listener would be automatically removed when invoked.

passive -- if true, indicates that the function specified by listener will never
call preventDefault(). If a passive listener does call preventDefault(), the user
agent will do nothing other than generate a console warning. See
Improving scrolling performance with passive listeners
to learn more.

The callback function passed to {{on}} will receive any arguments that are passed
to the event handler. Most commonly this would be the event itself.

If you would like to pass additional arguments to the function you should use
the {{fn}} helper.

For example, in our example case above if you'd like to pass in the post that
was being liked when the button is clicked you could do something like:

In this example, when the button is clicked saveLike will be invoked,
it will not have access to the component instance. In other
words, it will have no this context, so please make sure your functions
are bound (via @action or other means) before passing into on!

unboundpublic

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 this.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 this.name)}}
{{! You can use any helper, including unbound, in a nested expression }}
{{capitalize (unbound this.name)}}

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

unlesspublic

The unless helper is the inverse of the if helper. It displays if a value
is falsey ("not true" or "is false"). Example values that will display with
unless: false, undefined, null, "", 0, NaN or an empty array.

Inline form

The inline unless helper conditionally renders a single property or string.
This helper acts like a ternary operator. If the first property is falsy,
the second argument will be displayed, otherwise, the third argument will be
displayed

For example, if you pass a falsey useLongGreeting to the Greeting component:

app/templates/application.hbs

1

<Greeting @useLongGreeting={{false}} />

app/components/greeting.hbs

1

{{unless @useLongGreeting "Hi""Hello"}} Ben

Then it will display:

1

Hi Ben

Block form

Like the if helper, the unless helper also has a block form.

The following will not render anything:

app/templates/application.hbs

1

<Greeting />

app/components/greeting.hbs

1
2
3

{{#unless @greeting}}
No greeting was found. Why not set one?
{{/unless}}

You can also use an else helper with the unless block. The
else will display if the value is truthy.

with
(options)
Stringpublic

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, undefinednull, "", 0, NaN or
an empty array, the block will not be rendered.

app/templates/application.hbs

1
2
3
4
5
6
7
8
9

{{! Will only render if user.posts contains items}}{{#with @model.posts as |blogPosts|}}<divclass="notice">
There are {{blogPosts.length}} blog posts written by {{@model.name}}.
</div>{{#each blogPosts as |post|}}<li>{{post.title}}</li>{{/each}}{{/with}}