eventerjs v0.1.0

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