Yahoo! UI Library

yui  3.0.0pr2

Yahoo! UI Library > yui > YUI
Search:
 
Filters

Class YUI - uses Event.Target

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. Options:
  • ------------------------------------------------------------------------
  • Global:
  • ------------------------------------------------------------------------
  • debug: Turn debug statements on or off
  • useBrowserConsole: Log to the browser console if debug is on and the console is available
  • logInclude: A hash of log sources that should be logged. If specified, only log messages from these sources will be logged.
  • logExclude: A hash of log sources that should be not be logged. If specified, all sources are logged if not on this list.
  • throwFail: If throwFail is set, Y.fail will generate or re-throw a JS error. Otherwise the failure is logged.
  • win: The target window/frame
  • core: A list of modules that defines the YUI core (overrides the default)
  • ------------------------------------------------------------------------
  • For event and get:
  • ------------------------------------------------------------------------
  • pollInterval: The default poll interval
  • -------------------------------------------------------------------------
  • For loader:
  • -------------------------------------------------------------------------
  • base: The base dir
  • secureBase: The secure base dir (not implemented)
  • comboBase: The YUI combo service base dir. Ex: http://yui.yahooapis.com/combo?
  • root: The root path to prepend to module names for the combo service. Ex: 2.5.2/build/
  • filter: A filter to apply to result urls. This filter will modify the default path for all modules. The default path for the YUI library is the minified version of the files (e.g., event-min.js). The filter property can be a predefined filter or a custom filter. The valid predefined filters are:
    DEBUG
    Selects the debug versions of the library (e.g., event-debug.js). This option will automatically include the logger widget
    RAW
    Selects the non-minified version of the library (e.g., event.js).
    You can also define a custom filter, which must be an object literal containing a search expression and a replace string: 
    myFilter: { 
'searchExp': "-min\\.js", 
'replaceStr': "-debug.js"
}
  • combine: Use the YUI combo service to reduce the number of http connections required to load your dependencies
  • ignore: A list of modules that should never be dynamically loaded
  • force: A list of modules that should always be loaded when required, even if already present on the page
  • insertBefore: Node or id for a node that should be used as the insertion point for new nodes
  • charset: charset for dynamic nodes
  • timeout: number of milliseconds before a timeout occurs when dynamically loading nodes. in not set, there is no timeout
  • context: execution context for all callbacks
  • onSuccess: callback for the 'success' event
  • onFailure: callback for the 'failure' event
  • onTimeout: callback for the 'timeout' event
  • onProgress: callback executed each time a script or css file is loaded
  • modules: A list of module definitions. See Loader.addModule for the supported module metadata

Properties

_iefix - private object

IE will not enumerate native functions in a derived object even if the function was overridden. This is a workaround for specific functions we care about on the Object prototype.

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 )
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
Returns: YUI
the YUI instance 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

after

Event.Handle after ( )
Executes the callback after 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: type, callback, context, 1-n arguments For methods: callback, object (method host), methodName, context, 1-n arguments
Returns: Event.Handle
unsubscribe handle

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

before

before ( )
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, 1-n arguments For methods: callback, object (method host), methodName, context, 1-n arguments

detach

YUI detach ( type , f , o )
Detach an event listener (either a custom event or a DOM event
Parameters:
type <object> the type of event, or a Event.Handle to for the subscription. If the Event.Handle is passed in, the other parameters are not used.
f <Function> the subscribed function
o <object> the object or element the listener is subscribed to.
Returns: YUI
the YUI instance

fail

YUI fail ( 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 failure 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 logger widget and anything else can consume. If the 'useBrowserConsole' config is true, it will write to the browser console if available.
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

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 YAHOO.property, then YUI.property.package 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

on

Event.Handle on ( type , f , o , context , args* )
Attach an event listener, either to a DOM object or to an Event.Target.
Parameters:
type <string> the event type
f <Function> the function to execute
o <object> the Event.Target or element to attach to
context <object> Optional execution context
args* <object> 0..n additional arguments to append to the signature provided when the event fires.
Returns: Event.Handle
a handle object for unsubscribing to this event.

simulate

static void simulate ( type , options )
Simulates an event on the node.
Parameters:
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 )
Stamps an object with a guid. If the object already has one, a new one is not created
Parameters:
o <object> The object to stamp
Returns: string
The object's guid

substitute

string substitute ( s , o , f )
Does variable substitution on a string. It scans through the string looking for expressions enclosed in { } braces. If an expression is found, it is used a key on the object. If there is a space in the key, the first word is used for the key and the rest is provided to an optional function to be used to programatically determine the value (the extra information might be used for this decision). If the value for the key in the object, or what is returned from the function has a string value, number value, or object value, it is substituted for the bracket expression and it repeats. If this value is an object, it uses the Object's toString() if this has been overridden, otherwise it does a shallow dump of the key/value pairs if Y.dump is available (if dump isn't available, toString() is used). This method is included in the 'substitute' module. It is not included in the YUI module.
Parameters:
s <string> The string that will be modified.
o <object> An object containing the replacement values
f <function> An optional function that can be used to process each match. It receives the key, value, and any extra metadata included with the key inside of the braces.
Returns: string
the substituted string

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

Events

available

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

blur

blur ( )
Adds a DOM focus listener. Uses the focusout event in IE, and the capture phase otherwise so that the event propagates properly.

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)

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

key

key ( 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:
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.

Properties

Copyright © 2008 Yahoo! Inc. All rights reserved.