eventerjs

Eventer

Eventer is meant to bring the listener/observer pattern to JS. Commonly this would be extended into the prototype of a function and used to manage eventing between objects.

Version

0.0.1

License

MIT

Dependencies

• Underscore
• jQuery

---

Usage

var MyClass = function() {};
 
// Underscore
_(MyClass.prototype).extend(Eventer);
// jQuery
$.extend(MyClass.prototype, Eventer);

API

All examples will be ran with these instaces of MyClass from above.

var myObj      = new MyClass();
var myOtherObj = new MyClass();

on

Register a callback to be executed upon trigger of an event

Parameter	Required	Type	Description
name	Yes	String	Name of the event to be executed on
callback	Yes	Function/String	Function to be executed. If string, points to local function on context parameter
context	No	Object	Context/Object the function should be ran with. Defaults to 'this'
once	No	Boolean	Indicator to remove the event entry after the first trigger

Example

myObj.on('myEvent', function() { alert("Hi"); }); // Callback will be ran with myObj as context
myObj.on('myEvent', 'alert'); // Callback will be myObj.alert with myObj as context
 
var test = { myFunc : function() { alert("Here"); } };
myObj.on('myEvent', 'myFunc', test, true); // Callback will be myFunc on test with test as context. After ran, this event entry will be deleted

Note: All of the examples above will be attached to the 'myEvent' event. When that event is triggered all events will fire that are registered.

once

Alias to register an event with once set to true

Parameter	Required	Type	Description
name	Yes	String	Name of the event to be executed on
callback	Yes	Function/String	Function to be executed. If string, points to local function on context parameter
context	No	Object	Context/Object the function should be ran with. Defaults to 'this'

Example

myObj.once('myEvent', function() { alert("Hi"); }); // Callback will be ran with myObj as context. Will be unregistered once called

listenTo

Make one object listen to another's event triggers to run a callback

Parameter	Required	Type	Description
object	Yes	Object	An object instance with Eventer mixed in
name	Yes	String	Name of the event to listen to from the object
callback	Yes	Function/String	Function to be executed
once	No	Boolean	Indicator to remove the event entry after the first trigger

Example

myObj.listenTo(myOtherObj, 'myEvent', function() { alert('Hi'); }, true);

listenToOnce

Alias to listen to another object once

Parameter	Required	Type	Description
object	Yes	Object	An object instance with Eventer mixed in
name	Yes	String	Name of the event to listen to from the object
callback	Yes	Function/String	Function to be executed

Example

myObj.listenToOnce(myOtherObj, 'myEvent', function() { alert('Hi'); });

off

Remove a registered event

Parameter	Required	Type	Description
name	No	String	Name of the event to be removed
callback	No	Function/String	Function to be removed
context	No	Object	Context/Object events to be removed
stopListening	No	Boolean	Internal use to stop endless looping - used in stopListening functionality

Note: All parameters are optional and could be utilized to remove all events that are found matching the given data. If no parameters are given, all events are removed from this object

Example

myObj.off('myEvent'); // Removes all events registered to 'myEvent'
myObj.off('myEvent', 'alert'); // Only removes the 'myEvent' event calling 'alert'
myObj.off(null, null, myObj); // Remove all events that use myObj as it's context

stopListening

Remove a registered listener

Parameter	Required	Type	Description
object	No	Object	Object being listenedTo to unregister the listeners
name	No	String	Name of the event to stop listening to
callback	No	Function/String	Function that should be no longer ran

Note: All parameters are optional and could be utilized to remove all events that are found matching the given data. If no parameters are given, all listeners are removed.

Example

myObj.stopListening(myOtherObj, 'myEvent', 'alert'); // Stop running myObj.alert on 'myEvent' event triggered from myOtherObj
myObj.stopListening(myOtherObj) // Stop listening to myOtherObj all together

proxy

Replicate a event from another object to this one

Parameter	Required	Type	Description
object	Yes	Object	Object trigering the event
name	Yes	String	Name of the event to proxy

Example

myObj.proxy(myOtherObj, 'myEvent');  // myObj will trigger 'myEvent' when myOtherObj triggers 'myEvent'

forward

Trigger an event on another object when the event is triggered locally

Parameter	Required	Type	Description
target	Yes	Object	Object to trigger the event
name	Yes	String	Name of the event to forward

Example

myObj.forward(myOtherObj, 'myEvent');  // myOtherObj will trigger 'myEvent' when myObj triggers 'myEvent'

trigger

Fires the callbacks registered to an event, utilizing all the events/listeners from the above examples.

Parameter	Required	Type	Description
defer	No	Boolean	Not required to be passed - indicates to 'defer' to the next JS 'thread' or asynchronously. Defaults to true
name	Yes	String	Name of the event to trigger

All other parameters passed will be given to the registered callbacks.

Example

myObj.trigger('myEvent');  // Executes all the callbacks registered on the 'myEvent' event on myObj
myObj.trigger('myEvent', 'test', 'things'); // Executes all the callbacks with parameters - callback('test', 'things')
myObj.trigger(false, 'myEvent'); // Exceutes callbacks for 'myEvent' inline or synchronously