# Yahoo! UI Library

### yui 3.0.0b1

Yahoo! UI Library > yui > YUI
Search:
Filters Show Private Show Protected Show Deprecated

## Class YUI - uses EventTarget

The YUI global namespace object. If YUI is already defined, the existing YUI object will not be overwritten so that defined namespaces are preserved.

### Constructor

YUI `( o )`

Parameters:
  `o <object>` Optional configuration object. This object is stored in YUI.config. See config for the list of supported properties.

### Properties

#### Global - `EventTarget`

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.

### Methods

#### _init

`private void _init ( o )`
Initialize this YUI instance

Parameters:
  `o <object>` config options

Returns: `void`

#### _setup

`private void _setup ( )`
Finishes the instance setup. Attaches whatever modules were defined when the yui modules was registered.

Returns: `void`

#### add

`YUI add ( name , fn , version , details )`
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

#### applyTo

`object applyTo ( id , method , args )`
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

#### cached

`Function cached ( source , cache )`
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

Returns: `Function`
  the wrapped function

#### error

`YUI error ( msg , e )`
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

#### guid

`string guid ( pre )`
Generate an id that is unique among all YUI instances

Parameters:
  `pre <string>` optional guid prefix

Returns: `string`
  the guid

#### later

`object later ( when , o , fn , data , periodic )`
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.

#### log

`YUI log ( msg , cat , src , silent )`
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

#### merge

`object merge ( arguments )`
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

#### message

`YUI message ( msg , cat , src , silent )`
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

#### mix

`object mix ( r , s , ov , wl , mode , merge )`
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

#### namespace

`object namespace ( arguments )`
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

#### simulate

`static void simulate ( target , type , options )`
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: `void`

#### stamp

`string stamp ( o , readOnly )`
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

#### use

`YUI use ( modules* , *callback )`
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

#### Methods inherited from EventTarget:

`_getType, _parseType, addTarget, after, before, bubble, detach, detachAll, fire, getEvent, on, publish, removeTarget, subscribe, unsubscribe, unsubscribeAll`

### Events

#### available

`available ( )`
Executes the callback as soon as the specified element is detected in the DOM.

#### blur

`blur ( )`
Adds a DOM blur listener. Uses the focusout event in IE, and the capture phase otherwise so that the event propagates in a way that enables event delegation. Note: if you are registering this event on the intended target rather than an ancestor, the element must be in the DOM at the time of registration in order for it to work in Opera.

#### contentready

`contentready ( )`
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)

#### delegate

`delegate ( type , fn , el , delegateType , spec )`
Sets up a delegated listener container.

Parameters:
  `type <string>` 'delegate'
  `fn <string>` the function to execute
  `el <string|node>` the element that is the delegation container
  `delegateType <string>` the event type to delegate
  `spec <string>` a selector that must match the target of the event.

#### domready

`domready ( fn )`
Executes the supplied callback when the DOM is first usable. This will execute immediately if called after the DOMReady event has fired. @todo the DOMContentReady event does not fire when the script is dynamically injected into the page. This means the DOMReady custom event will never fire in FireFox or Opera when the library is injected. It _will_ fire in Safari, and the IE implementation would allow for us to fire it if the defered script is not available. We want this to behave the same in all browsers. Is there a way to identify when the script has been injected instead of included inline? Is there a way to know whether the window onload event has fired without having had a listener attached to it when it did so?

The callback is a Event.Custom, so the signature is:

type <string>, args <array>, customobject <object>

For DOMReady events, there are no fire argments, so the signature is:

"DOMReady", [], obj

Parameters:
  `fn <function>` what to execute when the element is found.

#### event:ready

`event:ready ( )`
Use domready event instead. @see domready
Deprecated use 'domready' instead

#### focus

`focus ( )`
Adds a DOM focus listener. Uses the focusin event in IE, and the capture phase otherwise so that the event propagates in a way that enables event delegation. Note: if you are registering this event on the intended target rather than an ancestor, the element must be in the DOM in order for it to work in Opera.

#### key

`key ( type , fn , id , spec , o , args )`
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 <string>` the function to execute
  `id <string>` the element(s) to bind
  `spec <string>` the keyCode and modifier specification
  `o <object>` optional context object
  `args <object>` 0..n additional arguments that should be provided to the listener.

#### mouseenter

`mouseenter ( type , fn , el , spec )`
Sets up a "mouseenter" listener—a listener that is called the first time the user's mouse enters the specified element(s). By passing a CSS selector as the fourth argument, can also be used to delegate a "mouseenter" event listener.

Parameters:
  `type <string>` "mouseenter"
  `fn <string>` 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.

#### mouseleave

`mouseleave ( type , fn , el , spec )`
Sets up a "mouseleave" listener—a listener that is called the first time the user's mouse leaves the specified element(s). By passing a CSS selector as the fourth argument, can also be used to delegate a "mouseleave" event listener.

Parameters:
  `type <string>` "mouseleave"
  `fn <string>` 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.

#### windowresize

`windowresize ( )`
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.

Copyright © 2009 Yahoo! Inc. All rights reserved.