YUI Class

Registers a YUI module and makes it available for use in a YUI().use() call or as a dependency for other modules.

The easiest way to create a first-class YUI module is to use Shifter, the YUI component build tool.

Shifter will automatically wrap your module code in a YUI.add() call along with any configuration info required for the module.

Like on(), this method creates a subscription to a custom event or to the execution of a method on an object.

For events, after() subscribers are executed after the event's defaultFn unless e.preventDefault() was called from an on() subscriber.

See the on() method for additional subscription options.

NOTE: The subscription signature shown is for events, not for function injection. See Y.Do.after for that signature.

Copies object properties from the supplier to the receiver. If the target has the property, and the property is an object, the target object will be augmented with the supplier's value.

Retrieves a NodeList based on the given CSS selector.

Applies a configuration to all YUI instances in this execution context.

The main use case for this method is in "mashups" where several third-party scripts need to write to a global YUI config, but cannot share a single centrally-managed config object. This way they can all call YUI.applyConfig({}) instead of overwriting the single global config.

Applies a new configuration object to the config of this YUI instance. This will merge new group/module definitions, and will also update the loader cache if necessary. Updating Y.config directly will not update the cache.

Executes the named method on the specified YUI instance if that method is whitelisted.

Asserts that a given condition is true. If not, then a Y.Assert.Error object is thrown and the test fails.

Augments the receiver with prototype properties from the supplier. The receiver may be a constructor function or an object. The supplier must be a constructor function.

If the receiver is an object, then the supplier constructor will be called immediately after receiver is augmented, with receiver as the this object.

If the receiver is a constructor function, then all prototype methods of supplier that are copied to receiver will be sequestered, and the supplier constructor will not be called immediately. The first time any sequestered method is called on the receiver's prototype, all sequestered methods will be immediately copied to the receiver's prototype, the supplier's constructor will be executed, and finally the newly unsequestered method that was called will be executed.

This sequestering logic sounds like a bunch of complicated voodoo, but it makes it cheap to perform frequent augmentation by ensuring that suppliers' constructors are only called if a supplied method is actually used. If none of the supplied methods is ever used, then there's no need to take the performance hit of calling the supplier's constructor.

Returns a new promise that will be resolved when all operations have completed. Takes both any numer of values as arguments. If an argument is a not a promise, it will be wrapped in a new promise, same as in Y.when().

Returns a function that will execute the supplied function in the supplied object's context, optionally adding any additional supplied parameters to the beginning of the arguments collection the supplied to the function.

Returns a wrapper for a function which caches the return value of that function, keyed off of the combined string representation of the argument values provided when the wrapper is called.

Calling this function again with the same arguments will return the cached value rather than executing the wrapped function.

Note that since the cache is keyed off of the string representation of arguments passed to the wrapper function, arguments that aren't strings and don't provide a meaningful toString() method may result in unexpected caching behavior. For example, the objects {} and {foo: 'bar'} would both be converted to the string [object Object] when used as a cache key.

Deep object/array copy. Function clones are actually wrappers around the original function. Array-like objects are treated as arrays. Primitives are returned untouched. Optionally, a function can be provided to handle other data types, filter keys, validate values, etc.

Note: Cloning a non-trivial object is a reasonably heavy operation, due to the need to recursively iterate down non-primitive properties. Clone should be used only when a deep clone down to leaf level properties is explicitly required. This method will also

In many cases (for example, when trying to isolate objects used as hashes for configuration properties), a shallow copy, using Y.merge() is normally sufficient. If more than one level of isolation is required, Y.merge() can be used selectively at each level which needs to be isolated from the original without going all the way to leaf properties.

Sets up event delegation on a container element. The delegated event will use a supplied filter to test if the callback should be executed. This filter can be either a selector string or a function that returns a Node to use as the currentTarget for the event.

The event object for the delegated event is supplied to the callback function. It is modified slightly in order to support all properties that may be needed for event delegation. 'currentTarget' is set to the element that matched the selector string filter or the Node returned from the filter function. 'container' is set to the element that the listener is delegated from (this normally would be the 'currentTarget').

Filter functions will be called with the arguments that would be passed to the callback function, including the event object as the first parameter. The function should return false (or a falsey value) if the success criteria aren't met, and the Node to use as the event's currentTarget and 'this' object if they are.

Destroys this YUI instance.

Returns a simple string representation of the object or array. Other types of objects will be returned unprocessed. Arrays are expected to be indexed.

Executes the supplied function for each item in a collection. Supports arrays, objects, and NodeLists

Reports an error.

The reporting mechanism is controlled by the throwFail configuration attribute. If throwFail is falsy, the message is logged. If throwFail is truthy, a JS exception is thrown.

If an errorFn is specified in the config it must return true to indicate that the exception was handled and keep it from being thrown.

Utility to set up the prototype, constructor and superclass properties to support an inheritance strategy that can chain constructors and methods. Static members will not be inherited.

