Bean

Bean is a small, fast, cross-platform, framework-agnostic event manager designed for desktop, mobile, and touch-based browsers. In its simplest form - it works like this:

bean.on(element, 'click', function (e) {
  console.log('hello');
});

Bean is included in Ender's starter pack, "The Jeesh". More details on the Ender interface below.

API

Bean has five main methods, each packing quite a punch.

• bean.on()
• bean.one()
• bean.off()
• bean.clone()
• bean.fire()

on(element, eventType[, selector], handler[, args ], [options])

bean.on() lets you attach event listeners to both elements and objects.

Arguments

• element / object (DOM Element or Object) - an HTML DOM element or any JavaScript Object
• event type(s) (String) - an event (or multiple events, space separated) to listen to
• selector (optional String) - a CSS DOM Element selector string to bind the listener to child elements matching the selector
• handler (Function) - the callback function
• args (optional) - additional arguments to pas to the callback function when triggered
• options (optional) - options, may include:
  • useCapture: set to true to pass useCapture=true to addEventListener (defaults to false)

Optionally, event types and handlers can be passed in an object of the form { 'eventType': handler } as the second argument.

Examples

// simple
bean.on(element, 'click', handler);

// register the event during capture phase instead of bubbling
bean.on(element, 'click', handler, {useCapture: true});

// optional arguments passed to handler
bean.on(element, 'click', function(e, o1, o2) {
  console.log(o1, o2);
}, 'fat', 'ded');

// multiple events
bean.on(element, 'keydown keyup', handler);

// multiple handlers
bean.on(element, {
  click: function (e) {},
  mouseover: function (e) {},
  'focus blur': function (e) {}
});

Delegation

A String as the 3rd argument to on() will be interpreted as a selector for event delegation. Events for child elements will cause the element to be checked against the selector and the event to be fired if a match is found. The event behaves the same way as if you listened directly to the element it was fired on.

// event delegated events
bean.on(element, 'click', '.content p', handler);

// Alternatively, you can pass an array of elements.
// This cuts down on selector engine work, and is a more performant means of
// delegation if you know your DOM won't be changing:
bean.on(element, 'click', [el, el2, el3], handler);
bean.on(element, 'click', $('.myClass'), handler);

Notes

• Prior to v1, Bean used add() as its primary handler-adding interface, it still exists but uses the original argument order for delegated events: add(element[, selector], eventType, handler[, args ]). This may be removed in future versions of Bean.

• The focus, blur, and submit events will not delegate due to vagaries of the DOM model. This may be addressed in a future version of Bean.

Namespacing

Bean supports namespacing your events. This makes it much easier to target the handlers later when using off() or fire(), both of these methods match namespaced handlers in the same way.

To namespace an event just add a dot followed by your unique name identifier:

bean.on(element, 'click.fat.foo', fn);  // 1
bean.on(element, 'click.ded', fn);      // 2
bean.on(element, 'click', fn);          // 3

// later:
bean.fire(element, 'click.ded');        // trigger 2
bean.fire(element, 'click.fat');        // trigger 1
bean.off(element, 'click');             // remove 1, 2 & 3

// fire() & off() match multiple namespaces with AND, not OR:
bean.fire(element, 'click.fat.foo');    // trigger 1
bean.off(element, 'click.fat.ded');     // remove nothing

Notes

• Prior to v1, Bean matched multiple namespaces in fire() and remove() calls using OR rather than AND.

one(element, eventType[, selector], handler[, args ])

bean.one() is an alias for bean.on() except that the handler will only be executed once and then removed for the event type(s).

Notes

• Prior to v1, one() used the same argument ordering as add() (see note above), it now uses the new on() ordering.

off(element[, eventType[, handler ]])

bean.off() is how you get rid of handlers once you no longer want them active. It's also a good idea to call off on elements before you remove them from your DOM; this gives Bean a chance to clean up some things and prevents memory leaks.

Arguments

• element / object (DOM Element or Object) - an HTML DOM element or any JavaScript Object
• event type(s) (optional String) - an event (or multiple events, space separated) to remove
• handler (optional Function) - the specific callback function to remove
• options (optional) - options, may include:
  • useCapture: set to true to pass useCapture=true to addEventListener (defaults to false)

Optionally, event types and handlers can be passed in an object of the form { 'eventType': handler } as the second argument, just like on().

Examples

// remove a single event handlers
bean.off(element, 'click', handler);

// remove an event handler that was added with `useCapture: true`
bean.off(element, 'click', handler, {useCapture: true});

// remove all click handlers
bean.off(element, 'click');

// remove handler for all events
bean.off(element, handler);

// remove multiple events
bean.off(element, 'mousedown mouseup');

// remove all events
bean.off(element);

// remove handlers for events using object literal
bean.off(element, { click: clickHandler, keyup: keyupHandler })

Notes

• Prior to Bean v1, remove() was the primary removal interface. This is retained as an alias for backward compatibility but may eventually be removed.

clone(destElement, srcElement[, eventType ])

bean.clone() is a method for cloning events from one DOM element or object to another.

Examples

// clone all events at once by doing this:
bean.clone(toElement, fromElement);

// clone events of a specific type
bean.clone(toElement, fromElement, 'click');

fire(element, eventType[, args ])

bean.fire() gives you the ability to trigger events.

Examples

// fire a single event on an element
bean.fire(element, 'click');

// fire multiple types
bean.fire(element, 'mousedown mouseup');

Notes

