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() 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
Optionally, event types and handlers can be passed in an object of the form { 'eventType': handler } as the second argument.
Examples
// simplebean.on(element, 'click', handler);// optional arguments passed to handlerbean.on(element, 'click', function(e, o1, o2) { console.log(o1, o2);}, 'fat', 'ded');// multiple eventsbean.on(element, 'keydown keyup', handler);// multiple handlersbean.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 eventsbean.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, [el, el2, el3], 'click', handler);bean.on(element, $('.myClass'), 'click', 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.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
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 handlersbean.off(element, 'click', handler);// remove all click handlersbean.off(element, 'click');// remove handler for all eventsbean.off(element, handler);// remove multiple eventsbean.off(element, 'mousedown mouseup');// remove all eventsbean.off(element);// remove handlers for events using object literalbean.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 typebean.clone(toElement, fromElement, 'click');
fire(element, eventType[, args ])
bean.fire() gives you the ability to trigger events.
Examples
// fire a single event on an elementbean.fire(element, 'click');// fire multiple typesbean.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 codebean.on(el, 'click', function (event) { event.stop();});// prevent all subsequent handlers from being triggered for this particular eventbean.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.
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.
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!