ember-event-helpers

Complimentary template helpers to be used with the {{on}} element modifier specified by RFC #471 "{{on}} modifier".

Installation

ember install ember-event-helpers

If you are below Ember 3.10, you'll also want to install the {{on}} modifier polyfill:

ember install ember-on-modifier

Compatibility

• Ember.js v2.18 or above
• ember-cli v2.13 or above

Usage

| Template Helper | Event method | |----------------------------------------------------------------------|----------------------------------------------------------| | (prevent-default fn) | event.preventDefault() | | (stop-propagation fn | event.stopPropagation() | | (stop-immediate-propagation fn) | stopImmediatePropagation |

👉 For usage information on {{on}} itself, refer to the RFC or polyfill documentation.

All three template helpers return a function that, when invoked, will call the associated Event method on the first argument. The helper themselves also take an optional fn argument, which is a function that will be called synchronously afterwards with all input arguments of the returned function. The return value of fn is passed through.

Sounds complicated? Let's see some examples instead! 😅

Template Helpers

(prevent-default)

Calls event.preventDefault().

Prevent the user agent from performing the default action, like toggling a checkbox, when it is clicked. The event continues to propagate as usual.

<label>
  <input type="checkbox" {{on "click" this.onClick}}>
  Click me baby, one more time!
</label>
<label>
  <input type="checkbox" {{on "click" (prevent-default this.onClick)}}>
  Can't touch this!
</label>

import Component from '@ember/component';
import { action } from '@ember/object';

export default class CheckboxesComponent extends Component {
  @action
  onClick(event: MouseEvent) {
    if (event.defaultPrevented) {
      console.log('Checkbox will not be toggled.');
    } else {
      console.log('Checkbox will be toggled.');
    }
  }
}

👉 The @action decorator is used to bind the onClick method's this context to the component instance. This is not required here, since this is not accessed, but in order to not break with patterns, we still do it here.

Using the old {{action}} modifier you would express the same thing like this:

<label>
  <input type="checkbox" {{action this.onClick on="click"}}>
  Click me baby, one more time!
</label>
<label>
  <input type="checkbox" {{action this.onClick on="click" preventDefault=true}}>
  Can't touch this!
</label>

(stop-propagation)

Calls event.stopPropagation().

Stops further propagation of the current event in the capturing phase (down the DOM) and bubbling phase (up the DOM).

<div class="outer" {{on "click" this.onOuterClick}}>
  <div class="inner-a" {{on "click" this.onInnerClick}}>
    I bubble.
  </div>
  <div class="inner-b" {{on "click" (stop-propagation this.onInnerClick)}}>
   I don't bubble.
  </div>
</div>

import Component from '@ember/component';
import { action } from '@ember/object';

export default class BubbleGumComponent extends Component {
  @action
  onOuterClick(event: MouseEvent) {
    console.log('outer');
  }

  @action
  onInnerClick(event: MouseEvent) {
    console.log('inner');
  }
}

Clicking .inner-a will print:

inner
outer

Clicking .inner-b will only print:

inner

If you enable the capture event option and use (stop-propagation) with it, the event propagation will already be stopped in the capture phase ("down the DOM").

<div class="outer" {{on "click" (stop-propagation this.onOuterClick)}}>
  <div class="inner" {{on "click" this.onInnerClick}}>
    My listener never gets called.
  </div>
</div>

Clicking .inner will only print:

outer

(stop-immediate-propagation)

⚠️ Not implemented yet.

Calls stopImmediatePropagation.

Like stopPropagation, but additionally even stopping any further listeners on the current element in the bubbling / capturing phase to be called.

👉 Imagine it like this: stopPropagation only stops further propagation vertically, so further down the DOM (capture phase) or back up the DOM (bubble phase). stopImmediatePropagation additionally prevents any further horizontal propagation, so any further listeners on the same element will not be called.

In practice, you will probably never need this helper.

<div class="outer" {{on "click" this.onOuterClick}}>
  <button {{on "click" (stop-propagation this.onInnerClickA)}} {{on "click" this.onInnerClickB}}>
    Both my listeners get called.
  </button>
  <button {{on "click" (stop-immediate-propagation this.onInnerClickA)}} {{on "click" this.onInnerClickB}}>
    Only my first listener gets called.
  </button>
</div>

import Component from '@ember/component';
import { action } from '@ember/object';

export default class BubbleGumComponent extends Component {
  @action
  onOuterClick(event: MouseEvent) {
    console.log('outer');
  }

  @action
  onInnerClickA(event: MouseEvent) {
    console.log('inner A');
  }

  @action
  onInnerClickB(event: MouseEvent) {
    console.log('inner B');
  }
}

Clicking the first button prints:

inner A
inner B

The listeners are executed in the order they were registered in. The listener on .outer is not called, since the first listener uses (stop-propagation), so there is no bubbling.

Clicking the second button prints:

inner A

Since the first listener uses (stop-immediate-propagation), the second listener is not called. The .outer listener is also not called.

Currying / Partial Application

If you want to curry the function call / partially apply arguments, you can do so using the {{fn}} helper:

{{#each this.users as |user|}}
  <button {{on "click" (prevent-default (fn this.deleteUser user))}}>
    Delete {{user.name}}
  </button>
{{/each}}

Combining Helpers

You can nest the helpers:

<button {{on "click" (prevent-default (stop-propagation this.onClick))}}>
  Click me
</button>

Or register additional "void" helpers, since the fn argument is optional:

<button
  {{on "click" (prevent-default)}}
  {{on "click" (stop-propagation)}}
  {{on "click" this.onClick))}}
>
  Click me
</button>