Yahoo! UI Library

Register a module

Parameters:

name <string> module name

fn <Function> entry point into the module that is used to bind module to the YUI instance

version <string> version string

details <object> optional config data: requires - features that should be present before loading optional - optional features that should be present if load optional defined use - features that should be attached automatically skinnable - rollup omit - features that should not be loaded if this module is present

Returns: YUI

the YUI instance

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 on for more information.

Parameters:

type <object> event type (this parameter does not apply for function events)

fn <object> the callback

target <object> a descriptor for the target (applies to custom events only). For function events, this is the object that contains the function to execute.

extra <object> 0..n Extra information a particular event may need. These will be documented with the event. In the case of function events, this is the name of the function to execute on the host. In the case of delegate listeners, this is the event delegation specification.

context <object> optionally change the value of 'this' in the callback

args* <object> 0..n additional arguments to pass to the callback.

Returns:

the event target or a detach handle per 'chain' config

Executes a method on a YUI instance with the specified id if the specified method is whitelisted.

Parameters:

id <string> the YUI instance id

method <string> the name of the method to exectute. Ex: 'Object.keys'

args <Array> the arguments to apply to the method

Returns: object

the return value from the applied method or null

Returns a wrapper for a function which caches the return value of that function, keyed off of the combined argument values.

Parameters:

source <function> the function to memoize

cache <object> an optional cache seed

refetch <object> if supplied, this value is tested against the cached value. If the values are equal, the wrapped function is executed again.

Returns: Function

the wrapped function

Sets up event delegation on a container element. The delegated event will use a supplied selector to test if the target or one of the descendants of the target match it. The supplied callback function will only be executed if a match was encountered, and, in fact, will be executed for each element that matches if you supply an ambiguous selector. 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 delegation specifcation. 'container' is set to the element that the listener is bound to (this normally would be the 'currentTarget').

Parameters:

type <string> the event type to delegate

fn <function> the callback function to execute. This function will be provided the event object for the delegated event.

el <string|node> the element that is the delegation container

spec <string> a selector that must match the target of the event.

context <object> optional argument that specifies what 'this' refers to.

args* <object> 0..n additional arguments to pass on to the callback function. These arguments will be added after the event object.

Returns: EventHandle

the detach handle

Report an error. The reporting mechanism is controled by the 'throwFail' configuration attribute. If throwFail is not specified, the message is written to the Logger, otherwise a JS error is thrown

Parameters:

msg <string> the error message

e <Error> Optional JS error that was caught. If supplied and throwFail is specified, this error will be re-thrown.

Returns: YUI

this YUI instance

Generate an id that is unique among all YUI instances

Parameters:

pre <string> optional guid prefix

Returns: string

the guid

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.

Parameters:

when <int> the number of milliseconds to wait until the fn is executed.

o <object> the context object.

fn <Function|String> the function to execute or the name of the method in the 'o' object to execute.

data <object> [Array] data that is provided to the function. This accepts either a single item or an array. If an array is provided, the function is executed with one parameter for each array item. If you need to pass a single array parameter, it needs to be wrapped in an array [myarray].

periodic <boolean> if true, executes continuously at supplied interval until canceled.

Returns: object

a timer object. Call the cancel() method on this object to stop the timer.

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.

Parameters:

msg <String> The message to log.

cat <String> The log category for the message. Default categories are "info", "warn", "error", time". Custom categories can be used as well. (opt)

src <String> The source of the the message (opt)

silent <boolean> If true, the log event won't fire

Returns: YUI

YUI instance

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.

Parameters:

arguments <Object*> the objects to merge

Returns: object

the new merged object

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

Parameters:

msg <String> The message to log.

cat <String> The log category for the message. Default categories are "info", "warn", "error", time". Custom categories can be used as well. (opt)

src <String> The source of the the message (opt)

silent <boolean> If true, the log event won't fire

Returns: YUI

YUI instance

Applies the supplier's properties to the receiver. By default all prototype and static propertes on the supplier are applied to the corresponding spot on the receiver. By default all properties are applied, and a property that is already on the reciever will not be overwritten. The default behavior can be modified by supplying the appropriate parameters.

Parameters:

r <Function> the object to receive the augmentation

s <Function> the object that supplies the properties to augment

ov <boolean> if true, properties already on the receiver will be overwritten if found on the supplier.

wl <string[]> a whitelist. If supplied, only properties in this list will be applied to the receiver.

mode <int> what should be copies, and to where default(0): object to object 1: prototype to prototype (old augment) 2: prototype to prototype and object props (new augment) 3: prototype to object 4: object to prototype

merge <boolean> merge objects instead of overwriting/ignoring Used by Y.aggregate

Returns: object

the augmented object

Returns the namespace specified and creates it if it doesn't exist

YUI.namespace("property.package");
YUI.namespace("YAHOO.property.package");

Either of the above would create YUI.property, then YUI.property.package (YAHOO is scrubbed out, this is to remain compatible with YUI2) Be careful when naming packages. Reserved words may work in some browsers and not others. For instance, the following will fail in Safari:

YUI.namespace("really.long.nested.namespace");

This fails because "long" is a future reserved word in ECMAScript

Parameters:

arguments <string*> 1-n namespaces to create

Returns: object

A reference to the last namespace object created

Registers plugins to be instantiated at the class level (plugins which should be plugged into every instance of Node by default).

Parameters:

plugin <Function | Array> Either the plugin class, an array of plugin classes or an array of objects (with fn and cfg properties defined)

config <Object> (Optional) If plugin is the plugin class, the configuration for the plugin

Unregisters any class level plugins which have been registered by the Node

Parameters:

plugin <Function | Array> The plugin class, or an array of plugin classes

