fat/bean — Issue #55: Proposal: adopt the `on()` standard
Author: rvagg
Created: 2012-01-25 23:05:04+00:00
State: open

**This is a request for comments on a bit of API breakage**, I'd love to get feedback from Bean users on this, particularly if you use `on()`.

`on()`, as it currently exists in the Ender bridge, is incompatible with the standard set by Prototype and adopted by jQuery.

I think the emerging `on()` standard is a **good** one and we should change Bean to conform to it. At least in the Ender bridge and perhaps in Bean proper. I suspect that since most jQuery users who are using Ender are probably using `bind()` or the other traditional jQuery style methods and since Bean's `on()` is not directly compatible with jQuery's it may not be getting much use.

Prototype's `on()` [signature](http://api.prototypejs.org/dom/Event/on/) is: `.on(element, eventName[, selector], handlerFn)`

jQuery's `on()` [signature](http://api.jquery.com/on/) is: `.on(events [, selector] [, data], handlerFn)`

Unfortunately, ours is (in Ender form): `.on([selector ,] events, handlerFn)` *(note the order of `selector` and `events`)*

I propose that we change Bean to this signature: `.on(events [, selector], handlerFn)` with the possibility of adding the jQuery `data` parameter in the future (I imagine it would be quite helpful, but perhaps you should just [curry](https://github.com/ded/valentine/blob/9af5493c5c1d5eb63cad0e7fa6da9b32be27f985/src/valentine.js#L418) your handler).

This is a modified `integrate()` in the bridge that makes the change there:

```js
, integrate = function (method, type) {
var _args = type ? [type] : []
return function () {
for (var args, i = 0, l = this.length; i < l; i++) {
args = [this[i]].concat(_args, Array.prototype.slice.call(arguments, 0))
if (args.length == 4) {
args.push($)
if (method == 'on') { // 'on' puts event type first, selector second
var s = args[1]
args[1] = args[2]
args[2] = s
}
}
b[!arguments.length && method == 'add' && type ?
'fire' : method == 'on' ?
'add' : method
].apply(this, args)
}
return this
}
}

// on: integrate('on')
```

It's a bit long and I think I'd rather see `on()` added to Bean proper, perhaps even encouraged as the primary interface for adding. The signature there would look something like: `.on(element, events [,selector], handlerFn [, selectorEngine])`.

I'm not sure where this leaves `.off()` though, it's a funny API although it's consistent with having an `.on()` I guess and we already have it in the bridge. Prototype doesn't bother with `on()`, you still use `.stopObserving()`.

*Incidentally, Prototype returns a special `handler` object that has `start()` and `stop()` methods that you can use to turn on and off the listener, so you don't really need an `off()`.*