@grrr/hansel
v2.1.0
Published
Runner of handlers/enhancers.
Downloads
82
Keywords
Readme
Hansel
Runner of JavaScript handlers and enhancers
- Lightweight (less than 1kb minified and gzipped)
- Transpile to desired browser target
- No dependencies (except a minor utility function)
Based on the article "Progressive enhancement with handlers and enhancers" by Hidde de Vries. We've been using this model for many years with great pleasure, fine-tuning here and there. Read the article for a deeper explanation.
Built with ❤️ by GRRR.
Installation
$ npm install @grrr/hansel
Note: depending on your setup additional configuration might be needed, since this package is published with untranspiled JavaScript.
Usage
Import into your main JavaScript file:
import { enhance, handle } from '@grrr/hansel';
enhance(document.documentElement, {
enhancer1(elm) {
// Enhance elements with this enhancer.
},
enhancer2(elm) { /* */ },
enhancerN(elm) { /* */ },
});
handle(document.documentElement, {
handler1(elm, event) {
// Handle clicks on elements with this handler.
},
handler2(elm, event) { /* */ },
handlerN(elm, event) { /* */ },
});
In a more modular setup, this would look like:
import { enhance, handle } from '@grrr/hansel';
import { enhancer as fooEnhancer, handler as fooHandler } from './foo';
import { enhancer as barEnhancer, handler as barHandler } from './bar';
enhance(document.documentElement, {
fooEnhancer,
barEnhancer,
});
handle(document.documentElement, {
fooHandler,
barHandler,
});
Enhancers
The enhance
function will look for DOM nodes containing the data-enhancer
attribute.
The second argument is a lookup table for enhancer functions. The value of the data-enhancer
attribute will be matched with the table and if found, executed, given the element as first argument:
// Given <p data-enhancer="foo" data-message="Hello!"></p>
enhance(document.documentElement, {
foo(elm) {
console.log(elm.getAttribute('data-message')); //=> "Hello!"
}
});
Multiple enhancers are possible by comma-separating them:
<div data-enhancer="foo,bar"></div>
Handlers
Handlers are called on click, using a global event listener on the document
.
// Given <button data-handler="shout" data-message="Hello!">shout</button>
handle(document.documentElement, {
shout(elm, e) {
alert(elm.getAttribute('data-message')); //=> "Hello!"
e.preventDefault();
}
});
Multiple handlers are possible by comma-separating them:
<a data-handler="foo,bar" href="/">Do the thing</a>
Options
It's possible to register a handler with options. To do so, register the handler via an object with an fn
and options
key:
handle(document.documentElement, {
foo(elm, e) { /* */ },
bar(elm, e) { /* */ },
baz: {
fn: baz(el, e) {
// The handler function.
},
options: {
// The handler options.
},
},
});
The following options are available:
allowModifierKeys
By default, modifier-clicks (metaKey, ctrlKey, altKey and shiftKey) on anchors (<a>
) are caught, and are not passed on to the handler. To disable this behaviour, register the handler with the allowModifierKeys
option:
options: {
allowModifierKeys: true,
},
Furthermore
Thanks to the global click listener, handlers do not have to be re-initialized to dynamically added content. The presence of a data-handler
attribute is enough.
Enhancers are run immediately however, so you might want to run them again, for instance when loading new DOM nodes in response to an AJAX call. The first argument to enhance
is the container element within which nodes are searched. Therefore, you can pass the parent to the newly created nodes as reference to enhance all its children:
const myContainer = document.querySelector('foo');
myContainer.innerHTML = htmlContainingEnhancedElements;
enhance(myContainer, myEnhancers);