xonecas.io
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)