• An optional args array may be passed to fire() which will in turn be passed to the event handlers. Handlers will be triggered manually, outside of the DOM, even if you're trying to fire standard DOM events.

setSelectorEngine(selectorEngine)

bean.setSelectorEngine() allows you to set a default selector engine for all your delegation needs.

The selector engine simply needs to be a function that takes two arguments: a selector string and a root element, it should return an array of matched DOM elements. Qwery, Sel, Sizzle, NWMatcher and other selector engines should all be compatible with Bean.

Examples

bean.setSelectorEngine(qwery);

Notes

• querySelectorAll() is used as the default selector engine, this is available on most modern platforms such as mobile WebKit. To support event delegation on older browsers you will need to install a selector engine.

The Event object

Bean implements a variant of the standard DOM Event object, supplied as the argument to your DOM event handler functions. Bean wraps and fixes the native Event object where required, providing a consistent interface across browsers.

// prevent default behavior and propagation (even works on old IE)
bean.on(el, 'click', function (event) {
  event.preventDefault();
  event.stopPropagation();
});

// a simple shortcut version of the above code
bean.on(el, 'click', function (event) {
  event.stop();
});

// prevent all subsequent handlers from being triggered for this particular event
bean.on(el, 'click', function (event) {
  event.stopImmediatePropagation();
});

Notes

• Your mileage with the Event methods (preventDefault etc.) may vary with delegated events as the events are not intercepted at the element in question.

Custom events

Bean uses methods similar to Dean Edwards' event model to ensure custom events behave like real events, rather than just callbacks.

For all intents and purposes, you can just think of them as native DOM events, which will bubble up and behave you would expect.

Examples

bean.on(element, 'partytime', handler);
bean.fire(element, 'partytime');

mouseenter, mouseleave

Bean provides you with two custom DOM events, 'mouseenter' and 'mouseleave'. They are essentially just helpers for making your mouseover / mouseout lives a bit easier.

Examples

bean.on(element, 'mouseenter', enterHandler);
bean.on(element, 'mouseleave', leaveHandler);

Object support

Everything you can do in Bean with an element, you can also do with an object. This is particularly useful for working with classes or plugins.

var inst = new Klass();
bean.on(inst, 'complete', handler);

//later on...
bean.fire(inst, 'complete');

Ender Integration API

If you use Bean with Ender its API is greatly extended through its bridge file. This extension aims to give Bean the look and feel of jQuery.

Add events

• on - $(element).on('click', fn);
• addListener - $(element).addListener('click', fn);
• bind - $(element).bind('click', fn);
• listen - $(element).listen('click', fn);

Remove events

• off - $(element).off('click');
• unbind - $(element).unbind('click');
• unlisten - $(element).unlisten('click');
• removeListener - $(element).removeListener('click');

Delegate events

• on - $(element).on('click', '.foo', fn);
• delegate - $(element).delegate('.foo', 'click', fn);
• undelegate - $(element).undelegate('.foo', 'click');

Clone events

• cloneEvents - $(element).cloneEvents('.foo', fn);

Custom events

• fire / emit / trigger - $(element).trigger('click')

Special events

• hover - $(element).hover(enterfn, leavefn);
• blur - $(element).blur(fn);
• change - $(element).change(fn);
• click - $(element).click(fn);
• dblclick - $(element).dblclick(fn);
• focusin - $(element).focusin(fn);
• focusout - $(element).focusout(fn);
• keydown - $(element).keydown(fn);
• keypress - $(element).keypress(fn);
• keyup - $(element).keyup(fn);
• mousedown - $(element).mousedown(fn);
• mouseenter - $(element).mouseenter(fn);
• mouseleave - $(element).mouseleave(fn);
• mouseout - $(element).mouseout(fn);
• mouseover - $(element).mouseover(fn);
• mouseup - $(element).mouseup(fn);
• mousemove - $(element).mousemove(fn);
• resize - $(element).resize(fn);
• scroll - $(element).scroll(fn);
• select - $(element).select(fn);
• submit - $(element).submit(fn);
• unload - $(element).unload(fn);

Browser support

Bean passes our tests in all the following browsers. If you've found bugs in these browsers or others please let us know by submitting an issue on GitHub!

• IE6+
• Chrome 1+
• Safari 4+
• Firefox 3.5+
• Opera 10+

Contributing

Bean uses BusterJS for its unit tests. npm install will install Buster and other required development dependencies for you and then you can simply point your browser at bean/tests/tests.html.

A Buster configuration file also exists so you can use buster-server to run a capture server to attach multiple browsers to and then buster-test to run the tests (if you don't have Buster installed globally, you can find the executables in node_modules/.bin/).

We're more than happy to consider pull requests, however major features that have not been previously discussed may risk being rejected. Feel free to open an issue on GitHub for discussion or questions.

Contributions should stick with Bean's coding style: comma-first, semicolon-free and two-space indenting. Non-trivial contributions should come with unit tests also, feel free to ask questions if you have trouble.

Running make will assemble the bean.js file in the root of the repository. Please be aware that any contributions to bean should be in src/bean.js or they will be lost!

Contributors

• Jacob Thornton (GitHub - Twitter)
• Rod Vagg (GitHub - Twitter)
• Dustin Diaz (GitHub - Twitter)

Special thanks to:

• Dean Edwards
• Diego Perini
• The entire MooTools team

Licence & copyright

Bean is copyright © 2011-2012 Jacob Thornton and licenced under the MIT licence. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE file for more details.