142
St
startsInvasion / files
startsInvasion / libs / node_modules / bean / README.md
6.3 KB
1Bean 2---- 3Bean is a small, slick, cross-platform, framework-agnostic event utility designed for desktop, mobile, and touch-based browsers. In its simplest form - it works like this: 4 5 bean.add(element, 'click', function (e) { 6 console.log('hello'); 7 }); 8 9API 10--- 11Bean has four methods, each packing quite a punch. 12 13 * bean.<code>add()</code> 14 * bean.<code>remove()</code> 15 * bean.<code>clone()</code> 16 * bean.<code>fire()</code> 17 18add() 19--- 20<code>bean.add()</code> lets you attach event listeners to both elements and objects. 21 22<h3>Signature</h3> 23 24 * {1} element {DOM Element} an HTML DOM element 25 * {2} event type(s) {String} an event (or multiple events) to listen to 26 * {3} handler {Function} the callback function 27 28 * {2,3} handlers {Object} a list of event keys with callback functions as the values 29 30 * {4,n} optional args 31 32<h3>Examples</h3> 33 34 // simple 35 bean.add(element, 'click', handler); 36 37 // optional arguments passed to handler 38 bean.add(element, 'click', function(e, o1, o2) { 39 console.log(o1, o2); 40 }, 'fat', 'ded'); 41 42 // multiple events 43 bean.add(element, 'keydown keyup', handler); 44 45 // multiple handlers 46 bean.add(element, { 47 click: function (e) {}, 48 mouseover: function (e) {}, 49 'focus blur': function (e) {} 50 }); 51 52 // event delegated events 53 bean.add(element, '.content p', 'click', handler, queryEngine); 54 55*(note: to use event delegation with a selector, you must pass bean.add a reference to a selector engine like qwery or sizzle)* 56Developers working on Mobile Webkit applications like iPhone or Android, you may wish to simply provide the following query selector with Bean: 57 58 bean.add(element, '.content p', 'click', fn, function (selector) { 59 return document.querySelectorAll(selector); 60 }); 61 62Or alternatively, you can pass an array of elements (this actually cuts down on selector engine work, and is a more performant means of delegation if you know your DOM won't be changing: 63 64 bean.add(element, [el, el2, el3], 'click', handler); 65 //or 66 bean.add(element, $('.myClass'), 'click', handler); 67 68*(note: the focus, blur, and submit events will not delegate)* 69 70<h3>Namespacing</h3> 71Bean also now supports namespacing your events! This makes it much easier to target them down the line with things like remove or fire. To name space an event just add a dot followed by your unique name identifier: 72 73 bean.add(element, 'click.fat', fn); 74 bean.add(element, 'click.ded', fn); 75 bean.add(element, 'click', fn); 76 77 //later... 78 bean.fire(element, 'click.ded'); 79 bean.remove(element, 'click.fat'); 80 81 //alternatively you can specify mutliple remove or fire handlers at once 82 bean.fire(element, 'click.ded.fat'); 83 bean.remove(element, 'click.fat.ded'); 84 85remove() 86------ 87<code>bean.remove()</code> is how you get rid of listeners once you no longer want them. It's also a good idea to call remove on elements before you remove elements from your dom (this gives bean a chance to clean up some things and prevents memory leaks) 88 89 // remove a single event handlers 90 bean.remove(element, 'click', handler); 91 92 // remove all click handlers 93 bean.remove(element, 'click'); 94 95 // remove multiple events 96 bean.remove(element, 'mousedown mouseup'); 97 98 // remove all events 99 bean.remove(element); 100 101clone() 102----- 103<code>bean.clone()</code> is a method for cloning events from one element to another. 104 105 // clone all events at once by doing this: 106 bean.clone(toElement, fromElement); 107 108 // clone events of a specific type 109 bean.clone(toElement, fromElement, 'click'); 110 111fire() 112---- 113<code>bean.fire()</code> gives you the ability to trigger events. 114 115 // fire a single event on an element 116 bean.fire(element, 'click'); 117 118 // fire multiple types 119 bean.fire(element, 'mousedown mouseup'); 120 121 122custom events 123------------- 124Bean uses methods similar to [Dean Edward's event model](http://dean.edwards.name/weblog/2009/03/callbacks-vs-events/) to ensure custom events behave like real events, rather than just callbacks. 125 126For all intents and purposes, you can just think of them as native events, which will bubble up, and everything else you would expect... 127 128use them like this: 129 130 bean.add(element, 'partytime', handler); 131 bean.fire(element, 'partytime'); 132 133mouseenter, mouseleave 134---------------------- 135Bean provides you with two custom DOM events, <code>mouseenter</code> and <code>mouseleave</code>. They are essentially just helpers for making your mouseover/mouseout lives a bit easier. 136 137use them like regular events: 138 139 bean.add(element, 'mouseenter', handler); 140 141object support 142-------------- 143Good news, 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. 144 145 var inst = new Klass(); 146 bean.add(klass, 'complete', handler); 147 148 //later on... 149 bean.fire(inst, 'complete'); 150 151Browser Support 152--------------- 153Bean passes our tests in all the following browsers. If you've found bugs in these browsers or others please let us know! 154 155 - IE6, IE7, IE8, IE9 156 - Chrome 1-10 157 - Safari 4-5 158 - Firefox 3, 4 159 160Other important browser notes 161-------------- 162One of the great things about Bean is that it fixes a number of distinguishable browser differences and also provides proper cross-platform support for certain special events. 163 164 // normalized browser event model for default behavior and propagation 165 bean.add(el, 'click', function (e) { 166 e.preventDefault(); 167 e.stopPropagation(); 168 }); 169 170 // DOMContentLoaded 171 bean.add(document, 'DOMContentLoaded', fn); 172 173 // mousewheel 174 bean.add(el, 'mousewheel', fn); 175 176 // mobile 177 bean.add(window, 'orientationchange', fn); 178 179 // touch events 180 bean.add(el, 'touchstart touchmove touchend touchcancel', fn); 181 182 // gestures 183 bean.add(el, 'gesturestart gesturechange gestureend', fn); 184 185Building Bean 186------------- 187Bean uses [JSHint](http://www.jshint.com/) to keep some house rules as well as [UglifyJS](https://github.com/mishoo/UglifyJS) for its compression. For those interested in building Bean yourself. Run *make* in the root of the project. 188 189Tests 190----- 191point your browser at <code>bean/tests/index.html</code> 192 193Contributors 194------- 195 196 * [Dustin Diaz](https://github.com/fat/bean/commits/master?author=ded) 197 * [Jacob Thornton](https://github.com/fat/bean/commits/master?author=fat) 198 * Follow our software [@dedfat](http://twitter.com/dedfat)