event-custom-base.js revision 389a9f8339d5c537895c22b7a6b55d96d9aa6639
* <dd>Immediatly stop execution and return * <code>returnValue</code>. No other wrapping functions will be * <dt></code>Y.Do.AlterArgs(message, newArgArray)</code></dt> * <dd>Replace the arguments that the original function will be * <dt></code>Y.Do.Prevent(message)</code></dt> * <dd>Don't execute the wrapped function. Other before phase * wrappers will be executed.</dd> * @param fn {Function} the function to execute * @param obj the object hosting the method to displace * @param sFn {string} the name of the method to displace * @param c The execution context for fn * @param arg* {mixed} 0..n additional arguments to supply to the subscriber * @return {string} handle for the subscription * <p>Execute the supplied method after the specified function. Wrapping * function may optionally return an instance of the following classes to * further alter runtime behavior:</p> * <dt></code>Y.Do.Halt(message, returnValue)</code></dt> * <dd>Immediatly stop execution and return * <code>returnValue</code>. No other wrapping functions will be * <dt></code>Y.Do.AlterReturn(message, returnValue)</code></dt> * <dd>Return <code>returnValue</code> instead of the wrapped * method's original return value. This can be further altered by * other after phase wrappers.</dd> * <p>The static properties <code>Y.Do.originalRetVal</code> and * <code>Y.Do.currentRetVal</code> will be populated for reference.</p> * @param fn {Function} the function to execute * @param obj the object hosting the method to displace * @param sFn {string} the name of the method to displace * @param c The execution context for fn * @param arg* {mixed} 0..n additional arguments to supply to the subscriber * @return {string} handle for the subscription * Execute the supplied method before or after the specified function. * Used by <code>before</code> and <code>after</code>. * @param when {string} before or after * @param fn {Function} the function to execute * @param obj the object hosting the method to displace * @param sFn {string} the name of the method to displace * @param c The execution context for fn * @return {string} handle for the subscription // create a map entry for the obj if it doesn't exist // create a map entry for the method if it doesn't exist // re-route the method to our wrapper * Detach a before or after subscription. * @param handle {string} the subscription handle ////////////////////////////////////////////////////////////////////////// * Contains the return value from the wrapped method, accessible * by 'after' event listeners. * @property Do.originalRetVal * Contains the current state of the return value, consumable by * 'after' event listeners, and updated if an after subscriber * changes the return value generated by the wrapped function. * @property Do.currentRetVal ////////////////////////////////////////////////////////////////////////// * Wrapper for a displaced method with aop enabled * @param obj The object to operate on * @param sFn The name of the method to displace * Register a aop subscriber * @param sid {string} the subscriber id * @param fn {Function} the function to execute * @param when {string} when to execute the function * Unregister a aop subscriber * @param sid {string} the subscriber id * @param fn {Function} the function to execute * @param when {string} when to execute the function * <p>Execute the wrapped method. All arguments are passed into the wrapping * functions. If any of the before wrappers return an instance of * <code>Y.Do.Halt</code> or <code>Y.Do.Prevent</code>, neither the wrapped * function nor any after phase subscribers will be executed.</p> * <p>The return value will be the return value of the wrapped function or one * provided by a wrapper function via an instance of <code>Y.Do.Halt</code> or * <code>Y.Do.AlterReturn</code>. * @param arg* {any} Arguments are passed to the wrapping and wrapped functions * @return {any} Return value of wrapped function unless overwritten (see above) // execute after methods. // Stop processing if a Halt object is returned // Check for a new return value // Update the static retval state ////////////////////////////////////////////////////////////////////////// * Return an AlterArgs object when you want to change the arguments that * were passed into the function. Useful for Do.before subscribers. An * example would be a service that scrubs out illegal characters prior to * executing the core business logic. * @param msg {String} (optional) Explanation of the altered return value * @param newArgs {Array} Call parameters to be used for the original method * instead of the arguments originally passed in. * Return an AlterReturn object when you want to change the result returned * from the core method to the caller. Useful for Do.after subscribers. * @param msg {String} (optional) Explanation of the altered return value * @param newRetVal {any} Return value passed to code that invoked the wrapped * Return a Halt object when you want to terminate the execution * of all subsequent subscribers as well as the wrapped method * if it has not exectued yet. Useful for Do.before subscribers. * @param msg {String} (optional) Explanation of why the termination was done * @param retVal {any} Return value passed to code that invoked the wrapped * Return a Prevent object when you want to prevent the wrapped function * from executing, but want the remaining listeners to execute. Useful * for Do.before subscribers. * @param msg {String} (optional) Explanation of why the termination was done * Return an Error object when you want to terminate the execution * of all subsequent method calls. * @param msg {String} (optional) Explanation of the altered return value * @param retVal {any} Return value passed to code that invoked the wrapped * @deprecated use Y.Do.Halt or Y.Do.Prevent ////////////////////////////////////////////////////////////////////////// // Y["Event"] && Y.Event.addListener(window, "unload", Y.Do._unload, Y.Do); * Custom event engine, DOM event listener abstraction layer, synthetic DOM * @submodule event-custom-base // var onsubscribeType = "_event:onsub", * The CustomEvent class lets you define events for your application * that can be subscribed to by one or more independent component. * @param {String} type The type of event, which is passed to the callback * @param {object} o configuration object. // if (arguments.length > 2) { // this.log('CustomEvent context and silent are now in the config', 'warn', 'Event'); * The type of event, returned to subscribers when the event fires * The context the the event will fire from by default. Defaults to the YUI * Monitor when an event is attached or detached. // this.monitored = false; * If 0, this event does not broadcast. If 1, the YUI instance is notified * every time this event fires. If 2, the YUI instance and the YUI global * (if event is enabled on the global) are notified every time this event * By default all custom events are logged in the debug build, set silent * to true to disable debug outpu for this event. * Specifies whether this event should be queued when the host is actively * processing an event. This will effect exectution order of the callbacks * for the various events. // this.queuable = false; * The subscribers to this event * This event has fired if true * An array containing the arguments the custom event * This event should only fire one time if true, and if * it has fired, any new subscribers should be notified // this.fireOnce = false; * fireOnce listeners will fire syncronously unless async * Flag for stopPropagation that is modified during fire() * 1 means to stop propagation to bubble targets. 2 means * to also stop additional subscribers on this target. * Flag for preventDefault that is modified during fire(). * if it is not 0, the default behavior for this event * Specifies the host for this custom event. This is used * to enable event bubbling * The default function to execute after event listeners * have fire, but only if the default action was not // this.defaultFn = null; * The function to execute if a subscriber calls * stopPropagation or stopImmediatePropagation // this.stoppedFn = null; * The function to execute if a subscriber calls // this.preventedFn = null; * Specifies whether or not this event's default function * can be cancelled by a subscriber by executing preventDefault() * Specifies whether or not a subscriber can stop the event propagation * via stopPropagation(), stopImmediatePropagation(), or halt() * Events can only bubble if emitFacade is true. * Supports multiple options for listener signatures in order to // this.hasSubscribers = false; // this.hasAfters = false; * If set to true, the custom event will deliver an EventFacade object * that is similar to a DOM event object. // this.emitFacade = false; // this.log("Creating " + this.type); * Returns the number of subscribers for this event as the sum of the on() * subscribers and after() subscribers. return (
when ==
'after') ? a : s;
* Monitor the event state for the subscribed event. The first parameter * is what should be monitored, the rest are the normal parameters when * subscribing to an event. * @param what {string} what to monitor ('detach', 'attach', 'publish'). * @return {EventHandle} return value from the monitor event subscription. * Get all of the subscribers to this event and any sibling event * @return {Array} first item is the on subscribers, second the after. * Apply configuration properties. Only applies the CONFIG whitelist * @param o hash of properties to apply. * @param force {boolean} if true, properties that exist on the event * Create the Subscription for subscribing function, context, and bound * arguments. If this is a fireOnce event, the subscriber is immediately * @param fn {Function} Subscription callback * @param [context] {Object} Override `this` in the callback * @param [args] {Array} bound arguments that will be passed to the callback after the arguments generated by fire() * @param [when] {String} "after" to slot into after subscribers this.
log(
'Invalid callback for CE: ' +
this.
type);
* @param {Function} fn The function to execute. * @return {EventHandle} Unsubscribe handle. * @param {Function} fn The function to execute. * @param {object} context optional execution context. * @param {mixed} arg* 0..n additional arguments to supply to the subscriber * @return {EventHandle} An object with a detach method to detch the handler(s). * Listen for this event after the normal subscribers have been notified and * the default behavior has been applied. If a normal subscriber prevents the * default behavior, it also prevents after listeners from firing. * @param {Function} fn The function to execute. * @param {object} context optional execution context. * @param {mixed} arg* 0..n additional arguments to supply to the subscriber * @return {EventHandle} handle Unsubscribe handle. * @param {Function} fn The subscribed function to remove, if not supplied * @param {Object} context The context object passed to subscribe. * @return {int} returns the number of subscribers unsubscribed. if (s && (!
fn ||
fn === s.
fn)) {
* @param {Function} fn The subscribed function to remove, if not supplied * @param {Object} context The context object passed to subscribe. * @return {int|undefined} returns the number of subscribers unsubscribed. * @deprecated use detach. * Notify a single subscriber * @param {Subscriber} s the subscriber. * @param {Array} args the arguments array to apply to the listener. this.
log(
this.
type +
' cancelled by subscriber');
* Logger abstraction to centralize the application of the silent flag * @param {string} msg message to log. * @param {string} cat log category. * Notifies the subscribers. The callback functions will be executed * from the context specified when the event was created, and with the * <li>The type of event</li> * <li>All of the arguments fire() was executed with as an array</li> * <li>The custom object (if any) that was passed into the subscribe() * @param {Object*} arguments an arbitrary set of parameters to pass to * @return {boolean} false if one of the subscribers returned false, this.
log(
'fireOnce event: ' +
this.
type +
' already fired');
// this doesn't happen if the event isn't published // this.host._monitor('fire', this.type, args); * Set up for notifying subscribers of non-emitFacade events. * @param args {Array} Arguments passed to fire() * @return Boolean false if a subscriber returned false // this._procSubs(Y.merge(this.subscribers, this.afters), args); return this.
stopped ?
false :
true;
// Requires the event-custom-complex module for full funcitonality. * Notifies a list of subscribers. * @param subs {Array} List of subscribers * @param args {Array} Arguments passed to fire() * @return Boolean false if a subscriber returns false or stops the event * propagation via e.stopPropagation(), * e.stopImmediatePropagation(), or e.halt() * Notifies the YUI instance if the event is configured with broadcast = 1, * and both the YUI instance and Y.Global if configured with broadcast = 2. * @param args {Array} Arguments sent to fire() * @return {int} The number of listeners unsubscribed. * @deprecated use detachAll. * @return {int} The number of listeners unsubscribed. * Deletes the subscriber from the internal store of on() and after() * @param subscriber object. * Stores the subscriber information to be used when the event fires. * @param {Function} fn The wrapped function to execute. * @param {Object} context The value of the keyword 'this' in the listener. * @param {Array} args* 0..n additional arguments to supply the listener. * The callback that will be execute when the event fires * This is wrapped by Y.rbind if obj was supplied. * Optional 'this' keyword for the listener * Additional arguments to propagate to the subscriber * Custom events for a given fire transaction. * This listener only reacts to the event once * Executes the subscriber. * @param args {Array} Arguments array for the subscriber. * @param ce {CustomEvent} The custom event that sent the notification. // only catch errors if we will not re-throw them. * Returns true if the fn and obj match this objects properties. * Used by the unsubscribe method to match the right subscriber. * @param {Function} fn the function to execute. * @param {Object} context optional 'this' keyword for the listener. * @return {boolean} true if the supplied arguments match this * subscriber's signature. * Return value from all subscribe operations * @param {CustomEvent} evt the custom event. * @param {Subscriber} sub the subscriber. Y.
Array.
each(
this.
evt,
function(h) {
* Detaches this subscriber * @return {int} the number of detached listeners * Monitor the event state for the subscribed event. The first parameter * is what should be monitored, the rest are the normal parameters when * subscribing to an event. * @param what {string} what to monitor ('attach', 'detach', 'publish'). * @return {EventHandle} return value from the monitor event subscription. * Custom event engine, DOM event listener abstraction layer, synthetic DOM * @submodule event-custom-base * EventTarget provides the implementation for any object to * publish, subscribe and fire to custom events, and also * alows other EventTargets to target the object with events * sourced from the other object. * EventTarget is designed to be used with Y.augment to wrap * EventCustom in an interface that allows events to be listened to * and fired by name. This makes it possible for implementing code to * subscribe to an event that either has not been created yet, or will * @param opts a configuration object * @config emitFacade {boolean} if true, all events will emit event * facade payloads by default (default false) * @config prefix {string} the prefix to apply to non-prefixed event names * @config chain {boolean} if true, on/after/detach return the host to allow * chaining, otherwise they return an EventHandle (default false) * If the instance has a prefix attribute and the * event type is not prefixed, the instance prefix is * applied to the supplied type. * Returns an array with the detach key (if provided), * and the prefixed event name from _getType * Y.on('detachcategory| menu:click', fn) // detach category, full type with instance prefix, is this an after listener, short type * Listen to a custom event hosted by this object one time. * This is the equivalent to <code>on</code> except the * listener is immediatelly detached when it is executed. * @param type {string} The type of the event * @param fn {Function} The callback * @param context {object} optional execution context. * @param arg* {mixed} 0..n additional arguments to supply to the subscriber * @return the event target or a detach handle per 'chain' config * Listen to a custom event hosted by this object one time. * This is the equivalent to <code>after</code> except the * listener is immediatelly detached when it is executed. * @param type {string} The type of the event * @param fn {Function} The callback * @param context {object} optional execution context. * @param arg* {mixed} 0..n additional arguments to supply to the subscriber * @return the event target or a detach handle per 'chain' config * Takes the type parameter passed to 'on' and parses out the * various pieces that could be included in the type. If the * event type is passed without a prefix, it will be expanded * to include the prefix one is supplied or the event target * is configured with a default prefix. * @param {string} type the type * @return {Array} an array containing: * * the detach category, if supplied, * * the prefixed event type, * * whether or not this is an after listener, * * the supplied event type * For Nodes and NodeLists, subscribe to a DOM event or custom event. * For other subclasses, this subscribes only to custom events. * DOM event subscribers or subscribers to custom events that are published * to emit an EventFacade can call `e.preventDefault()` to prevent any * default behavior associated with that event. `e.stopPropagation()` will * stop such events from bubbling, and `e.halt()` will do both. * Subscribers may alternatively return `false` instead of calling * `e.halt()`. It is recommended to use the event methods rather than * @param type {string} The type of the event * @param fn {Function} The callback * @param context {object} optional execution context. * @param arg* {mixed} 0..n additional arguments to supply to the subscriber * @return the event target or a detach handle per 'chain' config // full name, args, detachcategory, after // extra redirection so we catch adaptor events too. take a look at this. // Captures both DOM events and event plugins. // check for the existance of an event adaptor * Detach one or more listeners the from the specified event * @param type {string|Object} Either the handle to the subscriber or the * type of event. If the type * is not specified, it will attempt to remove * the listener from all hosted events. * @param fn {Function} The subscribed function to unsubscribe, if not * supplied, all subscribers will be removed. * @param context {Object} The custom object passed to subscribe. This is * optional, but if supplied will be used to * disambiguate multiple listeners that are the same * (e.g., you subscribe many object using a function * that lives on the prototype) * @return {EventTarget} the host // detachAll disabled on the Y instance. if (!
type && (
this !== Y)) {
// If this is an event handle, use it to detach // extra redirection so we catch adaptor events too. take a look at this. // The YUI instance handles DOM events and adaptors // use the adaptor specific detach code if * Removes all listeners from the specified event. If the event type * is not specified, all listeners from all hosted custom events will * @param type {string} The type, or name of the event * Removes all listeners from the specified event. If the event type * is not specified, all listeners from all hosted custom events will * @param type {string} The type, or name of the event * @deprecated use detachAll * Creates a new custom event of the specified type. If a custom event * by that name already exists, it will not be re-created. In either * case the custom event is returned. * @param type {string} the type, or name of the event * @param opts {object} optional config params. Valid properties are: * 'broadcast': whether or not the YUI instance and YUI global are notified when the event is fired (false) * 'bubbles': whether or not this event bubbles (true) * Events can only bubble if emitFacade is true. * 'context': the default execution context for the listeners (this) * 'defaultFn': the default function to execute when this event fires if preventDefault was not called * 'emitFacade': whether or not this event emits a facade (false) * 'prefix': the prefix for this targets events, e.g., 'menu' in 'menu:click' * 'fireOnce': if an event is configured to fire once, new subscribers after * the fire will be notified immediately. * 'async': fireOnce event listeners will fire synchronously if the event has already * fired unless async is true. * 'preventable': whether or not preventDefault() has an effect (true) * 'preventedFn': a function that is executed when preventDefault is called * 'queuable': whether or not this event can be queued during bubbling (false) * 'silent': if silent is true, debug messages are not provided for this event. * 'stoppedFn': a function that is executed when stopPropagation is called * 'monitored': specifies whether or not this event should send notifications about * when the event has been attached, detached, or published. * 'type': the event type (valid option if not provided as the first parameter to publish) * @return {CustomEvent} the custom event // ce.log("publish applying new config to published event: '"+type+"' exists", 'info', 'event'); // make sure we turn the broadcast flag off if this // event was published as a result of bubbling // if (opts instanceof Y.CustomEvent) { // events[type].broadcast = false; * This is the entry point for the event monitoring system. * You can monitor 'attach', 'detach', 'fire', and 'publish'. * When configured, these events generate an event. click -> * click_attach, click_detach, click_publish -- these can * be subscribed to like other events to monitor the event * system. Inividual published events can have monitoring * turned on or off (publish can't be turned off before it * it published) by setting the events 'monitor' config. * @param what {String} 'attach', 'detach', 'fire', or 'publish' * @param type {String} Name of the event being monitored * @param o {Object} Information about the event interaction, such as * fire() args, subscription category, publish config * Fire a custom event by name. The callback functions will be executed * from the context specified when the event was created, and with the * If the custom event object hasn't been created, then the event hasn't * been published and it has no subscribers. For performance sake, we * immediate exit in this case. This means the event won't bubble, so * if the intention is that a bubble target be notified, the event must * be published on this object first. * The first argument is the event type, and any additional arguments are * passed to the listeners as parameters. If the first of these is an * object literal, and the event is configured to emit an event facade, * that object is mixed into the event facade and the facade is provided * in place of the original object. * @param type {String|Object} The type of the event, or an object that contains * @param arguments {Object*} an arbitrary set of parameters to pass to * the handler. If the first of these is an object literal and the event is * configured to emit an event facade, the event facade will replace that * parameter after the properties the object literal contains are copied to * @return {EventTarget} the event host // this event has not been published or subscribed to // otherwise there is nothing to be done // delegate to *:type events if there are subscribers // console.log("GOT ONE: " + type); // ret = ce2.fire.apply(ce2, a); * Returns the custom event of the provided type has been created, a * @param type {string} the type, or name of the event * @param prefixed {string} if true, the type is prefixed already * @return {CustomEvent} the custom event or null * Subscribe to a custom event hosted by this object. The * supplied callback will execute after any listeners add * via the subscribe method, and after the default function, * if configured for the event, has executed. * @param type {string} The type of the event * @param fn {Function} The callback * @param context {object} optional execution context. * @param arg* {mixed} 0..n additional arguments to supply to the subscriber * @return the event target or a detach handle per 'chain' config // YArray.each(a[0], function(v) { * Executes the callback before a DOM event, custom event * or method. If the first argument is a function, it * is assumed the target is a method. For DOM and custom * events, this is an alias for Y.on. * For DOM and custom events: * type, callback, context, 0-n arguments * callback, object (method host), methodName, context, 0-n arguments // make Y an event target * Hosts YUI page level events. This is where events bubble to * when the broadcast config is set to 2. This property is * only available if the custom event module is loaded. // @TODO implement a global namespace function on Y.Global? * <code>YUI</code>'s <code>on</code> method is a unified interface for subscribing to * most events exposed by YUI. This includes custom events, DOM events, and * function events. <code>detach</code> is also provided to remove listeners * serviced by this function. * The signature that <code>on</code> accepts varies depending on the type * of event being consumed. Refer to the specific methods that will * service a specific request for additional information about subscribing * <li>Custom events. These events are defined by various * modules in the library. This type of event is delegated to * <code>EventTarget</code>'s <code>on</code> method. * <li>The type of the event</li> * <li>The callback to execute</li> * <li>An optional context object</li> * <li>0..n additional arguments to supply the callback.</li> * <code>Y.on('drag:drophit', function() { // start work });</code> * <li>DOM events. These are moments reported by the browser related * to browser functionality and user interaction. * This type of event is delegated to <code>Event</code>'s * <code>attach</code> method. * <li>The type of the event</li> * <li>The callback to execute</li> * <li>The specification for the Node(s) to attach the listener * to. This can be a selector, collections, or Node/Element * <li>An optional context object</li> * <li>0..n additional arguments to supply the callback.</li> * <code>Y.on('click', function(e) { // something was clicked }, '#someelement');</code> * <li>Function events. These events can be used to react before or after a * function is executed. This type of event is delegated to <code>Event.Do</code>'s * <code>before</code> method. * <li>The callback to execute</li> * <li>The object that has the function that will be listened for.</li> * <li>The name of the function to listen for.</li> * <li>An optional context object</li> * <li>0..n additional arguments to supply the callback.</li> * Example <code>Y.on(function(arg1, arg2, etc) { // obj.methodname was executed }, obj 'methodname');</code> * <code>on</code> corresponds to the moment before any default behavior of * the event. <code>after</code> works the same way, but these listeners * execute after the event's default behavior. <code>before</code> is an * alias for <code>on</code>. * @param type event type (this parameter does not apply for function events) * @param context optionally change the value of 'this' in the callback * @param args* 0..n additional arguments to pass to the callback. * @return the event target or a detach handle per 'chain' config * Listen for an event one time. Equivalent to <code>on</code>, except that * the listener is immediately detached when executed. * @param type event type (this parameter does not apply for function events) * @param context optionally change the value of 'this' in the callback * @param args* 0..n additional arguments to pass to the callback. * @return the event target or a detach handle per 'chain' config * after() is a unified interface for subscribing to * most events exposed by YUI. This includes custom events, * DOM events, and AOP events. This works the same way as * the on() function, only it operates after any default * behavior for the event has executed. @see <code>on</code> for more * @param type event type (this parameter does not apply for function events) * @param context optionally change the value of 'this' in the callback * @param args* 0..n additional arguments to pass to the callback. * @return the event target or a detach handle per 'chain' config