custom events on document & window

README.md

@@ -10,9 +10,10 @@ bean.add(element, 'click', function (e) {
 
 API
 ---
-Bean has four methods, each packing quite a punch.
+Bean has five methods, each packing quite a punch.
 
   * bean.<code>add()</code>
+  * bean.<code>one()</code>
   * bean.<code>remove()</code>
   * bean.<code>clone()</code>
   * bean.<code>fire()</code>
@@ -92,6 +93,10 @@ bean.fire(element, 'click.ded.fat');
 bean.remove(element, 'click.fat.ded');
 ```
 
+one()
+---
+<code>bean.one()</code> is an alias for <code>bean.add()</code> except that the handler will only be executed once and then removed for the event type(s).
+
 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)

src/bean.js

@@ -63,6 +63,10 @@
     };
   },
 
+  targetElement = function (element, isNative) {
+    return !W3C_MODEL && !isNative && (element === doc || element === win) ? root : element;
+  },
+
   addListener = function (element, orgType, fn, args) {
     var type = orgType.replace(stripName, ''),
         events = retrieveEvents(element),
@@ -86,6 +90,7 @@
         removeListener(element, type, fn) && org();
       };
     }
+    element = targetElement(element, isNative);
     element[eventSupport] && listener(element, isNative ? type : 'propertychange', fn, true, !isNative && type);
     handlers[uid] = fn;
     fn.__uid = uid;
@@ -100,6 +105,7 @@
       return element;
     }
 
+    handler && handler.__one && (handler = handler.__one)
     names = orgType.replace(namespace, '');
     uids = names ? names.split('.') : [handler.__uid];
 
@@ -112,6 +118,7 @@
       if (element[eventSupport]) {
         type = customEvents[type] ? customEvents[type].base : type;
         var isNative = W3C_MODEL || nativeEvents[type];
+        element = targetElement(element, isNative);
         listener(element, isNative ? type : 'propertychange', handler, false, !isNative && type);
       }
     }
@@ -144,21 +151,36 @@
     };
   },
 
-  add = function (element, events, fn, delfn, $) {
+  _add = function (meth, element, events, fn, delfn, $) {
     if (typeof events == 'object' && !fn) {
       for (var type in events) {
-        events.hasOwnProperty(type) && add(element, type, events[type]);
+        events.hasOwnProperty(type) && _add(meth, element, type, events[type]);
       }
     } else {
       var isDel = typeof fn == 'string', types = (isDel ? fn : events).split(' ');
-      fn = isDel ? del(events, delfn, $) : fn;
+      fn = isDel ? del(events, delfn, $) : meth == 'one' ? 
+        function(fn) {
+          var one = function() {
+            remove(element, events, one)
+            fn.apply(this, arguments)
+          }
+          return (fn.__one = one)
+        }(fn) : fn
       for (var i = types.length; i--;) {
-        addListener(element, types[i], fn, Array.prototype.slice.call(arguments, isDel ? 4 : 3));
+        addListener(element, types[i], fn, Array.prototype.slice.call(arguments, isDel ? 5 : 4));
       }
     }
     return element;
   },
 
+  add = function () {
+    return _add.apply(this, ['add'].concat(Array.prototype.slice.call(arguments, 0)))
+  },
+
+  one = function () {
+    return _add.apply(this, ['one'].concat(Array.prototype.slice.call(arguments, 0)))
+  },
+
   remove = function (element, orgEvents, fn) {
     var k, m, type, events, i,
         isString = typeof(orgEvents) == 'string',
@@ -178,9 +200,9 @@
         if (attached.hasOwnProperty(k)) {
           for (i in attached[k]) {
             for (m = names.length; m--;) {
-              attached[k].hasOwnProperty(i)
-                && new RegExp('^' + names[m] + '::\\d*(\\..*)?$').test(i)
-                && rm(element, [k, i].join('.'));
+              attached[k].hasOwnProperty(i) &&
+                new RegExp('^' + names[m] + '::\\d*(\\..*)?$').test(i) &&
+                rm(element, [k, i].join('.'));
             }
           }
         }
@@ -235,6 +257,7 @@
     evt[isNative ? 'initEvent' : 'initUIEvent'](type, true, true, win, 1);
     element.dispatchEvent(evt);
   } : function (isNative, type, element) {
+    element = targetElement(element, isNative);
     isNative ? element.fireEvent('on' + type, document.createEventObject()) : element['_on' + type]++;
   },
 
@@ -266,8 +289,8 @@
         result.clientX = e.pageX;
         result.clientY = e.pageY;
       } else if (e.clientX || e.clientY) {
-        result.clientX = e.clientX + document.body.scrollLeft + document.documentElement.scrollLeft;
-        result.clientY = e.clientY + document.body.scrollTop + document.documentElement.scrollTop;
+        result.clientX = e.clientX + doc.body.scrollLeft + root.scrollLeft;
+        result.clientY = e.clientY + doc.body.scrollTop + root.scrollTop;
       }
       overOut.test(type) && (result.relatedTarget = e.relatedTarget || e[(type == 'mouseover' ? 'from' : 'to') + 'Element']);
     }
@@ -332,7 +355,7 @@
     mousewheel: { base: /Firefox/.test(navigator.userAgent) ? 'DOMMouseScroll' : 'mousewheel' }
   };
 
-  var bean = { add: add, remove: remove, clone: clone, fire: fire };
+  var bean = { add: add, one: one, remove: remove, clone: clone, fire: fire };
 
   var clean = function (el) {
     var uid = remove(el).__uid;
@@ -358,4 +381,4 @@
 
   return bean;
 
-});
+});

src/ender.js

@@ -25,6 +25,8 @@
     listen: add,
     delegate: add,
 
+    one: integrate('one'),
+
     unbind: remove,
     unlisten: remove,
     removeListener: remove,
@@ -56,4 +58,4 @@
   }
 
   $.ender(methods, true);
-}(ender);
+}(ender);

tests/tests.js

@@ -116,6 +116,23 @@ sink('add', function (test, ok) {
     bean.add(el, 'foo', function () {ok(true, 'additional custom event listeners trigger event 2')});
   });
 
+  test('one: should only trigger handler once', 1, function() {
+    var el = document.getElementById('input')
+    bean.one(el, 'click', function() { ok(true, 'handler called exactly one time') })
+    Syn.click(el)
+    Syn.click(el)
+    Syn.click(el)
+  });
+
+  test('one: should be removable', 0, function() {
+    var el = document.getElementById('input')
+      , handler = function() { ok(false, 'handler shouldn\'t have been called') }
+    bean.one(el, 'click', handler)
+    bean.remove(el, 'click', handler)
+    Syn.click(el)
+    Syn.click(el)
+  });
+
 })
 
 sink('fire', function (test, ok) {
@@ -172,6 +189,26 @@ sink('custom', function (test, ok) {
     bean.fire(el2, 'partytime');
   });
 
+  test('custom: should be able to add, fire and remove custom events to document', 1, function () {
+    bean.remove(document);
+    bean.add(document, 'justlookatthat', function () {
+      ok(true, 'add custom events to document');
+      bean.remove(document, 'justlookatthat')
+    });
+    bean.fire(document, 'justlookatthat');
+    bean.fire(document, 'justlookatthat');
+  });
+
+  test('custom: should be able to add, fire and remove custom events to window', 1, function () {
+    bean.remove(window);
+    bean.add(window, 'spiffy', function () {
+      ok(true, 'add custom events to window');
+      bean.remove(window, 'spiffy')
+    });
+    bean.fire(window, 'spiffy');
+    bean.fire(window, 'spiffy');
+  });
+
 })
 
 sink('event object', function (test, ok) {
@@ -322,7 +359,6 @@ sink('remove', function (test, ok) {
           ok(true, 'remove all events 2');
         };
     bean.add(el, 'click.foo', handler1);
-    bean.add(el, 'click.foo', handler1);
     bean.add(el, 'keydown.foo', handler2);
     Syn.click(el);
   });
@@ -475,4 +511,4 @@ sink('namespaces', function (test, ok) {
 
 });
 
-window.onload = start;
+window.onload = start;