Forces an assertion error to occur. Shortcut for Y.Assert.fail().

Returns the location object from the window/frame in which this YUI instance operates, or undefined when executing in a non-browser environment (e.g. Node.js).

It is not recommended to hold references to the window.location object outside of the scope of a function in which its properties are being accessed or its methods are being called. This is because of a nasty bug/issue that exists in both Safari and MobileSafari browsers: WebKit Bug 34679.

Generates an id string that is unique among all YUI instances in this execution context.

Method for setting and deleting IO HTTP headers to be sent with every request.

Hosted as a property on the io function (e.g. Y.io.header).

Safe instanceof wrapper that works around a memory leak in IE when the object being tested is window or document.

Unless you are testing objects that may be window or document, you should use the native instanceof operator instead of this method.

Method for initiating an ajax call. The first argument is the url end point for the call. The second argument is an object to configure the transaction and attach event subscriptions. The configuration object supports the following properties:

method

HTTP method verb (e.g., GET or POST). If this property is not not defined, the default value will be GET.

data

This is the name-value string that will be sent as the transaction data. If the request is HTTP GET, the data become part of querystring. If HTTP POST, the data are sent in the message body.

xdr

Defines the transport to be used for cross-domain requests. By setting this property, the transaction will use the specified transport instead of XMLHttpRequest. The properties of the transport object are:

use

The transport to be used: 'flash' or 'native'

dataType

Set the value to 'XML' if that is the expected response content type.

form

Form serialization configuration object. Its properties are:

id

Node object or id of HTML form

useDisabled

true to also serialize disabled form field values (defaults to false)

on

Assigns transaction event subscriptions. Available events are:

start

Fires when a request is sent to a resource.

complete

Fires when the transaction is complete.

success

Fires when the HTTP response status is within the 2xx range.

failure

Fires when the HTTP response status is outside the 2xx range, if an exception occurs, if the transation is aborted, or if the transaction exceeds a configured timeout.

end

Fires at the conclusion of the transaction lifecycle, after success or failure.

<p>Callback functions for start and end receive the id of the
            transaction as a first argument. For complete, success, and
            failure, callbacks receive the id and the response object
            (usually the XMLHttpRequest instance).  If the arguments
            property was included in the configuration object passed to
            Y.io(), the configured data will be passed to all callbacks as
            the last argument.</p>
            </dd>

sync

Pass true to make a same-domain transaction synchronous. CAVEAT: This will negatively impact the user experience. Have a very good reason if you intend to use this.

context

