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

   1 /*
   2 Copyright (c) 2009, Yahoo! Inc. All rights reserved.
   3 Code licensed under the BSD License:
   4 http://developer.yahoo.net/yui/license.txt
   5 version: 2.8.0r4
   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                                 YAHOO.log("Using a CSS selector to define the filtering criteria for a delegated listener requires the Selector Utility.", "error", "Element");
  55                         return false;
  56                         }
  57
  58                         if (!Event._createDelegate) {
  59                         YAHOO.log("Using delegate functionality requires the event-delegate module.", "error", "Element");
  60                         return false;
  61                         }
  62
  63                         var sType = Event._getType(type),
  64                                 el = this.get("element"),
  65                                 fnDelegate,
  66                                 fnMouseDelegate,
  67
  68                                 fnWrapper = function (e) {
  69
  70                                         return fnDelegate.call(el, e);
  71
  72                                 };
  73
  74                         if (specialTypes[type]) {
  75
  76                                 if (!Event._createMouseDelegate) {
  77                                 YAHOO.log("Delegating a " + type + " event requires the event-mouseleave module.", "error", "Element");
  78                                 return false;
  79                                 }
  80
  81                                 fnMouseDelegate = Event._createMouseDelegate(fn, obj, overrideContext);
  82
  83                                 fnDelegate = Event._createDelegate(function (event, matchedEl, container) {
  84
  85                                         return fnMouseDelegate.call(matchedEl, event, container);
  86
  87                                 }, filter, obj, overrideContext);
  88
  89                         }
  90                         else {
  91                                 fnDelegate = Event._createDelegate(fn, filter, obj, overrideContext);
  92                         }
  93
  94
  95                         delegates.push([el, sType, fn, fnWrapper]);
  96
  97                         return this.on(sType, fnWrapper);
  98
  99                 },
 100
 101
 102             /**
 103              * Remove a delegated event listener
 104              * @method removeDelegate
 105              * @param {String} type The name of the event to listen for
 106              * @param {Function} fn The function call when the event fires
 107          * @return {boolean} Returns true if the unbind was successful, false
 108          *  otherwise.
 109          * @for Element
 110              */
 111                 removeDelegate: function (type, fn) {
 112
 113                         var sType = Event._getType(type),
 114                                 index = Event._getCacheIndex(delegates, this.get("element"), sType, fn),
 115                                 returnVal,
 116                                 cacheItem;
 117
 118                     if (index >= 0) {
 119                         cacheItem = delegates[index];
 120                     }
 121
 122                     if (cacheItem) {
 123
 124                         returnVal = this.removeListener(cacheItem[1], cacheItem[3]);
 125
 126                                 if (returnVal) {
 127                             delete delegates[index][2];
 128                             delete delegates[index][3];
 129                             delegates.splice(index, 1);
 130                                 }
 131
 132                         }
 133
 134                         return returnVal;
 135
 136                 }
 137
 138         });
 139
 140 }());
 141 YAHOO.register("element-delegate", YAHOO.util.Element, {version: "2.8.0r4", build: "2449"});