YUI Class

Registers a module with the YUI global. The easiest way to create a first-class YUI module is to use the YUI component build tool.

http://yuilibrary.com/projects/builder

The build system will produce the YUI.add wrapper for you module, 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.

Static method on the Global YUI object to apply a config to all YUI instances. It's main use case is "mashups" where several third party scripts are trying to write to a global YUI config at the same time. This way they can all call YUI.applyConfig({}) instead of overwriting other scripts configs.

Applies a new configuration object to the YUI instance config. 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 a method on a YUI instance with the specified id if the specified 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 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.

Clears internally stored data.

Clears data on all Node instances bound to the NodeList.

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.

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 the 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

Report an error. The reporting mechanism is controlled by the throwFail configuration attribute. If throwFail is not specified, the message is written to the Logger, otherwise a JS error is thrown. If an errorFn is specified in the config it must return true to keep the error 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().

Retrieves arbitrary data stored on each Node instance bound to the NodeList.

Retrieves arbitrary data stored on a Node instance. If no data is associated with the Node, it will attempt to retrieve a value from the corresponding HTML data attribute. (e.g. node.getData('foo') will check node.getAttribute('data-foo')).

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.

Generate an id that is unique among all YUI instances

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).

instanceof check for objects that works around memory leak in IE when the item tested is window/document

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.

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.

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 using Y.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.

Adds a namespace object onto the YUI global if called statically.

// creates YUI.your.namespace.here as nested objects
YUI.namespace("your.namespace.here");

If called as a method on a YUI instance, it creates the namespace on the 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. This allows multiple calls to namespace to preserve existing namespaced properties.

If the first token in the namespace string is "YAHOO", the token is discarded.

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.

Stores arbitrary data on a Node instance. This is not stored with the DOM node.

Stores arbitrary data on each Node instance bound to the NodeList. This is not stored with the DOM node.

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

Returns a guid associated with an object. If the object does not have one, a new one is created unless readOnly is specified.

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

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

• All requirements are available on the page -- The modules are attached to the instance. If supplied, the use callback is executed synchronously.

• Modules are missing, the Get utility is not available OR the 'bootstrap' config is false -- A warning is issued about the missing modules and all available modules are attached.

• Modules are missing, the Loader is not available but the Get utility is and boostrap is not false -- The loader is bootstrapped before doing the following....

• Modules are missing and the Loader is available -- The loader expands the dependency tree and fetches missing modules. When the loader is finshed the callback supplied to use is executed asynchronously.