receptor
Yes, it's another DOM event delegation toolkit! If you're new to event delegation, here's the gist:
Event delegation is a method for listening for events that bubble to a higher level in the DOM and applying a function only if the event's target meets some criteria (typically that it matches a given CSS selector). The primary advantage over adding event listeners to specific elements is that you don't need to know what's in the DOM to listen for events from certain elements. In other words, you can modify the DOM willy-nilly without having to juggle adding and removing "direct" event listeners whenever certain elements are added and removed.
There are lots of different tools that do delegation. The technique is even baked into jQuery, which behaves "correctly" in the sense that delegated functions match CSS selectors both for the target element and its ancestors.
Installation
Node
You can install receptor as a Node module with:
npm install receptor
In CommonJS environments, you may either require the module and access its API via the top-level export:
const receptor = require('receptor');
const click = receptor.delegate('click', 'button', function(e) {
// ...
});
...or, if you're using ES2015 and/or tree-shaking, you can import the top-level API methods directly:
import {behavior, delegateAll} from 'receptor';
// etc.
Browser
To use receptor in the browser, you can either bundle it with your CommonJS tool of choice (webpack, rollup, browserify, etc.) or grab the browser-ready build from the dist directory.
API
# receptor.delegate(selector, fn)
Returns a delegated function that only calls the fn
callback if the event target matches the given CSS selector
, or if it is contained by an element that does. The callback is called with the matching element as this
.
Why? Because many delegation tools only handle the case in which the event's target
matches the given selector, which breaks down as soon as you want to delegate to elements with children.
<button>hi</button>
<button>hi <i>there</i></button>
<script>
document.body.addEventListener(
'click',
receptor.delegate('button', function(event) {
console.log('clicked button:', this);
})
);
</script>
# receptor.delegateAll(selectors)
Returns a delegated function that treats each key in the selectors
map as a CSS selector to match a la receptor.delegate()
, and can either delegate events to multiple callbacks with matching selectors or short-circuit delegation to later selectors by returning false
:
<button>some button</button>
<button aria-controls="other">another button</button>
<script>
document.body.addEventListener(
'click',
receptor.delegateAll({
'button[aria-controls]': function(event) {
console.log('clicked controller:', this);
return false; // no other delegates will be called
},
'button': function(event) {
console.log('clicked other button:', this);
}
})
);
# receptor.ignore(element, callback)
Returns a delegated function that only calls the callback
if the event's target
isn't contained by the provided element
. This is useful for creating event handlers that only fire if the user interacts with something outside of a given UI element.
# receptor.once(callback [, options])
Returns a wrapped function that removes itself as an event listener as soon as it's called, then calls the callback
function with the same arugments. If you provide listener options, those will also be passed to removeEventListener()
.
# receptor.keymap(keys)
Returns a delegated function in which each key in the keys
object is treated as a key name or combination with modifier keys:
document.body.addEventListener('keydown', receptor.keymap({
'ArrowLeft': moveLeft,
'ArrowRight': moveRight,
'Shift+ArrowLeft': moveLeftMore,
'Shift+ArrowRight': moveRightMore
}));
In other words, this is a more declarative alternative to a single event handler with potentially messy key detection logic. Supported modifier keys are Alt, Control (or Ctrl), and Shift.
# receptor.behavior(listeners [, properties])
Returns a behavior object defined by one or more delegated listeners, which exposes add()
and remove()
methods for attaching and removing all delegates. Other properties
will be merged if provided.
Each key in listeners
should be one of either:
- One or more event types, such as
click
,keydown
, ormousedown touchstart
(multiple types are separated by spaces), in which case the value can either be a function or an object suitable forreceptor.delegateAll()
; or - A string in the form
types:delegate(selector)
, wheretypes
can be one or more event types separated with spaces, andselector
is a CSS selector.
This is the primary building block for developing rich, declarative interactions:
<button role="menubutton" aria-controls="menu">toggle menu</button>
<menu id="menu" aria-hidden="true">
<!-- stuff -->
</menu>
<script>
const MenuButton = receptor.behavior({
'click': {
'[role=menubutton]': function(event) {
let pressed = MenuButton.toggle(this);
if (pressed) {
const close = MenuButton.getCloseListener(this);
window.addEventListener('click', close);
}
}
}
}, {
toggle: function(button, pressed) {
if (typeof pressed !== 'boolean') {
pressed = button.getAttribute('aria-pressed') !== 'true';
}
button.setAttribute('aria-pressed', pressed);
MenuButton.getMenu(button).setAttribute('aria-hidden', !pressed);
return pressed;
},
getMenu: function(button) {
const id = button.getAttribute('aria-controls');
return document.getElementById(id);
},
getCloseListener: function(button) {
return receptor.ignore(button, receptor.once(function() {
MenuButton.toggle(button, false);
}));
}
});
// enable the interaction on any [role=menubutton]
MenuButton.add(document.body);
// later...
// MenuButton.remove(document.body);
</script>