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 and stopPropagation
• 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)

1. 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: default false) - Initiates capture. W3 Reference

   • delegate (mixed) - Accepts a CSS selector or a function

     Signature

     function (node)

     Arguments

     1. 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.

2. 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

1. arg1 (mixed: optional) - An argument to be passed to the handler, often a mock event object should be supplied.
2. 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

1. event (event) - A DOM event object

Returns

undefined

Examples

listener({
  event: 'click',
  node: document.getElementById('foo')
}, function (event){
  listener.preventDefault(event) // cancels event
})

Notes

See MDC event.preventDefault

listener.stopPropagation

Cross-browser method to prevent bubbling (propagation) of an event.

Signature

listener.stopPropagation(event)

Arguments

1. event (event) - A DOM event object

Returns

undefined

Examples

listener({
  event: 'click',
  node: document.getElementById('foo')
}, function (event){
  listener.stopPropagation(event) // prevents bubbling
})

Notes

See MDC event.stopPropagation

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

1. event (string) - The event handler to add, i.e. 'click'
2. 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

1. 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

1. 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

1. event (string) - The event handler to add, i.e. 'click'

2. delegation (mixed) - Accepts a CSS selector or a function.

   Signature

   function (node)

   Arguments

   1. 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.

3. 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
})