[Summary view] [Print] [Text view]

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