handle
v1.0.0
Published
Handle events on elements
Downloads
1,806
Readme
handle
Handle events on elements
Installation
npm install handle
API
handle(element, event, fn [, capture])
Handle event
on element
using fn
. It returns a function that can be called to stop listening. e.g. to build once
you could write:
var handle = require('handle');
function once(element, event, fn, capture) {
var dispose = handle(element, event, function (el, event) {
dispose();
fn(el, event);
}, capture);
}
Typical usage might look like:
var handle = require('handle');
handle(document.getElementById('my-button'), 'click', function (button, e) {
e.preventDefault();
// do something
});
handle(elements, event, fn [, capture])
You can handle the same event on a whole list of elements in one go. This does not need to be an array, it just needs to have a .length
property that is a number and have indexed values. e.g.
var handle = require('handle');
handle(document.querySelector('[data-action="do-something"]'), 'click', function (button, e) {
e.preventDefault();
// do something
});
It too returns a dispose
funciton.
handle(selector, event, fn [, capture])
This works just like jQuery's $(document.body).delecate(selector, event, function (e) { fn(this, e) })
. It too returns a dispose
function.
The advantages/disadvantages of using this method are:
- It will still capture the event if the element matching selector is added to the DOM after
handle
is called. - It captures the event later (i.e. after those handlers that were attached directly to elements lower in the DOM chain)
- It only binds to one element, so can have better performance, but it must check every event for a match, so can have worse performance
e.g.
var handle = require('handle');
handle('[data-action="do-something"]', 'click', function (button, e) {
e.preventDefault();
// do something
});
If you want to delegate from something other than document.body
you can select a start element via the .on
method:
var handle = require('handle').on(document.getElementById('hideable-list'));
handle('li', 'click', function (li, e) {
e.preventDefault();
li.style.visibility = 'hidden';
});
handle.once(element|elements|selector, event [, capture])
Return a promise that is resolved with the event args once the event is fired. e.preventDefault()
is also called since it must be called within the same turn to work.
Running Tests
Tests can be easilly run locally in the browser of your choice, and have passed if it ends with # ok
. They are also run on testling-ci when pushed to the repository:
npm install
npm test
License
MIT