dom-delegate

Create and manage a DOM event delegator

Showing:

Popularity

Downloads/wk

1.6K

GitHub Stars

316

Maintenance

Last Commit

3mos ago

Contributors

31

Package

Dependencies

0

Size (min+gzip)

1.3KB

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Deprecated!
This package has been re-named 'ftdomdelegate'. Please update your dependencies to use the 'ftdomdelegate' package instead of this one.

Readme

ftdomdelegate

FT's dom delegate library is a component for binding to events on all target elements matching the given selector, irrespective of whether anything exists in the DOM at registration time or not. This allows developers to implement the event delegation pattern.

Usage

Check out how to include Origami components in your project to get started with ftdomdelegate.

JavaScript

To import ftdomdelegate:

import Delegate from 'ftdomdelegate';
let myDel = new Delegate(document.body);

To instantiate Delegate on the body and listen to some events:

function handleButtonClicks(event) {
  // Do some things
}

function handleTouchMove(event) {
  // Do some other things
}

document.addEventListener('DOMContentLoaded', function() {
  var delegate = new Delegate(document.body);
  delegate.on('click', 'button', handleButtonClicks);

  // Listen to all touch move
  // events that reach the body
  delegate.on('touchmove', handleTouchMove);
});

A cool trick to handle images that fail to load:

function handleImageFail() {
  this.style.display = 'none';
}

document.addEventListener('DOMContentLoaded', function() {
  var delegate = new Delegate(document.body);
  delegate.on('error', 'img', handleImageFail);
});

.on(eventType[, selector], handler[, useCapture])

eventType (string)

The event to listen for e.g. mousedown, mouseup, mouseout, error, click, etc.

selector (string)

Any kind of valid CSS selector supported by matchesSelector. Some selectors, like #id or tag will use optimized functions internally that check for straight matches between the ID or tag name of elements.

null is also accepted and will match the root element set by root(). Passing a handler function into .on's second argument is equivalent to .on(eventType, null, handler).

handler (function)

Function that will handle the specified event on elements matching the given selector. The function will receive two arguments: the native event object and the target element, in that order.

useCapture (boolean)

Whether or not to listen during the capturing (pass in true) or bubbling phase (pass in false). If no value passed in, it will fallback to a 'sensible default', which is true for error, blur and focus events and false for all other types.

.off([eventType][, selector][, handler][, useCapture])

Calling off with no arguments will remove all registered listeners, effectively resetting the instance.

eventType (string)

Remove handlers for events matching this type considering the other parameters.

selector (string)

Only remove listeners registered with the given selector, among the other arguments.

If null passed listeners registered to the root element will be removed. Passing in a function into off's second parameter is equivalent to .off(eventType, null, handler[, useCapture]) (the third parameter will be ignored).

handler (function)

Only remove listeners registered with the given handler function, among the other arguments. If not provided, remove all handlers.

useCapture (boolean)

Only remove listeners with useCapture set to the value passed in. If not provided, remove listeners added with useCapture set to true and false.

.root([element])

element (Node)

Set the delegate's root node. If no element passed in the root node will be deleted and the event listeners will be removed.

.destroy()

Short hand for off() and root(), ie both with no parameters. Used to reset the delegate object.

Credits and collaboration

FT DOM Delegate was developed by FT Labs, part of the Financial Times. It's now maintained by the Origami Team. The developers of ftdomdelegate were Matthew Andrews and Matthew Caruana Galizia. Test engineering by Sam Giles. The API is influenced by jQuery Live.

Migration guide

StateMajor VersionLast Minor ReleaseMigration guide
✨ active5N/Amigrate to v5
⚠ maintained44.0.6migrate to v4
⚠ maintained33.1migrate to v3
╳ deprecated22.2N/A
╳ deprecated11.0N/A

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100