MicroEvent.js

MicroEvent.js is a event emitter library which provides the observer pattern to javascript objects. It works on node.js and browser and also supports RequireJS (AMD).

It is a fork of jeromeetienne/microevents.js with the changes of few other forks and custom changes.

Changes from original

• AMD support
• renamed bind/unbind into on/off
• on and off can be called with a space separated list of events like jQuery
• on and off can be called with a hash like jQuery
• add once method alinz
• add change method
• allow to rename methods in the mixin
• make on, off and once methods chainable feross
• fix error in off #27
• fix callback skips when off is called from another callback #10
• integrate prevent default and stop propagation patterns

Users

• jQuery QueryBuilder

You use MicroEvent in your project ? Just let me know or create a PR

How to Use It

You need a single file microevent.js. Include it in a webpage via the usual script tag.

<script src="microevent.js"></script>

To include it in a nodejs code isn't much harder

var MicroEvent = require('./microevent.js')

Now suppose you got a class Foobar, and you wish it to support the observer partern

MicroEvent.mixin(Foobar)

If needed you can rename the name of some or all methods

MicroEvent.mixin(Foobar, {
  'trigger': 'emit',
  'change': 'modify'
})

After applying the mixin the following methods are added to your class (all methods are chainable):

on

Add one or many event handlers.

// bind 'callback' to 'event'
obj.on('event', callback)

// bind 'callback' to 'event1' and 'event2'
obj.on('event1 event2', callback)

// bind 'callback1' to 'event1' and 'callback2' to 'event2'
obj.on({
  event1: callback1,
  event2: callback2
})

off

Remove one or many or all event handlers.

// remove all callbacks for 'event'
obj.off('event')

// remove 'callback' if attached to 'event'
obj.off('event', callback)

// remove all callbacks for 'event1' and 'event2'
obj.off('event1 event2')

// remove 'callback1' if attached to 'event1' and 'callback2' if attached to 'event2'
obj.off({
  event1: callback1,
  event2: callback2
})

// remove all callbacks
obj.off()

once

Same as on but the callbacks will be removed after the first invocation.

The callbacks attached once are only called by trigger and not by change.

trigger

Trigger all handlers for an event. Accept optional arguments transmitted to the callbacks.

// trigger 'event'
obj.trigger('event')

// trigger 'event' with arguments
obj.trigger('event', true, 42)

change

Works like trigger but returns a value. This is used to filter a value before display for example. All callbacks must accept at least on input value and return the modified (or not) value.

// call 'event' filters with 'Hello world' input
var newVal = obj.change('event', 'Hello world')

// call 'event' filters with 'Hello world' input and other arguments
var newVal = obj.change('event', 'Hello world', true, 42)

Advanced

MicroEvents integrates two concepts from jQuery : prevent default and stop propagation. This is done via an additional argument transmitted to each trigger and/or change callback.

Prevent default

Call preventDefault() on this additional object to "mark" the event. After calling trigger you get a reference to the Event object and test isDefaultPrevented().

obj.on('event', function(id, e) {
  if (id == 0) {
    e.preventDefault();
  }
});

var e = obj.trigger('event', id);

if (!e.isDefaultPrevented()) {
  // ...
}

Stop propagation

Call stopPropagation() on the Event object to prevent any further callbacks to be called. Works for trigger and change.

obj.on('event', function(val, e) {
  e.stopPropagation();
  return val;
});

obj.on('event', function(val, e) {
  return 'azerty';
});

var newVal = obj.change('event', '1234');
// newVal is still '1234'

Example

First we define the class which gonna use MicroEvent.js. This is a ticker, it is triggering 'tick' event every second, and add the current date as parameter

var Ticker = function(){
    var self = this;

    setInterval(function(){
        self.trigger('tick', new Date());
        console.log(self.change('hello', 'Hello'));
    }, 1000);
};

We mixin MicroEvent into Ticker and we are all set.

MicroEvent.mixin(Ticker);

Now lets actually use the Ticker Class. First, create the object.

var ticker = new Ticker();

and bind our tick event with its data parameter

ticker.on('tick', function(date) {
    console.log('notified date', date);
});

ticker.on('hello', function(str) {
    return '<b>' + str + '</b>';
});

And you will see this output:

notified date Tue, 22 Mar 2011 14:43:41 GMT
<b>Hello</b>
notified date Tue, 22 Mar 2011 14:43:42 GMT
<b>Hello</b>
...