The "this'" object for all configured event handlers. If a specific context is needed for individual callbacks, bind the callback to a context usingY.bind()`.

headers

Object map of transaction headers to send to the server. The object keys are the header names and the values are the header values.

timeout

Millisecond threshold for the transaction before being automatically aborted.

arguments

User-defined data passed to all registered event handlers. This value is available as the second argument in the "start" and "end" event handlers. It is the third argument in the "complete", "success", and "failure" event handlers. Be sure to quote this property name in the transaction configuration as "arguments" is a reserved word in JavaScript (e.g. Y.io({ ..., "arguments": stuff })).

Executes the supplied function in the context of the supplied object 'when' milliseconds later. Executes the function a single time unless periodic is set to true.

If the 'debug' config is true, a 'yui:log' event will be dispatched, which the Console widget and anything else can consume. If the 'useBrowserConsole' config is true, it will write to the browser console if available. YUI-specific log messages will only be present in the -debug versions of the JS files. The build system is supposed to remove log statements from the raw and minified versions of the files.

Returns a new object containing all of the properties of all the supplied objects. The properties from later objects will overwrite those in earlier objects.

Passing in a single object will create a shallow copy of it. For a deep copy, use clone().

Write a system message. This message will be preserved in the minified and raw versions of the YUI files, unlike log statements.

Mixes supplier's properties into receiver.

Properties on receiver or receiver's prototype will not be overwritten or shadowed unless the overwrite parameter is true, and will not be merged unless the merge parameter is true.

In the default mode (0), only properties the supplier owns are copied (prototype properties are not copied). The following copying modes are available:

• 0: Default. Object to object.
• 1: Prototype to prototype.
• 2: Prototype to prototype and object to object.
• 3: Prototype to object.
• 4: Object to prototype.

Utility method for safely creating namespaces if they don't already exist. May be called statically on the YUI global object or as a method on a YUI instance.

When called statically, a namespace will be created on the YUI global object:

// Create YUI.your.namespace.here as nested objects, preserving any
            // objects that already exist instead of overwriting them.
            YUI.namespace('your.namespace.here');

When called as a method on a YUI instance, a namespace will be created on that instance:

// Creates Y.property.package.
            Y.namespace('property.package');

Dots in the input string cause namespace to create nested objects for each token. If any part of the requested namespace already exists, the current object will be left in place and will not be overwritten. This allows multiple calls to namespace to preserve existing namespaced properties.

If the first token in the namespace string is "YAHOO", that token is discarded. This is legacy behavior for backwards compatibility with YUI 2.

Be careful with namespace tokens. Reserved words may work in some browsers and not others. For instance, the following will fail in some browsers because the supported version of JavaScript reserves the word "long":

Y.namespace('really.long.nested.namespace');

Note: If you pass multiple arguments to create multiple namespaces, only the last one created is returned from this function.

Y.on() can do many things:

• Subscribe to custom events published and fired from Y
• Subscribe to custom events published with broadcast 1 or 2 and fired from any object in the YUI instance sandbox
• Subscribe to DOM events
• Subscribe to the execution of a method on any object, effectively treating that method as an event

For custom event subscriptions, pass the custom event name as the first argument and callback as the second. The this object in the callback will be Y unless an override is passed as the third argument.

Y.on('io:complete', function () {
                Y.MyApp.updateStatus('Transaction complete');
            });

To subscribe to DOM events, pass the name of a DOM event as the first argument and a CSS selector string as the third argument after the callback function. Alternately, the third argument can be a Node, NodeList, HTMLElement, array, or simply omitted (the default is the window object).

Y.on('click', function (e) {
                e.preventDefault();
            
                // proceed with ajax form submission
                var url = this.get('action');
                ...
            }, '#my-form');

The this object in DOM event callbacks will be the Node targeted by the CSS selector or other identifier.

on() subscribers for DOM events or custom events published with a defaultFn can prevent the default behavior with e.preventDefault() from the event object passed as the first parameter to the subscription callback.

To subscribe to the execution of an object method, pass arguments corresponding to the call signature for Y.Do.before(...).

NOTE: The formal parameter list below is for events, not for function injection. See Y.Do.before for that signature.

Listen for an event one time. Equivalent to on(), except that the listener is immediately detached when executed.

See the on() method for additional subscription options.

Listen for an event one time. Equivalent to once(), except, like after(), the subscription callback executes after all on() subscribers and the event's defaultFn (if configured) have executed. Like after() if any on() phase subscriber calls e.preventDefault(), neither the defaultFn nor the after() subscribers will execute.

The listener is immediately detached when executed.

See the on() method for additional subscription options.

Returns a single Node instance bound to the node or the first element matching the given selector. Returns null if no match found. Note: For chaining purposes you may want to use Y.all, which returns a NodeList when no match is found.

Returns a function that will execute the supplied function in the supplied object's context, optionally adding any additional supplied parameters to the end of the arguments the function is executed with.

Sugar for loading both legacy and ES6-based YUI modules.

Set a method to be called when Get.script is called in Node.js Get will open the file, then pass it's content and it's path to this method before attaching it. Commonly used for code coverage instrumentation. Calling this multiple times will only attach the last hook method. This method is only available in Node.js.

Executes the supplied function for each item in a collection. The operation stops if the function returns true. Supports arrays, objects, and NodeLists.

Y.soon accepts a callback function. The callback function will be called once in a future turn of the JavaScript event loop. If the function requires a specific execution context or arguments, wrap it with Y.bind. Y.soon returns an object with a cancel method. If the cancel method is called before the callback function, the callback function won't be called.

Returns a unique id associated with the given object and (if readOnly is falsy) stamps the object with that id so it can be identified in the future.

Stamping an object involves adding a _yuid property to it that contains the object's id. One exception to this is that in Internet Explorer, DOM nodes have a uniqueID property that contains a browser-generated unique id, which will be used instead of a YUI-generated id when available.

Throttles a call to a method based on the time between calls.

Attaches one or more modules to this YUI instance. When this is executed, the requirements of the desired modules are analyzed, and one of several things can happen:

• All required modules have already been loaded, and just need to be attached to this YUI instance. In this case, the use() callback will be executed synchronously after the modules are attached.

• One or more modules have not yet been loaded, or the Get utility is not available, or the bootstrap config option is false. In this case, a warning is issued indicating that modules are missing, but all available modules will still be attached and the use() callback will be executed synchronously.

• One or more modules are missing and the Loader is not available but the Get utility is, and bootstrap is not false. In this case, the Get utility will be used to load the Loader, and we will then proceed to the following state:

• One or more modules are missing and the Loader is available. In this case, the Loader will be used to resolve the dependency tree for the missing modules and load them and their dependencies. When the Loader is finished loading modules, the use() callback will be executed asynchronously.

Abstraction API allowing you to interact with promises or raw values as if they were promises. If a non-promise object is passed in, a new Resolver is created and scheduled to resolve asynchronously with the provided value.

In either case, a promise is returned. If either callback or errback are provided, the promise returned is the one returned from calling promise.then(callback, errback) on the provided or created promise. If neither are provided, the original promise is returned.