bean

an events api for javascript

Subscribe to updates I use bean


Statistics on bean

Number of watchers on Github 1352
Number of open issues 33
Average time to close an issue about 2 months
Main language JavaScript
Average time to merge a PR 13 days
Open pull requests 6+
Closed pull requests 14+
Last commit over 3 years ago
Repo Created over 7 years ago
Repo Last Updated 9 months ago
Size 1.07 MB
Organization / Authorfat
Contributors26
Page Updated
Do you use bean? Leave a review!
View open issues (33)
View bean activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating bean for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

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.


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

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

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

// 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

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 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

Special thanks to:

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.

bean open issues Ask a question     (View All Issues)
  • over 2 years KeyboardEvent.keyIdentifier deprecated
  • over 2 years Allow bean.off to use selectors as bean.on does
  • almost 3 years Custom events doesn't bubble
  • over 3 years Events not firing in Chrome/Chromium since v42
  • over 3 years copy, cut, paste events
  • almost 4 years Cannot `one()` recursively
  • about 4 years IE8 can't fire native events on window
  • over 4 years Support matchesSelector and the like
  • over 4 years textinput event doesn't work
  • over 4 years Ender methods conflicts with Bonzo
  • almost 5 years API Documentation bug
  • almost 5 years focusin/focusout does not work in IE8
  • almost 5 years The event argument is not passed for listners attached to a JS object
  • over 5 years wrapper for using bean outside of ender
  • over 5 years Can't run tests from tests/tests.html
  • almost 6 years Fix delegation examples
  • almost 6 years Add support for Component.js (?)
  • about 6 years Normalize handler signature
  • about 6 years Add a function who checks if an event is binded
  • over 6 years Unable to pass event object when firing a native key(up|down) event
  • almost 7 years Allow capturing
  • about 7 years Ability to add additional custom events
  • about 7 years focusin/out doesn't work on FF
  • over 7 years Undelegate doesn't work as advertised
  • over 7 years Missing Support for DOM Level 2: handleEvent (Interface EventListener)
bean open pull requests (View All Pulls)
  • Add a semicolon at the end of min.bean.js
  • support being evaluated with "use strict" prefixed
  • Normalize handler signature (and test fire)
  • Change Firefox Detection Method
  • Change to check on createEvent instead of attachEvent
  • Support running inside a Web Worker
bean questions on Stackoverflow (View All Questions)
  • How to override Glassfish timeout configuration programmatically for a method or bean?
  • Spring batch : org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'scopedTarget.writer' when using JobScope
  • Singleton session bean
  • Close bootstrap modal depending on JSF Bean method return
  • Ibatis - Error creating bean with name sqlMapClient
  • Spring: Cannot autowire a Bean which extends another Bean
  • How to get externally defined bean in java config
  • Custom Bean for Authentication Policy - Conflict with obtain more parameters than just ticket - return more attributes cas jasig
  • spring bean is not created properly
  • Spring : Error creating bean
  • Spring-MVC: bean creating order
  • Convert Servlet 2.3 to Spring Boot - missing EmbeddedServletContainerFactory bean
  • org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'sessionFactory' defined in class path
  • Get hold of a JDBC Connection object from a Stateless Bean
  • Value does not update the bean property
  • org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'sessionFactory'
  • Form value not passed to Seam bean after a4j reRender
  • How does the singleton Bean serve the concurrent request?
  • Error creating bean with name 'transactionManagerPostProcessor': Initialization of bean failed
  • Spring Security config autowiring custom UserDetailsService bean
  • JSF exceptionhandler backing bean
  • Why I can't inject a Spring Environment object into my bean?
  • getResource() in ApplicationScoped bean
  • TDD approach injecting/isolating a bean when you want to have dependency package private but you are using Spring
  • Wildfly 9 Stateless session bean webservice not showing up in Web Service Endpoints
  • Session scoped CDI managed bean behaves like application scoped bean after Spring integration
  • Why do we need a bean to bean mapper like dozer in a web application
  • How to access application scoped cdi bean packed as jboss shared library
  • In spring, is there a way to autowire the first bean?
  • How to get new bean per request in spring
bean list of languages used
Other projects in JavaScript