YUI's on method is a unified interface for subscribing to most events exposed by YUI. This includes custom events, DOM events, and function events. detach is also provided to remove listeners serviced by this function. The signature that on 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 to that type of event.

• Custom events. These events are defined by various modules in the library. This type of event is delegated to EventTarget's on method.
  • The type of the event
  • The callback to execute
  • An optional context object
  • 0..n additional arguments to supply the callback.
  Example: Y.on('domready', function() { // start work });
• DOM events. These are moments reported by the browser related to browser functionality and user interaction. This type of event is delegated to Event's attach method.
  • The type of the event
  • The callback to execute
  • The specification for the Node(s) to attach the listener to. This can be a selector, collections, or Node/Element refereces.
  • An optional context object
  • 0..n additional arguments to supply the callback.
  Example: Y.on('click', function(e) { // something was clicked }, '#someelement');
• Function events. These events can be used to react before or after a function is executed. This type of event is delegated to Event.Do's before method.
  • The callback to execute
  • The object that has the function that will be listened for.
  • The name of the function to listen for.
  • An optional context object
  • 0..n additional arguments to supply the callback.
  Example Y.on(function(arg1, arg2, etc) { // obj.methodname was executed }, obj 'methodname');

on corresponds to the moment before any default behavior of the event. after works the same way, but these listeners execute after the event's default behavior. before is an alias for on.

Parameters:

type** <object> event type (this parameter does not apply for function events)

fn <object> the callback

target** <object> a descriptor for the target (applies to custom events only). For function events, this is the object that contains the function to execute.

extra** <object> 0..n Extra information a particular event may need. These will be documented with the event. In the case of function events, this is the name of the function to execute on the host. In the case of delegate listeners, this is the event delegation specification.

context <object> optionally change the value of 'this' in the callback

args* <object> 0..n additional arguments to pass to the callback.

Returns:

the event target or a detach handle per 'chain' config

Simulates the event with the given name on a target.

Parameters:

target <HTMLElement> The DOM element that's the target of the event.

type <String> The type of event to simulate (i.e., "click").

options <Object> (Optional) Extra options to copy onto the event object.

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

Parameters:

o <object> The object to stamp

readOnly <boolean> if true, a valid guid will only be returned if the object has one assigned to it.

Returns: string

The object's guid or null

Bind a module to a YUI instance

Parameters:

modules* <string> 1-n modules to bind (uses arguments array)

*callback <function> callback function executed when the instance has the required functionality. If included, it must be the last parameter.

Returns: YUI

the YUI instance

Executes the callback as soon as the specified element is detected in the DOM.

Parameters:

type <string> 'available'

fn <function> the callback function to execute.

el <string|HTMLElement|collection> the element(s) to attach

context <object> optional argument that specifies what 'this' refers to.

args* <object> 0..n additional arguments to pass on to the callback function. These arguments will be added after the event object.

Adds a DOM blur listener. Uses the focusout event in IE, DOMFocusOut for Opera and Webkit, and the capture phase for Gecko so that the event propagates in a way that enables event delegation.

Parameters:

type <string> 'blur'

fn <function> the callback function to execute

o <string|HTMLElement|collection> the element(s) to bind

context <object> optional context object

args <object> 0..n additional arguments to provide to the listener.

Executes the callback as soon as the specified element is detected in the DOM with a nextSibling property (indicating that the element's children are available)

Parameters:

type <string> 'contentready'

fn <function> the callback function to execute.

el <string|HTMLElement|collection> the element(s) to attach

context <object> optional argument that specifies what 'this' refers to.

args* <object> 0..n additional arguments to pass on to the callback function. These arguments will be added after the event object.

Adds a DOM focus listener. Uses the focusin event in IE, DOMFocusIn for Opera and Webkit, and the capture phase for Gecko so that the event propagates in a way that enables event delegation.

Parameters:

type <string> 'focus'

fn <function> the callback function to execute

o <string|HTMLElement|collection> the element(s) to bind

context <object> optional context object

args <object> 0..n additional arguments to provide to the listener.

Add a key listener. The listener will only be notified if the keystroke detected meets the supplied specification. The spec consists of the key event type, followed by a colon, followed by zero or more comma separated key codes, followed by zero or more modifiers delimited by a plus sign. Ex: press:12,65+shift+ctrl

Parameters:

type <string> 'key'

fn <function> the function to execute

id <string|HTMLElement|collection> the element(s) to bind

spec <string> the keyCode and modifier specification

o <object> optional context object

args <object> 0..n additional arguments to provide to the listener.

Sets up a "mouseenter" listener—a listener that is called the first time the user's mouse enters the specified element(s).

Parameters:

type <string> "mouseenter"

fn <function> The method the event invokes.

el <string|node> The element(s) to assign the listener to.

spec <string> Optional. String representing a selector that must match the target of the event in order for the listener to be called.

Sets up a "mouseleave" listener—a listener that is called the first time the user's mouse leaves the specified element(s).

Parameters:

type <string> "mouseleave"

fn <function> The method the event invokes.

el <string|node> The element(s) to assign the listener to.

spec <string> Optional. String representing a selector that must match the target of the event in order for the listener to be called.

Mousewheel event. This listener is automatically attached to the correct target, so one should not be supplied. Mouse wheel direction and velocity is stored in the 'mouseDelta' field.

Parameters:

type <string> 'mousewheel'

fn <function> the callback to execute

context <object> optional context object

args <object> 0..n additional arguments to provide to the listener.

Firefox fires the window resize event once when the resize action finishes, other browsers fire the event periodically during the resize. This code uses timeout logic to simulate the Firefox behavior in other browsers.