eventhub-xxl
v2.3.0
Published
Event Hub for event-based applications
Downloads
85
Readme
Javascript Eventhub Library
This is an Event Hub for event-based applications. It facilitates event-based communication between different parts of an application (Event driven system).
To start listening for an event, register a callback for that event
import {EventHub} from 'eventhub-xxl';
const eh = new EventHub();
eh.on('login', myFunc);
Now, myFunc will be called when the login
event is triggered. To trigger an event do
eh.trigger('login', 'success');
succes
is the data passed with this event and given to myFunc
.
But there is more, event names can be namespaced
bar.foo.baz
bar.foo
is the namespace and baz
the actual event name. Now you can still do
eh.on('bar.foo.baz', myFunc);
eh.trigger('bar.foo.baz');
and it will also trigger myFunc
but namespaces will give you some extra power which is described in the Phases
section below
Event phases
If the event bar.foo
is triggered, the namespace is traversed in a so called CAPTURING
and BUBBLING
phase
| | / \
---------------| |----------------- ---------------| |-----------------
| bar | | | | bar | | |
| -----------| |----------- | | -----------| |----------- |
| |bar.foo \ / | | | |bar.foo | | | |
| ------------------------- | | ------------------------- |
| Event CAPTURING | | Event BUBBLING |
----------------------------------- -----------------------------------
First the events propagates in CAPTURING phase and then in BUBBLING phase
| | / \
-----------------| |--| |-----------------
| bar | | | | |
| -------------| |--| |----------- |
| |bar.foo \ / | | | |
| -------------------------------- |
| event model |
------------------------------------------
During these phases each callback targeted for that specific phase is executed.
Example:
eventHub.on('bar', myFunc1);
eventHub.on('bar.foo', myFunc2, {phase: EventHub.PHASES.CAPTURING}) ;
eventHub.on('bar.foo', myFunc3, {phase: EventHub.PHASES.BUBBLING}) ;
eventHub.on('bar.foo.baz', myFunc4, {phase: EventHub.EVENT_MODE.BOTH) ; // added to both phases
eventHub.on('bar.foo.baz', myFunc5) ;
eventHub.trigger('bar.foo.baz') ;
bar.foo
is the namespace and the EventHub will begin with the CAPTURING
phase, meaning it will first execute myFunc2
. Note that myFunc1
is skipped, because it does not belong to a phase! The execution order is
myFunc2 // capturing
myFunc5 // end-point
myFunc3 // bubbling
myFunc4
is not executed too, as it belongs to a phase and in the context of this trigger baz
is the event, not part of the namespace!
On and Off
As mentioned above, a callback can be registered using on
eh.on('bar.foo', myFunc);
eh.on('bar.foo', myFunc, {phase: EventHub.PHASES.CAPTURING);
eh.on('bar.foo', myFunc, {phase: EventHub.PHASES.BUBBLING);
eh.on('bar.foo', myFunc, {phase: EventHub.PHASES.BOTH);
one
is identical, but the callback is removed after it has been executed
Disable / Enable
Sometimes it might be useful to disable parts of the namespace.
eh.disable('bar.foo');
eh.trigger('bar.foo.baz'); // Only triggers: myFunc5
To enable a namespace again do
eh.enable('bar.foo')
Multiple
By default is is possible to register a callback multiple times for the same event. This can be disabled by doing
eh.allowMultiple(false);
Traverse to children
Consider the following setup
eh.on('bar', funcA, {phase: EventHub.PHASES.BOTH);
eh.on('bar.foo', funcB);
eh.on('bar.foo.baz', funcc, {phase: EventHub.PHASES.BOTH);
eh.on('bar.foo.baz.moz', funD);
With the traverse
option set
eh.trigger('bar.foo', { traverse: true });
it will trigger the following sequence of callbacks
funcA
funcB
funcD
funcA
So, this option will traverse deeper into the namespace and only triggers callbacks without a phase.
Fake it
A trigger
can be simulated, meaning no callbacks are actually triggered, added or removed
eh.fake.trigger('bar.foo.ba');
it will return the amount of callbacks triggered.
Yarn tasks
Install the dependencies as follows
$> yarn install
To build and minify
$> yarn build
To run the tests
$> yarn test
Installation
$> yarn add eventhub-xxl
and import it into your project as follows
import { EventHub } from 'eventhub-xxl';
or with ES5
var EventHub = require('eventhub-xxl').EventHub;
Run in the browser
There are a couple of ways to run this library in the browser.
a) If you use import
or require
in you project
import { EventHub } from 'eventhub-xxl';
var EventHub = require('eventhub-xxl').EventHub;
you need to browserify
it first. For es2015 use babelify
$> ./node_modules/.bin/browserify index.js -o bundle.js -t [ babelify --presets [ env ] ]
and for es5 you only need to do
$> ./node_modules/.bin/browserify index.js -o bundle.js
b) With RequireJs you have to use the UMD named module
requirejs.config({
paths: {
xxl: './node_modules/eventhub-xxl/dist/eventhub.umd.min'
}
});
requirejs(['xxl'], function(xxl) {
var EventHub = xxl.EventHub;
...
});
c) or without any loaders by simply adding a script element
<script src="./node_modules/eventhub-xxl/dist/eventhub.umd.min.js"></script>
<script>
var EventHub = xxl.EventHub;
...
</script>