ember-event-helpers

Complimentary template helpers to be used with the {{on}} element modifierspecified 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 Helpers
  • (prevent-default fn)
  • (stop-propagation fn)
  • (stop-immediate-propagation fn)
• Tips & Tricks
  • Currying / Partial Application
  • Combining Helpers
  • Getting the event.target.value

�� For usage information on {{on}} itself, refer to the RFC orpolyfill documentation.

Template Helpers

All three template helpers return a function that, when invoked, will call theassociated Event method on the first argument. The helper themselves also takean optional fn argument, which is a function that will be called synchronouslyafterwards with all input arguments of the returned function. The return valueof fn is passed through.

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

(prevent-default)

Calls event.preventDefault().

Prevent the user agent from performing the default action, like toggling acheckbox, 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'sthis context to the component instance. This is not required here, sincethis is not accessed, but in order to not break with patterns, we still doit here.

Using the old {{action}} modifier you wouldexpress 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 theDOM) 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 onthe current element in the bubbling / capturing phase to be called.

�� Imagine it like this: stopPropagation only stops further propagationvertically, so further down the DOM (capture phase) or back up the DOM(bubble phase). stopImmediatePropagation additionally prevents any furtherhorizontal propagation, so any further listeners on the same element willnot 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), sothere is no bubbling.

Clicking the second button prints:

inner A

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

Tips & Tricks

Currying / Partial Application

If you want to curry the function call / partially apply arguments, you can doso 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 (recommended):

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

Alternatively you could even use (queue) from ember-composable-helpers.

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

Getting the event.target.value

With the {{action}} modifier / helper, you used to be able to conveniently accessevent.target.value (or any other property thereof), like so:

<button onclick={{action this.onClick value="target.value"}}>
  Click me
</button>

You can still easily do this with (pick) from ember-composable-helpers.

<button {{on "click" (pick "target.value" this.onClick)}}>
  Click me
</button>