2 Copyright (c) 2009, Yahoo! Inc. All rights reserved.
3 Code licensed under the BSD License:
4 http://developer.yahoo.net/yui/license.txt
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.)
13 * @module element-delegate
14 * @title Element Event Delegation Module
15 * @namespace YAHOO.util
16 * @requires element, event-delegate
21 var Event = YAHOO.util.Event,
28 YAHOO.lang.augmentObject(YAHOO.util.Element.prototype, {
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.)
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
51 delegate: function (type, fn, filter, obj, overrideContext) {
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");
58 if (!Event._createDelegate) {
59 YAHOO.log("Using delegate functionality requires the event-delegate module.", "error", "Element");
63 var sType = Event._getType(type),
64 el = this.get("element"),
68 fnWrapper = function (e) {
70 return fnDelegate.call(el, e);
74 if (specialTypes[type]) {
76 if (!Event._createMouseDelegate) {
77 YAHOO.log("Delegating a " + type + " event requires the event-mouseleave module.", "error", "Element");
81 fnMouseDelegate = Event._createMouseDelegate(fn, obj, overrideContext);
83 fnDelegate = Event._createDelegate(function (event, matchedEl, container) {
85 return fnMouseDelegate.call(matchedEl, event, container);
87 }, filter, obj, overrideContext);
91 fnDelegate = Event._createDelegate(fn, filter, obj, overrideContext);
95 delegates.push([el, sType, fn, fnWrapper]);
97 return this.on(sType, fnWrapper);
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
111 removeDelegate: function (type, fn) {
113 var sType = Event._getType(type),
114 index = Event._getCacheIndex(delegates, this.get("element"), sType, fn),
119 cacheItem = delegates[index];
124 returnVal = this.removeListener(cacheItem[1], cacheItem[3]);
127 delete delegates[index][2];
128 delete delegates[index][3];
129 delegates.splice(index, 1);
141 YAHOO.register("element-delegate", YAHOO.util.Element, {version: "2.8.0r4", build: "2449"});