Listener
A no-frills cross-browser DOM event listener with ender integration.
Features
- 0.6kb gzipped (1.2kb minified)
- Cross-browser event listeners (IE6+, and everybody else)
- Cross-browser
preventDefault
andstopPropagation
- Event delegation with or without a selector engine
- Ender bridge with wrapper prototype methods
Installation
Install with npm
$ npm install listener
... or build with ender
$ ender build listener
... or just download and include like any other script.
Method signature overview
Please see full API docs down the page
listener(params, handler)
listenerObj.attach()
listenerObj.detach()
listenerObj.fire([arg1, [argN]])
listener.preventDefault(event)
listener.stopPropagation(event)
Ender bridge
// ender methods
ender.listener(params, handler)
ender.preventDefault(event)
ender.stopPropagation(event)
// ender element wrapper prototype methods
wrap.attach(event, handler)
wrap.detach(namespace)
wrap.fire(namespace)
wrap.delegate(event, delegation, handler)
Ender Integration
When including a selector engine, include it before listener
, and then you can delegate events with a selector supported by the engine. Otherwise you can delegate with functions or a single tag selector.
The ender API is included at the end of the docs.
Tests
The tests require qunit, it's a submodule so do this before running:
$ git submodule init
$ git submodule update
And then you can open the tests/index.html
file in your browser.
Copyright / License
(c) Ryan Florence 2011, MIT License
Listener API Documentation
Listener can be built with ender, see the "Ender Bridge Documentation" at the end.
listener
Creates a new event listener object.
Note: When using a string for delegate
you should define a selector engine with listener._select = function(){...}
. If you're building with ender, build the selector engine (like qwery) before listener. The Ender API bridge assigns the listener's engine to ender's, if it's undefined, you're hosed.
Signature
listener(params, handler)
-
params
(object) - Key value pairs of parameters for the listener.-
node
(element) - A DOM element to attach the listener to. -
event
(string) - Which event to listen to, i.e. 'click'. -
capture
(boolean: defaultfalse
) - Initiates capture. W3 Reference -
delegate
(mixed) - Accepts a CSS selector or a functionSignature
function (node)
Arguments
node
(element) - The element the event is listening on
Returns Array - You must return an element collection, or array of elements you want to be matched against the event target.
-
-
handler
(function) - The event handler.
Returns
Object - A listener object.
Examples
A basic click listener
var params = {
node: document.getElementById('foo'),
event: 'click'
}
listener(params, function (){
alert('hey!')
})
Delegate with function
var params = {
node: document.getElementById('foo'),
event: 'click',
delegate: function (node){
// return a collection of elements
// only buttons will fire the handler
return node.getElementsByTagName('button')
}
}
listener(params, function (){
alert('hey!')
})
Delegate with CSS selector
listener({
node: document.getElementById('foo'),
event: 'click',
delegate: 'button' // same as above but uses the selector engine
}, function (){
alert('hey!')
})
listenerObj.attach
Attaches the listener to the element.
Signature
listenerObj.attach()
Returns
undefined
Examples
var listenerObj = listener({
node: document.getElementById('foo'),
event: 'click'
}, function (){
alert('hey!')
})
listenerObj.detach()
// click does nothing
listenerObj.attach()
// click is attached again
listenerObj.detach
Detaches the listener from the element.
Signature
listenerObj.detach()
Returns
undefined
Examples
var listenerObj = listener({
node: document.getElementById('foo'),
event: 'click'
}, function (){
alert('hey!')
})
listenerObj.detach()
// click does nothing
listenerObj.attach()
// click is attached again
listenerObj.fire
Fires the handler of a listener object.
Signature
listener.fire([arg1, [argN]])
Arguments
arg1
(mixed: optional) - An argument to be passed to the handler, often a mock event object should be supplied.argN
(mixed: optional) - Any number of arguments passed in will be applied to the handler.
Returns
undefined
Examples
var listenerObj = listener({
node: document.getElementById('foo'),
event: 'keyup'
}, function (event){
event.keyCode //> 'fake'
})
listenerObj.fire({keyCode: 'fake'})
listener.preventDefault
Cross-browser method to cancel an event without stopping further propagation of the event.
Signature
listener.preventDefault(event)
Arguments
event
(event) - A DOM event object
Returns
undefined
Examples
listener({
event: 'click',
node: document.getElementById('foo')
}, function (event){
listener.preventDefault(event) // cancels event
})
Notes
listener.stopPropagation
Cross-browser method to prevent bubbling (propagation) of an event.
Signature
listener.stopPropagation(event)
Arguments
event
(event) - A DOM event object
Returns
undefined
Examples
listener({
event: 'click',
node: document.getElementById('foo')
}, function (event){
listener.stopPropagation(event) // prevents bubbling
})
Notes
Ender Bridge Documentation
When building with ender the listener
function is returned to its previous definition and then added to the ender client-side API.
ender.listener
Identical to listener
, see docs above.
ender.preventDefault
Identical to listener.preventDefault
, see docs above.
ender.stopPropagation
Identical to listener.stopPropagation
, see docs above.
ender.prototype.attach
Attaches an event handler to each element in the wrap.
Signature
wrap.attach(event, handler)
Arguments
event
(string) - The event handler to add, i.e. 'click'handler
(function) - The event handler.
Returns
Object - the wrap
Examples
// assumes you've got a selector engine
var wrap = $('#some-el')
wrap.attach('click', function (){
// do something
})
ender.prototoype.detach
Detaches any event handlers added with a namespace from each element in the wrap.
Signature
wrap.detach(namespace)
Arguments
namespace
(string) - The namespace of events.
Returns
Object - the wrap
Examples
// assumes you've got a selector engine
var wrap = $('#some-el')
wrap.attach('click.foo', function (event){
// do something
})
wrap.attach('mouseover.foo', function (event){
// do something else
})
// later
wrap.detach('foo') // removes both listeners
ender.prototype.fire
Fires any event handlers added with a namespace for each element in the wrap.
Signature
wrap.fire(namespace)
Arguments
namespace
(string) - The namespace of events.
Returns
Object - wrap
Examples
// assumes you've got a selector engine
var wrap = $('#some-el')
wrap.attach('click.foo', function (event){
// do something
})
wrap.attach('mouseover.foo', function (event){
// do something else
})
wrap.fire('foo') // fires both listeners
ender.prototype.delegate
Delegates an event for each element in the wrapper.
Signature
wrap.delegate(event, delegation, handler)
Arguments
-
event
(string) - The event handler to add, i.e. 'click' -
delegation
(mixed) - Accepts a CSS selector or a function.Signature
function (node)
Arguments
node
(element) - The element the event is listening on
Returns Array - You must return an element collection, or array of elements you want to be matched against the event target.
-
handler
(function) - The event handler.
Returns
Object - wrap
Examples
delegate with selector
// assumes you've got a selector engine
var wrap = $('#some-el')
wrap.delegate('click', 'a', function (event, target){
// `this` and `target` are the clicked anchor tag
})
delegate with function
var delegation = function (node){
return node.getElementsByTagName('foo')
}
// assumes you've got a selector engine
var wrap = $('#some-el')
wrap.delegate('click', delegation, function (event, target){
// do stuff with the target
})