Skip to content

Commit

Permalink
Merge pull request fat#37 from ricardovaleriano/master
Browse files Browse the repository at this point in the history 
Just some syntax highlight on Readme.
  • Loading branch information
@fat
fat committed Nov 21, 2011
2 parents 54cc481 + 7a39f9e commit 49c6964
Showing 1 changed file with 94 additions and 72 deletions.
166 changes: 94 additions & 72 deletions README.md
View file
Expand Up @@ -2,9 +2,11 @@ Bean
----
Bean 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:

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

API
---
Expand All @@ -31,92 +33,106 @@ add()

<h3>Examples</h3>

// simple
bean.add(element, 'click', handler);
```javascript
// simple
bean.add(element, 'click', handler);

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

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

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

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

*(note: to use event delegation with a selector, you must pass bean.add a reference to a selector engine like qwery or sizzle)*
Developers working on Mobile Webkit applications like iPhone or Android, you may wish to simply provide the following query selector with Bean:

bean.add(element, '.content p', 'click', fn, function (selector) {
return document.querySelectorAll(selector);
});
```javascript
bean.add(element, '.content p', 'click', fn, function (selector) {
return document.querySelectorAll(selector);
});
```

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

bean.add(element, [el, el2, el3], 'click', handler);
//or
bean.add(element, $('.myClass'), 'click', handler);
```javascript
bean.add(element, [el, el2, el3], 'click', handler);
//or
bean.add(element, $('.myClass'), 'click', handler);
```

*(note: the focus, blur, and submit events will not delegate)*

<h3>Namespacing</h3>
Bean 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:

bean.add(element, 'click.fat', fn);
bean.add(element, 'click.ded', fn);
bean.add(element, 'click', fn);
```javascript
bean.add(element, 'click.fat', fn);
bean.add(element, 'click.ded', fn);
bean.add(element, 'click', fn);

//later...
bean.fire(element, 'click.ded');
bean.remove(element, 'click.fat');
//later...
bean.fire(element, 'click.ded');
bean.remove(element, 'click.fat');

//alternatively you can specify mutliple remove or fire handlers at once
bean.fire(element, 'click.ded.fat');
bean.remove(element, 'click.fat.ded');
//alternatively you can specify mutliple remove or fire handlers at once
bean.fire(element, 'click.ded.fat');
bean.remove(element, 'click.fat.ded');
```

remove()
------
<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)

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

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

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

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

clone()
-----
<code>bean.clone()</code> is a method for cloning events from one element to another.

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

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

fire()
----
<code>bean.fire()</code> gives you the ability to trigger events.

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

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


custom events
Expand All @@ -127,8 +143,10 @@ For all intents and purposes, you can just think of them as native events, which

use them like this:

bean.add(element, 'partytime', handler);
bean.fire(element, 'partytime');
```javascript
bean.add(element, 'partytime', handler);
bean.fire(element, 'partytime');
```

mouseenter, mouseleave
----------------------
Expand All @@ -142,11 +160,13 @@ object support
--------------
Good 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.

var inst = new Klass();
bean.add(inst, 'complete', handler);
```javascript
var inst = new Klass();
bean.add(inst, 'complete', handler);

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

Browser Support
---------------
Expand All @@ -161,26 +181,28 @@ Other important browser notes
--------------
One 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.

// normalized browser event model for default behavior and propagation
bean.add(el, 'click', function (e) {
e.preventDefault();
e.stopPropagation();
});
```javascript
// normalized browser event model for default behavior and propagation
bean.add(el, 'click', function (e) {
e.preventDefault();
e.stopPropagation();
});

// DOMContentLoaded
bean.add(document, 'DOMContentLoaded', fn);
// DOMContentLoaded
bean.add(document, 'DOMContentLoaded', fn);

// mousewheel
bean.add(el, 'mousewheel', fn);
// mousewheel
bean.add(el, 'mousewheel', fn);

// mobile
bean.add(window, 'orientationchange', fn);
// mobile
bean.add(window, 'orientationchange', fn);

// touch events
bean.add(el, 'touchstart touchmove touchend touchcancel', fn);
// touch events
bean.add(el, 'touchstart touchmove touchend touchcancel', fn);

// gestures
bean.add(el, 'gesturestart gesturechange gestureend', fn);
// gestures
bean.add(el, 'gesturestart gesturechange gestureend', fn);
```

Building Bean
-------------
Expand Down Expand Up @@ -253,4 +275,4 @@ Contributors

* [Dustin Diaz](https://github.com/fat/bean/commits/master?author=ded)
* [Jacob Thornton](https://github.com/fat/bean/commits/master?author=fat)
* Follow our software [@dedfat](http://twitter.com/dedfat)
* Follow our software [@dedfat](http://twitter.com/dedfat)

0 comments on commit 49c6964

Please sign in to comment.