event-delegator v1.0.5
event-delegator
==================
To install :
npm install --save event-delegator
What is it?
This is a module used to delegate events in the dom for you and abstract event and dom interaction. Instead of having multiple element listeners we use only top level window listeners to reduce our dom footprint.It leverages the use of weakmaps to make it forgiving if you do not clean your event listeners as well as helping in the use of generic components via the use of stores. It also fixes the differences in srcElement and target properties on events between IE and real browsers
This is intended to be used on the browser side, and is easily browserified having only one dependancy with no subdependancies
Example
We want to have a list with multiple items and when an item is click , get its context correctly so we can use it to do ... something
var eventDelegator = require('event-delegator');
//Assuming we have a top level ul element which the li 's have as their parent
eventDelegator.add(ul,'click',function(rawEv,store)
{
if (store)
{
store.doSomething();
}
});
//create all the items in our ul
eventDelegator.addStore(li1,someComponent1);
eventDelegator.addStore(li2,someComponent2);
eventDelegator.addStore(li3,someComponent3);
eventDelegator.addStore(li4,someComponent4);
eventDelegator.addStore(li5,someComponent5);
//....
Now we can preserve some context at runtime without having 5+ different listeners for each li component
Since it leverages the idea of delegation, if one wants to stop stop the delegation bubbling , just set ev.cancelBubble = true on a eventListener, and propagation will stop
Alternatively if you want to expose a non bubbable event, you can add an event listener to that event originator, in which case it will allow the event to bubble up
eg eventDelegator.add(ul,'mouseleave',function(){});
will allow the delegator to allow bubbling of the mouseleave event, something which would usually not be capturable. Again if you dont want it to bubble, set use
eventDelegator.add(ul,'mouseleave',function(ev) { ev.cancelBubble = true });
Additionally the event delegator normalises some quirks between browsers. The target will always be at ev.srcElement even at old browsers that use target.
API
EventDelegator.add(target,eventName,listenerFunction,isGlobal)
Starts listening for the specified eventName with the listenerFunction. If isGlobal is true, then the target is no longer an html element but rather a global context. This is used so that later when removing a global listener that potentially has been added multiple times that we remove the correct one.Any object can be used as the target context.
{
target:HTMLElement|Object if global,
eventName:String,
listenerFunction:function,
isGlobal:Boolean
}
EventDelegator.remove(target,eventName,listenerFunction,isGlobal)
Stops listening for the prescribed event
EventDelegator.has(target,eventName,listenerFunction,isGlobal)
Returns a boolean whether the target has the specified listener function for the event
EventDelegator.setStore(target,store)
Stores a context on an element so we can use that context as you've seen in the aforementioned example.Anything can be used as a store. The target must be an html element though
EventDelegator.getStore(target)
Gets a store if it exists from the target