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
private
void
_init
(
o
)
Initialize this YUI instance
- Parameters:
-
o
<object>
config options
- Returns:
void
private
void
_setup
(
)
Finishes the instance setup. Attaches whatever modules were defined
when the yui modules was registered.
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
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
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
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
string
guid
(
pre
)
Generate an id that is unique among all YUI instances
- Parameters:
-
pre
<string>
optional guid prefix
- Returns:
string
- the guid
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.
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
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
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
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
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
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
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
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
(
)
Executes the callback as soon as the specified element
is detected in the DOM.
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
(
)
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
(
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
(
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
(
)
Use domready event instead. @see domready
Deprecated use 'domready' instead
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
(
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
(
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
(
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
(
)
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.