1.0.5 • Published 9 years ago

event-delegator v1.0.5

Weekly downloads
-
License
-
Repository
github
Last release
9 years ago

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

1.0.5

9 years ago

1.0.4

9 years ago

1.0.3

9 years ago

1.0.2

9 years ago

1.0.1

9 years ago