Actions
Actions let you bind event listeners to an element.
Attributes and names
The data-action attribute is a space-separated list of action descriptors that defines how an element should react when an event is fired on it.
<greet-user>
<button type="button" data-action="click->greet-user#greet">...</button>
</greet-user>// elements/greet_user_element.ts
import { ImpulseElement, registerElement } from '@ambiki/impulse';
@registerElement('greet-user')
export default class GreetUserElement extends ImpulseElement {
greet(event: Event) {
//
}
}Descriptors
The data-action value click->greet-user#greet is called an action descriptor. In this descriptor:
clickis the name of the DOM event.greet-useris the name of the custom element.greetis the name of the function that should be invoked when the event is triggered.
The event name is required. There is no default event per element, so greet-user#greet is ignored.
An action is wired up by the closest ancestor (or the element itself) whose tag name matches the identifier in the descriptor — greet-user above. A data-action that names an element it is not inside of is never bound to anything.
Actions are bound once that element has initialized. An event fired before then is missed.
An action on an element inserted later is bound when Impulse's MutationObserver delivers the insertion, not at the moment of the append() call, so an event dispatched in the same synchronous run of script is missed too. Await a microtask (await Promise.resolve()) between inserting the element and dispatching the event.
Global events
You can add @window or @document to the descriptor to listen for events on the window or document respectively.
<image-gallery>
<!-- Listen for the `resize` event on the `window`. -->
<div data-action="resize@window->image-gallery#resizeLayout"></div>
</image-gallery>
<my-element>
<!-- Listen for the `mouseup` event on the `document`. -->
<div data-action="mouseup@document->my-element#invokeAction"></div>
</my-element>Event modifiers
You'll often call event.preventDefault() or event.stopPropagation() inside a handler. Declaring it in the action descriptor is clearer, so Impulse provides these modifiers out of the box.
.stop.prevent.self.capture.once.passive
<my-element>
<!-- Calls `event.stopPropagation()`. -->
<button data-action="click.stop->my-element#invokeAction"></button>
<!-- Calls `event.preventDefault()`. -->
<form data-action="submit.prevent->my-element#invokeAction"></form>
<!-- Only call the function if event.target is the element itself. -->
<div data-action="click.self->my-element#invokeAction"></div>
<!-- Modifiers can be chained. -->
<a href="#" data-action="click.stop.prevent->my-element#invokeAction"></a>
</my-element>Modifiers run in the order written, and only when the method exists. click.self.prevent calls preventDefault() only for clicks on the element itself, while click.prevent.self calls it for every click. Unknown modifiers are ignored.
The .capture, .once, and .passive modifiers mirror the DOM event listener options.
<my-element>
<div data-action="click.capture->my-element#invokeAction"></div>
<div data-action="click.once->my-element#invokeAction"></div>
<div data-action="scroll.passive->my-element#invokeAction"></div>
</my-element>Naming conventions
Always use camelCase to reference the action names.
<greet-user>
<div data-action="click->greet-user#doThis"></div>
<div data-action="click->greet-user#avoid_this"></div>
</greet-user>