Version 3.18.1
Show:

File: node/js/node-event.js

            /**
             * @module node
             * @submodule node-base
             */
            
            var Y_Node = Y.Node;
            var Y_NodeList = Y.NodeList;
            /**
             * List of events that route to DOM events
             * @static
             * @property DOM_EVENTS
             * @for Node
             */
            
            Y_Node.DOM_EVENTS = {
                abort: 1,
                beforeunload: 1,
                blur: 1,
                change: 1,
                click: 1,
                close: 1,
                command: 1,
                contextmenu: 1,
                copy: 1,
                cut: 1,
                dblclick: 1,
                DOMMouseScroll: 1,
                drag: 1,
                dragstart: 1,
                dragenter: 1,
                dragover: 1,
                dragleave: 1,
                dragend: 1,
                drop: 1,
                error: 1,
                focus: 1,
                key: 1,
                keydown: 1,
                keypress: 1,
                keyup: 1,
                load: 1,
                message: 1,
                mousedown: 1,
                mouseenter: 1,
                mouseleave: 1,
                mousemove: 1,
                mousemultiwheel: 1,
                mouseout: 1,
                mouseover: 1,
                mouseup: 1,
                mousewheel: 1,
                orientationchange: 1,
                paste: 1,
                reset: 1,
                resize: 1,
                select: 1,
                selectstart: 1,
                submit: 1,
                scroll: 1,
                textInput: 1,
                unload: 1,
                invalid: 1
            };
            
            // Add custom event adaptors to this list.  This will make it so
            // that delegate, key, available, contentready, etc all will
            // be available through Node.on
            Y.mix(Y_Node.DOM_EVENTS, Y.Env.evt.plugins);
            
            Y.augment(Y_Node, Y.EventTarget);
            
            Y.mix(Y_Node.prototype, {
                /**
                 * Removes event listeners from the node and (optionally) its subtree
                 * @method purge
                 * @param {Boolean} recurse (optional) Whether or not to remove listeners from the
                 * node's subtree
                 * @param {String} type (optional) Only remove listeners of the specified type
                 * @chainable
                 *
                 */
                purge: function(recurse, type) {
                    Y.Event.purgeElement(this._node, recurse, type);
                    return this;
                }
            
            });
            
            Y.mix(Y.NodeList.prototype, {
                _prepEvtArgs: function(type, fn, context) {
                    // map to Y.on/after signature (type, fn, nodes, context, arg1, arg2, etc)
                    var args = Y.Array(arguments, 0, true);
            
                    if (args.length < 2) { // type only (event hash) just add nodes
                        args[2] = this._nodes;
                    } else {
                        args.splice(2, 0, this._nodes);
                    }
            
                    args[3] = context || this; // default to NodeList instance as context
            
                    return args;
                },
            
                /**
                Subscribe a callback function for each `Node` in the collection to execute
                in response to a DOM event.
            
                NOTE: Generally, the `on()` method should be avoided on `NodeLists`, in
                favor of using event delegation from a parent Node.  See the Event user
                guide for details.
            
                Most DOM events are associated with a preventable default behavior, such as
                link clicks navigating to a new page.  Callbacks are passed a
                `DOMEventFacade` object as their first argument (usually called `e`) that
                can be used to prevent this default behavior with `e.preventDefault()`. See
                the `DOMEventFacade` API for all available properties and methods on the
                object.
            
                By default, the `this` object will be the `NodeList` that the subscription
                came from, <em>not the `Node` that received the event</em>.  Use
                `e.currentTarget` to refer to the `Node`.
            
                Returning `false` from a callback is supported as an alternative to calling
                `e.preventDefault(); e.stopPropagation();`.  However, it is recommended to
                use the event methods.
            
                @example
            
                    Y.all(".sku").on("keydown", function (e) {
                        if (e.keyCode === 13) {
                            e.preventDefault();
            
                            // Use e.currentTarget to refer to the individual Node
                            var item = Y.MyApp.searchInventory( e.currentTarget.get('value') );
                            // etc ...
                        }
                    });
            
                @method on
                @param {String} type The name of the event
                @param {Function} fn The callback to execute in response to the event
                @param {Object} [context] Override `this` object in callback
                @param {Any} [arg*] 0..n additional arguments to supply to the subscriber
                @return {EventHandle} A subscription handle capable of detaching that
                                      subscription
                @for NodeList
                **/
                on: function(type, fn, context) {
                    return Y.on.apply(Y, this._prepEvtArgs.apply(this, arguments));
                },
            
                /**
                 * Applies an one-time event listener to each Node bound to the NodeList.
                 * @method once
                 * @param {String} type The event being listened for
                 * @param {Function} fn The handler to call when the event fires
                 * @param {Object} context The context to call the handler with.
                 * Default is the NodeList instance.
                 * @return {EventHandle} A subscription handle capable of detaching that
                 *                    subscription
                 * @for NodeList
                 */
                once: function(type, fn, context) {
                    return Y.once.apply(Y, this._prepEvtArgs.apply(this, arguments));
                },
            
                /**
                 * Applies an event listener to each Node bound to the NodeList.
                 * The handler is called only after all on() handlers are called
                 * and the event is not prevented.
                 * @method after
                 * @param {String} type The event being listened for
                 * @param {Function} fn The handler to call when the event fires
                 * @param {Object} context The context to call the handler with.
                 * Default is the NodeList instance.
                 * @return {EventHandle} A subscription handle capable of detaching that
                 *                    subscription
                 * @for NodeList
                 */
                after: function(type, fn, context) {
                    return Y.after.apply(Y, this._prepEvtArgs.apply(this, arguments));
                },
            
                /**
                 * Applies an one-time event listener to each Node bound to the NodeList
                 * that will be called only after all on() handlers are called and the
                 * event is not prevented.
                 *
                 * @method onceAfter
                 * @param {String} type The event being listened for
                 * @param {Function} fn The handler to call when the event fires
                 * @param {Object} context The context to call the handler with.
                 * Default is the NodeList instance.
                 * @return {EventHandle} A subscription handle capable of detaching that
                 *                    subscription
                 * @for NodeList
                 */
                onceAfter: function(type, fn, context) {
                    return Y.onceAfter.apply(Y, this._prepEvtArgs.apply(this, arguments));
                }
            });
            
            Y_NodeList.importMethod(Y.Node.prototype, [
                /**
                  * Called on each Node instance
                  * @method detach
                  * @see Node.detach
                  * @for NodeList
                  */
                'detach',
            
                /** Called on each Node instance
                  * @method detachAll
                  * @see Node.detachAll
                  * @for NodeList
                  */
                'detachAll'
            ]);
            
            /**
            Subscribe a callback function to execute in response to a DOM event or custom
            event.
            
            Most DOM events are associated with a preventable default behavior such as
            link clicks navigating to a new page.  Callbacks are passed a `DOMEventFacade`
            object as their first argument (usually called `e`) that can be used to
            prevent this default behavior with `e.preventDefault()`. See the
            `DOMEventFacade` API for all available properties and methods on the object.
            
            If the event name passed as the first parameter is not a whitelisted DOM event,
            it will be treated as a custom event subscriptions, allowing
            `node.fire('customEventName')` later in the code.  Refer to the Event user guide
            for the full DOM event whitelist.
            
            By default, the `this` object in the callback will refer to the subscribed
            `Node`.
            
            Returning `false` from a callback is supported as an alternative to calling
            `e.preventDefault(); e.stopPropagation();`.  However, it is recommended to use
            the event methods.
            
            @example
            
                Y.one("#my-form").on("submit", function (e) {
                    e.preventDefault();
            
                    // proceed with ajax form submission instead...
                });
            
            @method on
            @param {String} type The name of the event
            @param {Function} fn The callback to execute in response to the event
            @param {Object} [context] Override `this` object in callback
            @param {Any} [arg*] 0..n additional arguments to supply to the subscriber
            @return {EventHandle} A subscription handle capable of detaching that
                                  subscription
            @for Node
            **/