EventMixer
What is this?
Just another event-emitter implementation. Nothin' special.
Features
- Manage custom events in your application easily
- Listener registration and emitter functionality can be mixed-in to existing objects
- Listener functions can
- opt-out of future notification
- stop continued propagation of an event
- request event cancellation (like 'preventDefault')
Mmm... Ok. How do I get it?
npm
npm install event-mixer --save
bower
bower install event-mixer --save
What's the Setup?
Simple.
For node
var eventMixer = ;
In a browser
// or, minified
How Does This Work?
You have an object. It needs some pub-sub functionality.
You want it to manage its own event subscriptions.
You want it (or some other object) to manage the event publishing.
var mySubber = {} myPubber = {};var mixer = eventMixer;
Now mySubber
has .on()
/.off()
methods to register/unregister listener functions, and myPubber
has a .fire()
method to trigger event notifications.
Now, we need some events
var twist = mixer mangle = mixer scratch = mixer;
At this point mySubber
has .onTwist()
, .offTwist()
, .onMangle()
, etc.
And myPubber
now has .fireTwist()
, .fireMangle()
, etc.
Also, event handlers have been returned. More on those in a sec.
Register some listeners!
mySubber;mySubber;mySubber;
So we've created events and registered some listeners.
Now we want to fire them. We can use the emitter object,
myPubber; // => dog => catmyPubber; // => mangled!myPubber; // => scratched!
or the handlers we got earlier.
twist; mangle;scratch;
--
Now, let's talk about the event listener functions.
listener(eo:object):object
As you likely noticed earlier, listener functions are passed an event object (eo
).
-
eo.target
The target object the mixer was created with. -
eo.name
The name of the event that was triggered. -
eo.data
Any additional data attached to the event. This will be data used to create the handler merged with any provided when the event was fired. Any changes made by a listener will also be available to subsequent listeners.
The listener object return value has some flags you can use.
If the listener wants to opt out of future event notifications:
return remove: true ;
If the listener wants to be the last one called for this event:
return stop: true ;
If the listener wants to stop whatever happens next (like .preventDefault()
):
return prevent: true ;
Use whatever combination of these flags you like:
return prevent: true remove: true stop: false ;
Beyond this, listener return values are ignored.
Nice. Can I Get an API Quick-Ref?
Yep. Here you go!
module
-
mixer(target:object, emitter:object):mixer
Returns an event manager object that mixes listener registration methods into target object and event trigger methods into emitter object. Both arguments are optional. -
handler(target:object, name:string, data:object):handler
Returns an event handler object that passes triggered events on to its listeners. Data provided here will be passed to each listener. (Note: Listeners are not managed as a Set so a handler can add the same listener function multiple times.)
mixer
-
create(name:string, data:object):handler
Creates a new event handler. This adds on/off methods to target object and a fire method to emitter object. -
destroy(name:string):handler
Destroys an event handler. This removes on/off methods from target object and the fire method from emitter object. -
emitter():object
Returns the emitter for this mixer. -
event(name:string):handler
Returns the named handler object. -
fire(name:string, data:object):boolean
Fires the named event. This method is also added directly to the emitter object. -
has(name:string):boolean
Returnstrue
if there is an event handler for the given name. -
names():array
Returns the names of all event handlers. -
off(name:string|array, listener:function|array):this
Removes listener(s) from named event(s). This method is also added directly to the target object. -
on(name:string|array, listener:function|array):this
Adds listener(s) to named event(s). This method is also added directly to the target object. -
target():object
Returns the target of this mixer.
handler
-
add(listener:function|array):this
Alias for.append()
. -
append(listener:function|array):this
Appends listener function(s) to end of listener list. -
at(index:number):listener
Returns the listener at the given index ornull
if not found. -
clear():this
Removes all listeners. -
count():number
Returns the number of listeners in this event handler. -
cut(index:number):listener
Removes and returns the listener at the given index ornull
if not found. -
each(callback:function):this
Filters the listener array. Each listener (and its index) is passed to 'callback' and replaced by its return value. If the callback does not return a function the listener will be omitted. -
fire(data:object):boolean
Triggers the event (with optional data). The returned boolean value indicates if the event should continue normally (true
) or not (false
). -
has(listener:function):boolean
Returnstrue
if this handler has the given listener function. -
indexOf(listener:function, start:number):number
Returns the index of given listener in the listener list or-1
if not found. Specify 'start' to begin the search at a specific index. -
prepend(listener:function|array):this
Prepends listener function(s) to beginning of listener list. -
remove(listener:function|array):this
Removes listener function(s).
target
-
off(name:string|array, listener:function|array):this
Removes listener(s) from named event handler(s). Added from mixer. -
on(name:string|array, listener:function|array):this
Adds listener(s) to named event handler(s). Added from mixer. -
offXxx(listener:function|array):this
Removes listener(s) from event handler 'Xxx'. Added viamixer.create()
. -
onXxx(listener:function|array):this
Adds listener(s) to event handler 'Xxx'. Added viamixer.create()
.
emitter
-
fire(name:string, data:object):boolean
Fires the named event. Added from mixer. -
fireXxx(data:object):boolean
Fires the event named 'Xxx'. Added viamixer.create()
.
Anything Else I Should Know?
Links
{ distrib } { updates } { feedback } { license } { versioning }
Please be sure to check 'updates' link when upgrading to a new version.
Tests
EventMixer uses Jasmine for testing and Istanbul for coverage analysis.
npm test
Finally
Don't Get Triggered! Happy Eventing!