Helper Functions

It's possible to use plain functions for helpers and modifiers. A plain helper function can be "local" to or defined on components and controllers.

import Component from '@glimmer/component';
import { setComponentTemplate } from '@ember/component';
import { hbs } from 'ember-cli-htmlbars';

export default class Message extends Component {
  substring = (string, start, end) => string.substring(start, end);
}

We can then use this helper in the component's template to get the first letter of the username.

<Message::Avatar
  @title="{{@username}}'s avatar"
  @initial={{@avatarInitial}}
  @initial={{this.substring @username 0 1}}
  @isActive={{@userIsActive}}
  class={{if @isCurrentUser "current-user"}}
/>
<section>
  <Message::Username
    @name={{@username}}
    @localTime={{@userLocalTime}}
  />

  {{yield}}
</section>

Helpers default to using positional arguments, but sometimes it can make the corresponding syntax {{substring @username 0 1}} a little hard to read. We see some numbers at the end but can't tell what exactly they mean. We can use named arguments to make the substring helper easier to read.

Using named arguments, we could make our template a lot clearer.

<Message::Avatar
  @title="{{@username}}'s avatar"
  @initial={{substring @username 0 1}}
  {{! This won't work yet! We need to update the substring helper }}
  @initial={{substring @username start=0 end=1}}
  @isActive={{@userIsActive}}
  class={{if @isCurrentUser "current-user"}}
/>
<section>
  <Message::Username
    @name={{@username}}
    @localTime={{@userLocalTime}}
  />

  {{yield}}
</section>

Helpers take named arguments as a JavaScript object. All named arguments are grouped into an "options object" as the last parameter.

import Component from '@glimmer/component';
import { setComponentTemplate } from '@ember/component';
import { hbs } from 'ember-cli-htmlbars';

export default class Message extends Component {
  substring = (string, start, end) => string.substring(start, end);
  substring = (string, options) => string.substring(options.start, options.end);
}

You can mix positional and named arguments to make your templates easy to read:

{{this.calculate 1 2 op="add"}}

export default class Calculator extends Component {
  calculate(first, second, options) {
    // ...
  }
}

Sometimes, you might see helpers invoked by placing them inside parentheses, (). This means that a Helper is being used inside of another Helper or Component. This is referred to as a "nested" Helper Invocation. Parentheses must be used because curly braces {{}} cannot be nested.

{{this.sum (this.multiply 2 4) 2}}

In this example, we are using a helper to multiply 2 and 4 before passing the value into {{sum}}.

Thus, the output of these combined helpers is 10.

As you move forward with these template guides, keep in mind that a helper can be used anywhere a normal value can be used.

Many of Ember's built-in helpers (as well as your custom helpers) can be used in nested form.

Next to local helpers, ember provides a way to use global helpers. We define global helper functions in the app/helpers folder. Once defined, they will be available to use directly inside all templates in your app.

Zoey says...

Before Ember 4.5, using global helpers was the only way to define helpers.

To implement the helper, we define and export a regular JavaScript function:

export default function substring(string, start, end) {
  return string.substring(start, end);
}

We can then use this helper in the component's template to get the first letter of the username.

<Message::Avatar
  @title="{{@username}}'s avatar"
  @initial={{@avatarInitial}}
  @initial={{substring @username 0 1}}
  @isActive={{@userIsActive}}
  class={{if @isCurrentUser "current-user"}}
/>
<section>
  <Message::Username
    @name={{@username}}
    @localTime={{@userLocalTime}}
  />

  {{yield}}
</section>

Similar to local helpers, global helpers also can mix positional and named arguments.

<Message::Avatar
  @title="{{@username}}'s avatar"
  @initial={{substring @username 0 1}}
  {{! This won't work yet! We need to update the substring helper }}
  @initial={{substring @username start=0 end=1}}
  @isActive={{@userIsActive}}
  class={{if @isCurrentUser "current-user"}}
/>
<section>
  <Message::Username
    @name={{@username}}
    @localTime={{@userLocalTime}}
  />

  {{yield}}
</section>

export default function substring(string, { start, end }) {
  return string.substring(start || 0, end);
}

Sometimes, you may encounter helpers defined using the helper function:

import { helper } from '@ember/component/helper';

function substring(positional, { start, end }) {
  const string = positional[0];
  return string.substring(start || 0, end);
}

export default helper(substring);

Zoey says...

Before Ember 4.5, this was the only way to define helpers.

By wrapping the function using the helper() function, Ember will extract the arguments passed from the template. It'll then call your function with an array (positional arguments passed in the template) and an object (named arguments passed in the template).

This style mostly exists for backwards compatibility reasons, but the other advantage is that it makes it easier to untangle the positional and named arguments (e.g. when your helper accept an arbitrary number of positional arguments and optionally some named arguments). Note that, however, it also makes it more difficult to reuse the logic of the helper function from regular JavaScript code outside of templates. On the other hand, if you define your helpers as plain JavaScript function, as we have been doing until now, you are able to import and call them from any JavaScript files in your app.

Classic helpers can also be defined using class syntax. For instance, we could define the substring helper using classes instead.

import Helper from '@ember/component/helper';

export default class Substring extends Helper {
  compute(positional, { start, end }) {
    const string = positional[0];
    return string.substring(start || 0, end);
  }
}

Class helpers are useful when the helper logic is fairly complicated, requires fine-grained control of the helper lifecycle, is stateful (we'll be discussing state in the next chapter), or requiring access to a service.

Below you will find some useful template helpers documented. For the full list of available helpers, you can check the template helpers API documentation.

The {{get}} helper makes it easy to dynamically look up a property on an object or an element in an array. The second argument to {{get}} can be a string or a number, depending on the object being accessed.

To access a property on an object with a string key:

{{get this.someObject "object_key"}}

To access the first element in an array:

{{get this.someArray 0}}

To access a property on an object with a dynamic key:

{{get this.address this.part}}

If the part getter returns "zip", this will display the result of this.address.zip. If it returns "city", you get this.address.city.

We mentioned above that helpers can be nested. This can be combined with different dynamic helpers. For example, the {{concat}} helper makes it easy to dynamically send a number of parameters to a component or helper as a single parameter in the format of a concatenated string.

{{get this.foo (concat "item" this.index)}}

This will display the result of this.foo.item1 when index is 1, and this.foo.item2 when index is 2, etc.

Now let's say your template is starting to get a bit cluttered and you want to clean up the logic in your templates. This can be achieved with the let block helper. The {{let}} helper lets you create new bindings (or temporary variables) in your template.

Say your template now looks like this:

Welcome back {{concat (capitalize this.person.givenName) ' ' (capitalize this.person.familyName)}}

Account Details:
Given Name: {{capitalize this.person.givenName}}
Family Name: {{capitalize this.person.familyName}}

As mentioned in the previous section, we use the concat helper to render both person.givenName and person.familyName in one go. But we also want to make sure that the names are capitalized. It gets a bit repetitive to keep writing capitalize and honestly, we might just forget it at some point. Thankfully, we can use the {{let}} helper to fix this:

{{#let (capitalize this.person.givenName) (capitalize this.person.familyName)
  as |givenName familyName|
}}
  Welcome back {{concat givenName ' ' familyName}}

  Account Details:
  Given Name: {{givenName}}
  Family Name: {{familyName}}
{{/let}}

Now, as long as your template is wrapped in the let helper, you can access the capitalized given name and family name as givenName and familyName instead of (capitalize this.person.givenName).

Using the {{array}} helper, you can pass arrays directly from the template as an argument to your components.

<MyComponent
  @people={{array
    'Tom Dale'
    'Yehuda Katz'
    this.myOtherPerson
  }}
/>

In the component's template, you can then use the people argument as an array:

<ul>
  {{#each @people as |person|}}
    <li>{{person}}</li>
  {{/each}}
</ul>

Using the {{hash}} helper, you can pass objects directly from the template as an argument to your components.

<Greeting
  @person={{hash
    givenName='Jen'
    familyName='Weber'
  }}
/>

In the component's template, you can then use the person object:

Hello, {{@person.givenName}} {{@person.familyName}}

Using the {{in-element}} helper, you can render content into a DOM element that is in a different part of the page. For instance, we might want to render a modal, tooltip, or dropdown.

Suppose we want to show a dropdown menu when the user clicks on a button. The code below shows a <button> element, a placeholder <div> element, and a dropdown component. The argument @show, when set to true, will add the dropdown to the placeholder div.

  <button
    type="button"
    {{on "click" this.onClickShowDropdown}}
  >
    More Actions
  </button>
  <div id="dropdown-destination" />

  <MyDropdownComponent
    @show={{this.showDropdown}}
  />

When the user clicks on the button, the flag showDropdown will be set to true.

  @tracked
  showDropdown = false;

  @action
  onClickShowDropdown() {
    this.showDropdown = true;
  }

The dropdown component uses the argument @show to activate the in-element helper. We must provide the destination DOM element to the helper. In other words, where should the helper render its block content?

{{#if @show}}
  {{#in-element this.destinationElement}}
    <ul>
      <li>Archive</li>
      <li>Mark as Read</li>
      <li>Report</li>
    </ul>
  {{/in-element}}
{{/if}}

  get destinationElement() {
    return document.querySelector('#dropdown-destination');
  }

After the user clicks on the button, the final HTML result for the div will be like this:

  <div id="dropdown-destination">
    <ul>
      <li>Archive</li>
      <li>Mark as Read</li>
      <li>Report</li>
    </ul>
  </div>

Things to note:

• The destination element needs to exist in the DOM before we use the helper. Otherwise, an error will be thrown if you are in development mode. The error is not thrown in production.
• When the destination element changes, the content defined in in-element will re-render completely.
• By default, the in-element helper replaces the destination element's existing content with the helper's block content. If you want to instead append the block content, you can pass insertBefore=null.