ember-event-helpers
Complimentary template helpers to be used with the {{on}} element modifier
specified by RFC #471 "{{on}} modifier".
Complimentary event template helpers to the {{on}} modifier
Complimentary template helpers to be used with the {{on}} element modifier
specified by RFC #471 "{{on}} modifier".
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
👉 For usage information on
{{on}}itself, refer to the RFC or polyfill documentation.
| Template Helper | Event method |
|----------------------------------------------------------------------|----------------------------------------------------------|
| (prevent-default fn) | event.preventDefault() |
| (stop-propagation fn) | event.stopPropagation() |
| (stop-immediate-propagation fn) | stopImmediatePropagation |
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! 😅
(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
@actiondecorator is used to bind theonClickmethod'sthiscontext to the component instance. This is not required here, sincethisis 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:
stopPropagationonly stops further propagation vertically, so further down the DOM (capture phase) or back up the DOM (bubble phase).stopImmediatePropagationadditionally 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.
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}}
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>
event.target.valueWith the {{action}} modifier / helper, you used to be able to conveniently access
event.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>
Standard MoltPulse indexed agent.