2 Copyright (c) 2010, Yahoo! Inc. All rights reserved.
3 Code licensed under the BSD License:
4 http://developer.yahoo.com/yui/license.html
8 YUI.add('event-synthetic', function(Y) {
11 * Define new DOM events that can be subscribed to from Nodes.
14 * @submodule event-synthetic
16 var DOMMap = Y.Env.evt.dom_map,
19 isObject = YLang.isObject,
20 isString = YLang.isString,
21 query = Y.Selector.query,
22 noop = function () {};
25 * <p>The triggering mechanism used by SyntheticEvents.</p>
27 * <p>Implementers should not instantiate these directly. Use the Notifier
28 * provided to the event's implemented <code>on(node, sub, notifier)</code> or
29 * <code>delegate(node, sub, notifier, filter)</code> methods.</p>
31 * @class SyntheticEvent.Notifier
33 * @param handle {EventHandle} the detach handle for the subscription to an
34 * internal custom event used to execute the callback passed to
35 * on(..) or delegate(..)
36 * @param emitFacade {Boolean} take steps to ensure the first arg received by
37 * the subscription callback is an event facade
41 function Notifier(handle, emitFacade) {
43 this.emitFacade = emitFacade;
47 * <p>Executes the subscription callback, passing the firing arguments as the
48 * first parameters to that callback. For events that are configured with
49 * emitFacade=true, it is common practice to pass the triggering DOMEventFacade
50 * as the first parameter. Barring a proper DOMEventFacade or EventFacade
51 * (from a CustomEvent), a new EventFacade will be generated. In that case, if
52 * fire() is called with a simple object, it will be mixed into the facade.
53 * Otherwise, the facade will be prepended to the callback parameters.</p>
55 * <p>For notifiers provided to delegate logic, the first argument should be an
56 * object with a "currentTarget" property to identify what object to
57 * default as 'this' in the callback. Typically this is gleaned from the
58 * DOMEventFacade or EventFacade, but if configured with emitFacade=false, an
59 * object must be provided. In that case, the object will be removed from the
60 * callback parameters.</p>
62 * <p>Additional arguments passed during event subscription will be
63 * automatically added after those passed to fire().</p>
66 * @param e {EventFacade|DOMEventFacade|Object|any} (see description)
67 * @param arg* {any} additional arguments received by all subscriptions
70 Notifier.prototype.fire = function (e) {
71 // first arg to delegate notifier should be an object with currentTarget
72 var args = toArray(arguments, 0, true),
76 thisObj = sub.context,
77 delegate = sub.filter,
80 if (this.emitFacade) {
81 if (!e || !e.preventDefault) {
82 event = ce._getFacade();
84 if (isObject(e) && !e.preventDefault) {
85 Y.mix(event, e, true);
93 event.details = args.slice();
96 event.container = ce.host;
98 } else if (delegate && isObject(e) && e.currentTarget) {
102 sub.context = thisObj || event.currentTarget || ce.host;
103 ce.fire.apply(ce, args);
104 sub.context = thisObj; // reset for future firing
109 * <p>Wrapper class for the integration of new events into the YUI event
110 * infrastructure. Don't instantiate this object directly, use
111 * <code>Y.Event.define(type, config)</code>. See that method for details.</p>
113 * <p>Properties that MAY or SHOULD be specified in the configuration are noted
114 * below and in the description of <code>Y.Event.define</code>.</p>
116 * @class SyntheticEvent
118 * @param cfg {Object} Implementation pieces and configuration
120 * @in event-synthetic
122 function SyntheticEvent() {
123 this._init.apply(this, arguments);
126 Y.mix(SyntheticEvent, {
130 * Returns the array of subscription handles for a node for the given event
131 * type. Passing true as the third argument will create a registry entry
132 * in the event system's DOM map to host the array if one doesn't yet exist.
134 * @method getRegistry
135 * @param node {Node} the node
136 * @param type {String} the event
137 * @param create {Boolean} create a registration entry to host a new array
138 * if one doesn't exist.
144 getRegistry: function (node, type, create) {
147 key = 'event:' + yuid + type + '_synth',
148 events = DOMMap[yuid] || (DOMMap[yuid] = {});
150 if (!events[key] && create) {
160 detachAll : function () {
161 var notifiers = this.notifiers,
162 i = notifiers.length;
165 notifiers[i].detach();
171 return (events[key]) ? events[key].notifiers : null;
175 * Alternate <code>_delete()</code> method for the CustomEvent object
176 * created to manage SyntheticEvent subscriptions.
179 * @param sub {Subscription} the subscription to clean up
183 _deleteSub: function (sub) {
185 var synth = this.eventDef,
186 method = (sub.filter) ? 'detachDelegate' : 'detach';
188 this.subscribers = {};
191 synth[method](sub.node, sub, this.notifier, sub.filter);
192 synth._unregisterSub(sub);
201 constructor: SyntheticEvent,
204 * Construction logic for the event.
210 var config = this.publishConfig || (this.publishConfig = {});
212 // The notification mechanism handles facade creation
213 this.emitFacade = ('emitFacade' in config) ?
216 config.emitFacade = false;
220 * <p>Implementers MAY provide this method definition.</p>
222 * <p>Implement this function if the event supports a different
223 * subscription signature. This function is used by both
224 * <code>on()</code> and <code>delegate()</code>. The second parameter
225 * indicates that the event is being subscribed via
226 * <code>delegate()</code>.</p>
228 * <p>Implementations must remove extra arguments from the args list
229 * before returning. The required args for <code>on()</code>
230 * subscriptions are</p>
231 * <pre><code>[type, callback, target, context, argN...]</code></pre>
233 * <p>The required args for <code>delegate()</code>
234 * subscriptions are</p>
236 * <pre><code>[type, callback, target, filter, context, argN...]</code></pre>
238 * <p>The return value from this function will be stored on the
239 * subscription in the '_extra' property for reference elsewhere.</p>
241 * @method processArgs
242 * @param args {Array} parmeters passed to Y.on(..) or Y.delegate(..)
243 * @param delegate {Boolean} true if the subscription is from Y.delegate
249 * <p>Implementers MAY override this property.</p>
251 * <p>Whether to prevent multiple subscriptions to this event that are
252 * classified as being the same. By default, this means the subscribed
253 * callback is the same function. See the <code>subMatch</code>
254 * method. Setting this to true will impact performance for high volume
257 * @property preventDups
261 //preventDups : false,
264 * <p>Implementers SHOULD provide this method definition.</p>
266 * Implementation logic for subscriptions done via <code>node.on(type,
267 * fn)</code> or <code>Y.on(type, fn, target)</code>. This
268 * function should set up the monitor(s) that will eventually fire the
269 * event. Typically this involves subscribing to at least one DOM
270 * event. It is recommended to store detach handles from any DOM
271 * subscriptions to make for easy cleanup in the <code>detach</code>
272 * method. Typically these handles are added to the <code>sub</code>
273 * object. Also for SyntheticEvents that leverage a single DOM
274 * subscription under the hood, it is recommended to pass the DOM event
275 * object to <code>notifier.fire(e)</code>. (The event name on the
276 * object will be updated).
279 * @param node {Node} the node the subscription is being applied to
280 * @param sub {Subscription} the object to track this subscription
281 * @param notifier {SyntheticEvent.Notifier} call notifier.fire(..) to
282 * trigger the execution of the subscribers
287 * <p>Implementers SHOULD provide this method definition.</p>
289 * <p>Implementation logic for detaching subscriptions done via
290 * <code>node.on(type, fn)</code>. This function should clean up any
291 * subscriptions made in the <code>on()</code> phase.</p>
294 * @param node {Node} the node the subscription was applied to
295 * @param sub {Subscription} the object tracking this subscription
296 * @param notifier {SyntheticEvent.Notifier} the Notifier used to
297 * trigger the execution of the subscribers
302 * <p>Implementers SHOULD provide this method definition.</p>
304 * <p>Implementation logic for subscriptions done via
305 * <code>node.delegate(type, fn, filter)</code> or
306 * <code>Y.delegate(type, fn, container, filter)</code>. Like with
307 * <code>on()</code> above, this function should monitor the environment
308 * for the event being fired, and trigger subscription execution by
309 * calling <code>notifier.fire(e)</code>.</p>
311 * <p>This function receives a fourth argument, which is the filter
312 * used to identify which Node's are of interest to the subscription.
313 * The filter will be either a boolean function that accepts a target
314 * Node for each hierarchy level as the event bubbles, or a selector
315 * string. To translate selector strings into filter functions, use
316 * <code>Y.delegate.compileFilter(filter)</code>.</p>
319 * @param node {Node} the node the subscription is being applied to
320 * @param sub {Subscription} the object to track this subscription
321 * @param notifier {SyntheticEvent.Notifier} call notifier.fire(..) to
322 * trigger the execution of the subscribers
323 * @param filter {String|Function} Selector string or function that
324 * accepts an event object and returns null, a Node, or an
325 * array of Nodes matching the criteria for processing.
331 * <p>Implementers SHOULD provide this method definition.</p>
333 * <p>Implementation logic for detaching subscriptions done via
334 * <code>node.delegate(type, fn, filter)</code> or
335 * <code>Y.delegate(type, fn, container, filter)</code>. This function
336 * should clean up any subscriptions made in the
337 * <code>delegate()</code> phase.</p>
339 * @method detachDelegate
340 * @param node {Node} the node the subscription was applied to
341 * @param sub {Subscription} the object tracking this subscription
342 * @param notifier {SyntheticEvent.Notifier} the Notifier used to
343 * trigger the execution of the subscribers
344 * @param filter {String|Function} Selector string or function that
345 * accepts an event object and returns null, a Node, or an
346 * array of Nodes matching the criteria for processing.
349 detachDelegate : noop,
352 * Sets up the boilerplate for detaching the event and facilitating the
353 * execution of subscriber callbacks.
356 * @param args {Array} array of arguments passed to
357 * <code>Y.on(...)</code> or <code>Y.delegate(...)</code>
358 * @param delegate {Boolean} true if called from
359 * <code>Y.delegate(...)</code>
360 * @return {EventHandle} the detach handle for this subscription
364 _on: function (args, delegate) {
366 extra = this.processArgs(args, delegate),
368 method = delegate ? 'delegate' : 'on',
371 // Can't just use Y.all because it doesn't support window (yet?)
372 nodes = (isString(selector)) ? query(selector) : toArray(selector);
374 if (!nodes.length && isString(selector)) {
375 handle = Y.on('available', function () {
376 Y.mix(handle, Y[method].apply(Y, args), true);
382 Y.Array.each(nodes, function (node) {
383 var subArgs = args.slice(),
390 filter = subArgs.splice(3, 1)[0];
393 // (type, fn, el, thisObj, ...) => (fn, thisObj, ...)
394 subArgs.splice(0, 4, subArgs[1], subArgs[3]);
396 if (!this.preventDups || !this.getSubs(node, args,null,true)) {
397 handle = this._getNotifier(node, subArgs, extra,filter);
399 this[method](node, handle.sub, handle.notifier, filter);
401 handles.push(handle);
406 return (handles.length === 1) ?
408 new Y.EventHandle(handles);
412 * Creates a new Notifier object for use by this event's
413 * <code>on(...)</code> or <code>delegate(...)</code> implementation.
415 * @method _getNotifier
416 * @param node {Node} the Node hosting the event
417 * @param args {Array} the subscription arguments passed to either
418 * <code>Y.on(...)</code> or <code>Y.delegate(...)</code>
419 * after running through <code>processArgs(args)</code> to
420 * normalize the argument signature
421 * @param extra {any} Extra data parsed from
422 * <code>processArgs(args)</code>
423 * @param filter {String|Function} the selector string or function
424 * filter passed to <code>Y.delegate(...)</code> (not
425 * present when called from <code>Y.on(...)</code>)
426 * @return {SyntheticEvent.Notifier}
430 _getNotifier: function (node, args, extra, filter) {
431 var dispatcher = new Y.CustomEvent(this.type, this.publishConfig),
432 handle = dispatcher.on.apply(dispatcher, args),
433 notifier = new Notifier(handle, this.emitFacade),
434 registry = SyntheticEvent.getRegistry(node, this.type, true),
437 handle.notifier = notifier;
442 this.applyArgExtras(extra, sub);
448 host : node, // I forget what this is for
449 currentTarget: node, // for generating facades
450 target : node, // for generating facades
451 el : node._node, // For category detach
453 _delete : SyntheticEvent._deleteSub
456 registry.push(handle);
462 * <p>Implementers MAY provide this method definition.</p>
464 * <p>Implement this function if you want extra data extracted during
465 * processArgs to be propagated to subscriptions on a per-node basis.
466 * That is to say, if you call <code>Y.on('xyz', fn, xtra, 'div')</code>
467 * the data returned from processArgs will be shared
468 * across the subscription objects for all the divs. If you want each
469 * subscription to receive unique information, do that processing
472 * <p>The default implementation adds the data extracted by processArgs
473 * to the subscription object as <code>sub._extra</code>.</p>
475 * @method applyArgExtras
476 * @param extra {any} Any extra data extracted from processArgs
477 * @param sub {Subscription} the individual subscription
479 applyArgExtras: function (extra, sub) {
484 * Removes the subscription from the Notifier registry.
486 * @method _unregisterSub
487 * @param sub {Subscription} the subscription
491 _unregisterSub: function (sub) {
492 var notifiers = SyntheticEvent.getRegistry(sub.node, this.type),
496 for (i = notifiers.length - 1; i >= 0; --i) {
497 if (notifiers[i].sub === sub) {
498 notifiers.splice(i, 1);
506 * Removes the subscription(s) from the internal subscription dispatch
507 * mechanism. See <code>SyntheticEvent._deleteSub</code>.
510 * @param args {Array} The arguments passed to
511 * <code>node.detach(...)</code>
515 _detach: function (args) {
516 // Can't use Y.all because it doesn't support window (yet?)
517 // TODO: Does Y.all support window now?
518 var target = args[2],
519 els = (isString(target)) ?
520 query(target) : toArray(target),
521 node, i, len, handles, j;
523 // (type, fn, el, context, filter?) => (type, fn, context, filter?)
526 for (i = 0, len = els.length; i < len; ++i) {
527 node = Y.one(els[i]);
530 handles = this.getSubs(node, args);
533 for (j = handles.length - 1; j >= 0; --j) {
542 * Returns the detach handles of subscriptions on a node that satisfy a
543 * search/filter function. By default, the filter used is the
544 * <code>subMatch</code> method.
547 * @param node {Node} the node hosting the event
548 * @param args {Array} the array of original subscription args passed
549 * to <code>Y.on(...)</code> (before
550 * <code>processArgs</code>
551 * @param filter {Function} function used to identify a subscription
552 * for inclusion in the returned array
553 * @param first {Boolean} stop after the first match (used to check for
554 * duplicate subscriptions)
555 * @return {Array} detach handles for the matching subscriptions
557 getSubs: function (node, args, filter, first) {
558 var notifiers = SyntheticEvent.getRegistry(node, this.type),
564 filter = this.subMatch;
567 for (i = 0, len = notifiers.length; i < len; ++i) {
568 handle = notifiers[i];
569 if (filter.call(this, handle.sub, args)) {
573 handles.push(notifiers[i]);
579 return handles.length && handles;
583 * <p>Implementers MAY override this to define what constitutes a
584 * "same" subscription. Override implementations should
585 * consider the lack of a comparator as a match, so calling
586 * <code>getSubs()</code> with no arguments will return all subs.</p>
588 * <p>Compares a set of subscription arguments against a Subscription
589 * object to determine if they match. The default implementation
590 * compares the callback function against the second argument passed to
591 * <code>Y.on(...)</code> or <code>node.detach(...)</code> etc.</p>
594 * @param sub {Subscription} the existing subscription
595 * @param args {Array} the calling arguments passed to
596 * <code>Y.on(...)</code> etc.
597 * @return {Boolean} true if the sub can be described by the args
601 subMatch: function (sub, args) {
602 // Default detach cares only about the callback matching
603 return !args[1] || sub.fn === args[1];
608 Y.SyntheticEvent = SyntheticEvent;
611 * <p>Defines a new event in the DOM event system. Implementers are
612 * responsible for monitoring for a scenario whereby the event is fired. A
613 * notifier object is provided to the functions identified below. When the
614 * criteria defining the event are met, call notifier.fire( [args] ); to
615 * execute event subscribers.</p>
617 * <p>The first parameter is the name of the event. The second parameter is a
618 * configuration object which define the behavior of the event system when the
619 * new event is subscribed to or detached from. The methods that should be
620 * defined in this configuration object are <code>on</code>,
621 * <code>detach</code>, <code>delegate</code>, and <code>detachDelegate</code>.
622 * You are free to define any other methods or properties needed to define your
623 * event. Be aware, however, that since the object is used to subclass
624 * SyntheticEvent, you should avoid method names used by SyntheticEvent unless
625 * your intention is to override the default behavior.</p>
627 * <p>This is a list of properties and methods that you can or should specify
628 * in the configuration object:</p>
631 * <dt><code>on</code></dt>
632 * <dd><code>function (node, subscription, notifier)</code> The
633 * implementation logic for subscription. Any special setup you need to
634 * do to create the environment for the event being fired--E.g. native
635 * DOM event subscriptions. Store subscription related objects and
636 * state on the <code>subscription</code> object. When the
637 * criteria have been met to fire the synthetic event, call
638 * <code>notifier.fire(e)</code>. See Notifier's <code>fire()</code>
639 * method for details about what to pass as parameters.</dd>
641 * <dt><code>detach</code></dt>
642 * <dd><code>function (node, subscription, notifier)</code> The
643 * implementation logic for cleaning up a detached subscription. E.g.
644 * detach any DOM subscriptions added in <code>on</code>.</dd>
646 * <dt><code>delegate</code></dt>
647 * <dd><code>function (node, subscription, notifier, filter)</code> The
648 * implementation logic for subscription via <code>Y.delegate</code> or
649 * <code>node.delegate</code>. The filter is typically either a selector
650 * string or a function. You can use
651 * <code>Y.delegate.compileFilter(selectorString)</code> to create a
652 * filter function from a selector string if needed. The filter function
653 * expects an event object as input and should output either null, a
654 * matching Node, or an array of matching Nodes. Otherwise, this acts
655 * like <code>on</code> DOM event subscriptions. Store subscription
656 * related objects and information on the <code>subscription</code>
657 * object. When the criteria have been met to fire the synthetic event,
658 * call <code>notifier.fire(e)</code> as noted above.</dd>
660 * <dt><code>detachDelegate</code></dt>
661 * <dd><code>function (node, subscription, notifier)</code> The
662 * implementation logic for cleaning up a detached delegate subscription.
663 * E.g. detach any DOM delegate subscriptions added in
664 * <code>delegate</code>.</dd>
666 * <dt><code>publishConfig</code></dt>
667 * <dd>(Object) The configuration object that will be used to instantiate
668 * the underlying CustomEvent. See Notifier's <code>fire</code> method
671 * <dt><code>processArgs</code></dt
673 * <p><code>function (argArray, fromDelegate)</code> Optional method
674 * to extract any additional arguments from the subscription
675 * signature. Using this allows <code>on</code> or
676 * <code>delegate</code> signatures like
677 * <code>node.on("hover", overCallback,
678 * outCallback)</code>.</p>
679 * <p>When processing an atypical argument signature, make sure the
680 * args array is returned to the normal signature before returning
681 * from the function. For example, in the "hover" example
682 * above, the <code>outCallback</code> needs to be <code>splice</code>d
683 * out of the array. The expected signature of the args array for
684 * <code>on()</code> subscriptions is:</p>
686 * <code>[type, callback, target, contextOverride, argN...]</code>
688 * <p>And for <code>delegate()</code>:</p>
690 * <code>[type, callback, target, filter, contextOverride, argN...]</code>
692 * <p>where <code>target</code> is the node the event is being
693 * subscribed for. You can see these signatures documented for
694 * <code>Y.on()</code> and <code>Y.delegate()</code> respectively.</p>
695 * <p>Whatever gets returned from the function will be stored on the
696 * <code>subscription</code> object under
697 * <code>subscription._extra</code>.</p></dd>
698 * <dt><code>subMatch</code></dt>
700 * <p><code>function (sub, args)</code> Compares a set of
701 * subscription arguments against a Subscription object to determine
702 * if they match. The default implementation compares the callback
703 * function against the second argument passed to
704 * <code>Y.on(...)</code> or <code>node.detach(...)</code> etc.</p>
708 * @method Event.define
709 * @param type {String} the name of the event
710 * @param config {Object} the prototype definition for the new event (see above)
711 * @param force {Boolean} override an existing event (use with caution)
713 * @return {SyntheticEvent} the subclass implementation instance created to
714 * handle event subscriptions of this type
717 * @in event-synthetic
719 Y.Event.define = function (type, config, force) {
724 var eventDef = (isObject(type)) ? type : Y.merge({ type: type }, config),
727 if (force || !Y.Node.DOM_EVENTS[eventDef.type]) {
729 SyntheticEvent.apply(this, arguments);
731 Y.extend(Impl, SyntheticEvent, eventDef);
736 Y.Node.DOM_EVENTS[type] = Y.Env.evt.plugins[type] = {
740 return synth._on(toArray(arguments));
743 delegate: function () {
744 return synth._on(toArray(arguments), true);
747 detach: function () {
748 return synth._detach(toArray(arguments));
758 }, '3.3.0' ,{requires:['node-base', 'event-custom']});