include/javascript/yui/build/element-delegate/element-delegate.js

   1 /*
   2 Copyright (c) 2011, Yahoo! Inc. All rights reserved.
   3 Code licensed under the BSD License:
   4 http://developer.yahoo.com/yui/license.html
   5 version: 2.9.0
   6 */
   7 /**
   8  * Augments the Element Utility with a <code>delegate</code> method that
   9  * facilitates easy creation of delegated event listeners.  (Note: Using CSS
  10  * selectors as the filtering criteria for delegated event listeners requires
  11  * inclusion of the Selector Utility.)
  12  *
  13  * @module element-delegate
  14  * @title Element Event Delegation Module
  15  * @namespace YAHOO.util
  16  * @requires element, event-delegate
  17  */
  18
  19 (function () {
  20
  21         var Event = YAHOO.util.Event,
  22                 delegates = [],
  23                 specialTypes = {
  24                         mouseenter: true,
  25                         mouseleave: true
  26                 };
  27
  28         YAHOO.lang.augmentObject(YAHOO.util.Element.prototype, {
  29
  30             /**
  31          * Appends a delegated event listener.  Delegated event listeners
  32                  * receive two arguments by default: the DOM event and the element
  33                  * specified by the filtering function or CSS selector.
  34                  * (Note: Using the delegate method requires the element-delegate
  35                  * module.  Using CSS selectors as the filtering criteria for delegated
  36                  * event listeners requires inclusion of the Selector Utility.)
  37              * @method delegate
  38              * @param {String} type The name of the event to listen for
  39              * @param {Function} fn The handler to call when the event fires
  40                  * @param {Function|string} filter Function or CSS selector used to
  41                  * determine for what element(s) the event listener should be called.
  42                  * When a function is specified, the function should return an
  43                  * HTML element.  Using a CSS Selector requires the inclusion of the
  44                  * CSS Selector Utility.
  45              * @param {Any} obj A variable to pass to the handler
  46              * @param {Object} scope The object to use for the scope of the handler
  47          * @return {boolean} Returns true if the delegated event listener
  48                  * was added successfully
  49          * @for Element
  50              */
  51                 delegate: function (type, fn, filter, obj, overrideContext) {
  52
  53                         if (YAHOO.lang.isString(filter) && !YAHOO.util.Selector) {
  54                         return false;
  55                         }
  56
  57                         if (!Event._createDelegate) {
  58                         return false;
  59                         }
  60
  61                         var sType = Event._getType(type),
  62                                 el = this.get("element"),
  63                                 fnDelegate,
  64                                 fnMouseDelegate,
  65
  66                                 fnWrapper = function (e) {
  67
  68                                         return fnDelegate.call(el, e);
  69
  70                                 };
  71
  72                         if (specialTypes[type]) {
  73
  74                                 if (!Event._createMouseDelegate) {
  75                                 return false;
  76                                 }
  77
  78                                 fnMouseDelegate = Event._createMouseDelegate(fn, obj, overrideContext);
  79
  80                                 fnDelegate = Event._createDelegate(function (event, matchedEl, container) {
  81
  82                                         return fnMouseDelegate.call(matchedEl, event, container);
  83
  84                                 }, filter, obj, overrideContext);
  85
  86                         }
  87                         else {
  88                                 fnDelegate = Event._createDelegate(fn, filter, obj, overrideContext);
  89                         }
  90
  91
  92                         delegates.push([el, sType, fn, fnWrapper]);
  93
  94                         return this.on(sType, fnWrapper);
  95
  96                 },
  97
  98
  99             /**
 100              * Remove a delegated event listener
 101              * @method removeDelegate
 102              * @param {String} type The name of the event to listen for
 103              * @param {Function} fn The function call when the event fires
 104          * @return {boolean} Returns true if the unbind was successful, false
 105          *  otherwise.
 106          * @for Element
 107              */
 108                 removeDelegate: function (type, fn) {
 109
 110                         var sType = Event._getType(type),
 111                                 index = Event._getCacheIndex(delegates, this.get("element"), sType, fn),
 112                                 returnVal,
 113                                 cacheItem;
 114
 115                     if (index >= 0) {
 116                         cacheItem = delegates[index];
 117                     }
 118
 119                     if (cacheItem) {
 120
 121                         returnVal = this.removeListener(cacheItem[1], cacheItem[3]);
 122
 123                                 if (returnVal) {
 124                             delete delegates[index][2];
 125                             delete delegates[index][3];
 126                             delegates.splice(index, 1);
 127                                 }
 128
 129                         }
 130
 131                         return returnVal;
 132
 133                 }
 134
 135         });
 136
 137 }());
 138 YAHOO.register("element-delegate", YAHOO.util.Element, {version: "2.9.0", build: "2800"});