tarqd / LucidJS

LucidJS is a chainable event emitter library. It offers several unique features such as set events, emitter piping, DOM node encapsulation, sub events, along with the usual event triggering and binding. LucidJS emitters also feature meta events that allow listening for event binding and event triggering. LucidJS works in both the browser and node.js.

#LucidJS

Navigation

• Set Events
• Emitter Piping
• DOM Node Augmentation
• Sub Events
• Simple Events
• Meta Events
• Documentation
  • Emitter
  • Emitter.on()
  • Emitter.off()
  • Emitter.once()
  • Emitter.trigger()
  • Emitter.set()
  • Emitter.pipe()
  • Emitter.pipe.clear()
  • Emitter.listeners()
  • Emitter.listeners.clear()

##Decouple components, make them lucid.

LucidJS is an event emitter library offering several unique features such as set events, emitter piping, DOM node Augmentation, sub events, along with the usual event triggering and binding. LucidJS emitters also feature meta events that allow listening for event binding and event triggering.

It works with AMD loaders, on NodeJS, and with the good old script tag.

###Set Events

LucidJS emitters have a method called .set(). Set allows you to bind to an event even after it has happened.

var emitter = LucidJS.emitter();
emitter.set('ready');
console.log('fired ready event');
setTimeout(function() {
	emitter.on('ready', function() {
		console.log('listener bound and executed after ready event');
	});
}, 2000);

>>> fired ready event
>>> listener bound and executed after ready event

Set is extremely useful for events that only happen once and indicate state. Its the perfect solution for load, complete or ready events.

###Emitter Piping

Sometimes its nice to have a collection of emitters and a central emitter to aggregate them. This is possible with LucidJS emitters.

var centralEmitter = LucidJS.emitter();
var emitterA = LucidJS.emitter();
var emitterB = LucidJS.emitter();
var emitterC = LucidJS.emitter();

//pipe the foo event from emitter A
centralEmitter.pipe('foo', emitterA);

//pipe the bar and baz event from emitter B
centralEmitter.pipe(['bar', 'baz'], emitterB);

//pipe all events from emitter C
centralEmitter.pipe(emitterC);

###DOM Node Augmentation

In the browser you may listen to the events emitted by DOM nodes using LucidJS's emitter API.

var button = document.getElementByID('button');
LucidJS.emitter(button);
button.on('click', function(event) {
	console.log('the button was clicked');
	event.preventDefault();
});

As a side note any object or array can be augmented by passing it into LucidJS.emitter(), the emitter constructor. DOM node event capture is just an added bonus.

###Sub Events

Ever wish you could have events with sub events? LucidJS makes this possible. Trigger an event called foo.bar.baz will trigger foo.bar.baz, foo.bar, and foo.

var emitter = LucidJS.emitter();
emitter.on('foo.bar', function() {
	console.log('foo.bar');
});
emitter.on('foo', function() {
	console.log('foo');
});
emitter.trigger('foo.bar.baz');

>>> 'foo.bar'
>>> 'foo'

###Simple Events

Along with all the tasty bits above LucidJS emitters are also very good at good old regular event passing.

var emitter = LucidJS.emitter();
emitter.on('foo', function(arg1, arg2, arg3, arg4, arg5, arg6, arg7) {
	console.log([arg1, arg2, arg3, arg4, arg5, arg6, arg7].join(' '));
});
emitter.trigger('foo', 'any', 'number', 'of', 'arguments', 'can', 'be', 'passed');

>>> 'any number of arguments can be passed'

###Meta Events

LucidJS each emitter also emits a set of meta events that let you listen for new listeners on an emitter.

var emitter = LucidJS.emitter();
emitter.on('emitter.listener', function(event, listener) {
	console.log('captured listener', listener, 'on event ' + event);
});
emitter.on('foo', function() { console.log('bar'); });

>>> 'captured listeners' function() { console.log('bar'); } 'on event foo'

You can event listen to all of the events emitted by an emitter.

var emitter = LucidJS.emitter();
emitter.on('emitter.event', function(event) {
	console.log('captured event ' + event);
});
emitter.trigger('foo');

>>> 'captured event foo'

##Documentation

LucidJS.emitter()

Creates an event emitter and returns it. If an object is passed in the object is augmented with emitter methods. If a DOM node is passed in it will also be augmented, however any DOM events emitted by the node will also be emitted by the emitter.

Arguments

LucidJS.emitter([object object]) => object emitter

Name	Description	Allowed Types
object	Optional. Any object or array you wish to turn into an emitter.	object

```javascript LucidJS.emitter([object DOMNode]) => object emitter ```

Name	Description	Allowed Types
DOMNode	Optional. Any DOM node you wish to turn into an emitter.	object

emitter{}

emitter
	on()
	once()
	trigger()
	set()
	pipe()
		clear()
	listeners()
		clear()

The emitter object is produced LucidJS.emitter. Any objects passed into LucidJS.emitter will have all of the above methods attached. The emitter object contains the API for interacting with the emitter.

binding{}

binding
	clear()

The binding object is returned by emitter.on, emitter.once, emitter.set, and emitter.pipe. Executing binding.clear() will destroy the event binding or pipe that the binding was returned from.

emitter.on()

Binds any number of listener callbacks to an event or an array of events. Whenever the given event or events are triggered or set on emitter, the listener callbacks will be executed. Any arguments passed to trigger() after the event will be passed into the listener callbacks on execution.

