@ryanmorr/action-observer
v4.0.1
Published
Declarative event handling to capture unbound action events
Downloads
24
Maintainers
ryanmorrReadme
action-observer
Declarative event handling to capture unbound action events
Description
Action observer is a solution for capturing user triggered action events (click, submit) as they bubble up to the document element. This is most useful as a means of maintaining responsiveness pre-initialization of JavaScript heavy apps, allowing action events to be handled immediately or queued for processing once the page has finished initializing. Please refer to the blog post to read more.
Install
Download the CJS, ESM, UMD versions or install via NPM:
npm install @ryanmorr/action-observerUsage
First, you'll want to add the script to the <head> of your HTML. This is important because it must be loaded before the DOM has started to load and scripts have begun executing so that action events can be captured pre-initialization.
Next, add an action-observe attribute to any element you wish to observe events on. Adding the action-observe attribute to a form will automatically observe submit events for that form. Otherwise, click events will be observed for any other type of element. The value of the action-observe attribute is used as the reference to that element in the JavaScript API for action observer:
<!-- Observe click events -->
<a href="#" action-observe="add">Add Item</a>
<!-- Observe submit events -->
<form method="GET" action="#" action-observe="search">
<input type="search" name="search" />
<button type="submit">Submit</button>
</form>There are two different ways to approach implementation in JavaScript. The first option is to define a callback function to be called for each action event dispatched from the target element, including events dispatched before the handler was defined, allowing you to handle actions immediately:
import { observe } from '@ryanmorr/action-observer';
// Observes the element(s) with the action-observe="add" attribute
observe('add', (event, element) => {
// Handle the action immediately
});The other option is to check if an action event was dispatched on a target element once your scripts have completed initializing to address the action afterwards:
import { getActions } from '@ryanmorr/action-observer';
// Returns an array of all events dispatched from the action-observe="add" attribute
const actions = getActions('add');
actions.forEach(({event, element}) => {
// Handle each action after the fact (better late than never)
});Once your primary JavaScript has loaded, you can choose to stop observing specific elements or stop functionality entirely for all elements:
import { unobserve, disable } from '@ryanmorr/action-observer';
// Once the application code has initialized the link, stop observing
if (isInitialized('link')) {
unobserve('link');
}
// Once all initializing code is complete, disable all functionality
if (isAppLoaded()){
disable();
}License
This project is dedicated to the public domain as described by the Unlicense.