If any of the listener callbacks return false, the emitter.trigger or emitter.set that fired the event will return false. If the event was from a DOM node and false is returned both event.stopPropigation and event.preventDefault will be called.

emitter.on returns a binding object that can be used to modify the event binding.

Arguments

emitter.on(string event, function listener[, ...]) => object binding

Name	Description	Allowed Types
event	The name of the event that the listener will be bound to.	string
listener	A callback function that will be executed whenever the event given is triggered.	function

```javascript emitter.on(array events, function listener[, ...]) => object binding ```

Name	Description	Allowed Types
events	An array of event names the listener will be bound to.	array
listener	A callback function that will be executed whenever the event given is triggered.	function

emitter.off()

Clears any given listeners on a given event. This method has been added to allow users familar with jQuery or Backbone to get a quick start with the library. However you are encuraged to use the binding.clear() method instead.

Arguments

emitter.off(string event, function listener[, ...])

Name	Description	Allowed Types
event	The name of the event that the listeners will be removed from.	string
listener	A callback that is already bound to the event. This callback will be removed from the event.	function

emitter.once()

Binds a listener to an event. Acts exactly like emitter.on with the exception that once the given event is triggered the binding is automatically cleared. Because of this any listeners bound with emitter.once will once fire once.

emitter.once returns a binding object that can be used to modify the event binding.

Arguments

emitter.once(string event, function listener[, ...]) => object binding

Name	Description	Allowed Types
event	The name of the event that the listener will be bound to.	string
listener	A callback function that will be executed whenever the event given is triggered.	function

```javascript emitter.once(array events, function listener[, ...]) => object binding ```

Name	Description	Allowed Types
events	An array of event names the listener will be bound to.	array
listener	A callback function that will be executed whenever the event given is triggered.	function

emitter.trigger()

Triggers an event or an array of events on the emitter. Any listeners bound with emitter.on or emitter.once will be executed. Any additional arguments passed into emitter.trigger excluding the first argument; the event, will be passed to any and all listeners bound to the emitter.

If any listeners triggered explicitly return false then emitter.trigger will return false as well.

Arguments

emitter.trigger(string event, * arg[, ...]) => bool successful

Name	Description	Allowed Types
event	The name of the event that will be triggered.	string
arg	Any argument to be passed into listeners of the event.	*

```javascript emitter.trigger(array events, * arg[, ...]) => bool successful ```

Name	Description	Allowed Types
events	An array of event names that will be triggered.	array
arg	Any argument to be passed into listeners of the event.	*

emitter.set()

Works like trigger except that any listeners bound to the event or events after emitter.set is called will be fired as soon as they are bound. This is great of events that only happen once such as a load event. It prevents your listeners from missing an event because it has already fired prior to binding them.

Arguments

emitter.set(string event, * arg[, ...]) => bool successful

Name	Description	Allowed Types
event	The name of the event that will be set.	string
arg	Any argument to be passed into listeners of the event.	*

```javascript emitter.set(array events, * arg[, ...]) => bool successful ```

Name	Description	Allowed Types
events	An array of event names that will be set.	array
arg	Any argument to be passed into listeners of the event.	*

emitter.pipe()

Pipes all events or select events from one or more emitters, into another. Any events emitted by the piped emitters will also be emitted by the emitter pipe was called on. This is extremely powerful and allows you to chain your emitters. Note that you can also pass in DOM nodes as emitters.

Returns a pipe object that can be used to clear the pipe.

Arguments

emitter.pipe(object emitter[, ...]) => object pipe

Name	Description	Allowed Types
emitter	The emitter that events will be piped from.	object

```javascript emitter.pipe(string event, object emitter[, ...]) => object pipe ```

Name	Description	Allowed Types
event	The name of the event that will be piped.	string
emitter	The emitter that events will be piped from.	object

```javascript emitter.pipe(array events, object emitter[, ...]) => object pipe ```

Name	Description	Allowed Types
events	An array of event names that will be piped.	array
emitter	The emitter that events will be piped from.	object

emitter.pipe.clear()

Allows clearing all pipes, or pipes that transport select events. If an event name is given, only listeners bound to that event will be cleared. If no event name is given all bound listeners will be cleared.

Arguments

emitter.pipe.clear(string event)

Name	Description	Allowed Types
event	Optional. If any pipes are transporting this event they will be cleared.	string

emitter.listeners()

Allows access to the emitter's bound event listeners.

If an event name is given, the array of listeners bound to the named event will be returned. If no event name is given then the events will be returned. The events object contains all event arrays.

Directly editing the listeners array is not recommended, however it may be necessary to achieve certain types of functionally in specific cases.

Arguments

emitter.listeners([string event]) => object eventlisteners

Name	Description	Allowed Types
event	Optional. The name of the event to expose. The listeners bound the the event will be returned.	string

emitter.listeners.clear()

Clears listeners bound to the emitter. If an event name is given, only listeners bound to that event will be cleared. If no event name is given all bound listeners will be cleared.

Arguments

emitter.listeners.clear([string event])

Name	Description	Allowed Types
event	Optional. The name of the event to clear listeners from.	string

##A Foot Note

If you like my library feel free to use it however you want. If you wish to contribute to LucidJS please feel free to send me a pull request or make your own fork. Commentary is welcome on any of my projects.

Cheers and happy coding.