Yahoo! UI Library

yui  3.2.0

Yahoo! UI Library > yui > YUI
Search:
 
Filters

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. It is the constructor for the object the end user interacts with. As indicated below, each instance has full custom event support, but only if the event system is available.

Constructor

YUI ( o* )
Parameters:
o* <object> 0..n optional configuration objects. these values are store in Y.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

_attach

private void _attach ( )
Executes the function associated with each required module, binding the module to the YUI instance.

_init

private void _init ( )
Initialize this YUI instance

_setup

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

add

YUI add ( name , fn , version , details )
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.
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 must be present before this module can be attached. optional: optional features that should be present if loadOptional is defined. Note: modules are not often loaded this way in YUI 3, but this field is still useful to inform the user that certain features in the component will require additional dependencies. use: features that are included within this module which need to be be attached automatically when this module is attached. This supports the YUI 3 rollup system -- a module with submodules defined will need to have the submodules listed in the 'use' config. The YUI component build tool does this for you.
Returns: YUI
the YUI instance

after

after ( type , fn , context , args* )
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
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

applyConfig

void applyConfig ( the )
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.
Parameters:
the <object> configuration object

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 , refetch )
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

delegate

EventHandle delegate ( type , fn , el , spec , context , args* )

Sets up event delegation on a container element. The delegated event will use a supplied selector or filtering function to test if the event references at least one node that should trigger the subscription callback.

Selector string filters will trigger the callback if the event originated from a node that matches it or is contained in a node that matches it. Function filters are called for each Node up the parent axis to the subscribing container node, and receive at each level the Node and the event object. The function should return true (or a truthy value) if that Node should trigger the subscription callback. Note, it is possible for filters to match multiple Nodes for a single event. In this case, the delegate callback will be executed for each matching Node.

For each matching Node, the callback will be executed with its 'this' object set to the Node matched by the filter (unless a specific context was provided during subscription), and the provided event's currentTarget will also be set to the matching Node. The containing Node from which the subscription was originally made can be referenced as e.container.

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|Function> a selector that must match the target of the event or a function to test target and its parents for a match
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

delegate._applyFilter

protected Node|Node[]|undefined delegate._applyFilter ( filter , args )
Walks up the parent axis of an event's target, and tests each element against a supplied filter function. If any Nodes satisfy the filter, the delegated callback will be triggered for each.
Parameters:
filter <Function> boolean function to test for inclusion in event notification
args <Array> the arguments that would be passed to subscribers
Returns: Node|Node[]|undefined
The Node or Nodes that satisfy the filter

delegate.compileFilter

static Function delegate.compileFilter ( selector )

Compiles a selector string into a filter function to identify whether Nodes along the parent axis of an event's target should trigger event notification.

This function is memoized, so previously compiled filter functions are returned if the same selector string is provided.

This function may be useful when defining synthetic events for delegate handling.

Parameters:
selector <String> the selector string to base the filtration on

delegate.notifySub

private static Boolean delegate.notifySub ( thisObj , args , ce )
Overrides the _notify method on the normal DOM subscription to inject the filtering logic and only proceed in the case of a match.
Parameters:
thisObj <Object> default 'this' object for the callback
args <Array> arguments passed to the event's fire()
ce <CustomEvent> the custom event managing the DOM subscriptions for the subscribed event on the subscribing node.
Returns: Boolean
false if the event was stopped

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/int> merge objects instead of overwriting/ignoring. A value of 2 will skip array merge 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

on

on ( type , fn , context , args* )
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('drag:drophit', 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
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

once

once ( type , fn , context , args* )
Listen for an event one time. Equivalent to on, except that the listener is immediately detached when executed.
Parameters:
type <object> event type (this parameter does not apply for function events)
fn <object> the callback
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

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

throttle

function throttle ( fn , ms )
Throttles a call to a method based on the time between calls.
Parameters:
fn <function> The function call to throttle.
ms <int> The number of milliseconds to throttle the method call. Can set globally with Y.config.throttleTime or by call. Passing a -1 will disable the throttle. Defaults to 150
Returns: function
Returns a wrapped function that calls fn throttled.

use

YUI use ( modules* , *callback )
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.
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. // loads and attaches drag and drop and its dependencies YUI().use('dd', function(Y) {}); // attaches all modules that are available on the page YUI().use('*', function(Y) {}); // intrinsic YUI gallery support (since 3.1.0) YUI().use('gallery-yql', function(Y) {}); // intrinsic YUI 2in3 support (since 3.1.0) YUI().use('yui2-datatable', function(Y) {});
Returns: YUI
the YUI instance

Events

available

available ( type , fn , el , context , args* )
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.

contentready

contentready ( type , fn , el , context , args* )
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.

domready

domready ( )
The domready event fires at the moment the browser's DOM is usable. In most cases, this is before images are fully downloaded, allowing you to provide a more responsive user interface. In YUI 3, domready subscribers will be notified immediately if that moment has already passed when the subscription is created. One exception is if the yui.js file is dynamically injected into the page. If this is done, you must tell the YUI instance that you did this in order for DOMReady (and window load events) to fire normally. That configuration option is 'injected' -- set it to true if the yui.js script is not included inline. This method is part of the 'event-ready' module, which is a submodule of 'event'.

flick

flick ( type , fn , cfg )
Sets up a "flick" event, that is fired whenever the user initiates a flick gesture on the node where the listener is attached. The subscriber can specify a minimum distance or velocity for which the event is to be fired. The subscriber can also specify if there is a particular axis which they are interested in - "x" or "y". If no axis is specified, the axis along which there was most distance covered is used.

It is recommended that you use Y.bind to set up context and additional arguments for your event handler, however if you want to pass the context and arguments as additional signature arguments to "on", you need to provide a null value for the configuration object, e.g: node.on("flick", fn, null, context, arg1, arg2, arg3)

Parameters:
type <string> "flick"
fn <function> The method the event invokes. It receives an event facade with an e.flick object containing the flick related properties: e.flick.time, e.flick.distance, e.flick.velocity and e.flick.axis, e.flick.start.
cfg <Object> Optional. An object which specifies any of the following:
minDistance (in pixels, defaults to 10)
The minimum distance between start and end points, which would qualify the gesture as a flick.
minVelocity (in pixels/ms, defaults to 0)
The minimum velocity which would qualify the gesture as a flick.
preventDefault (defaults to false)
Can be set to true/false to prevent default behavior as soon as the touchstart/touchend or mousedown/mouseup is received so that things like scrolling or text selection can be prevented. This property can also be set to a function, which returns true or false, based on the event facade passed to it.
axis (no default)
Can be set to "x" or "y" if you want to constrain the flick velocity and distance to a single axis. If not defined, the axis along which the maximum distance was covered is used.

gesturemove

gesturemove ( type , fn , cfg )
Sets up a "gesturemove" event, that is fired on touch devices in response to a single finger "touchmove", and on mouse based devices in response to a "mousemove".

By default this event is only fired when the same node has received a "gesturemovestart" event. The subscriber can set standAlone to true, in the configuration properties, if they want to listen for this event without an initial "gesturemovestart".

By default this event sets up it's internal "touchmove" and "mousemove" DOM listeners on the document element. The subscriber can set the root configuration property, to specify which node to attach DOM listeners to, if different from the document.

This event can also be listened for using node.delegate().

It is recommended that you use Y.bind to set up context and additional arguments for your event handler, however if you want to pass the context and arguments as additional signature arguments to on/delegate, you need to provide a null value for the configuration object, e.g: node.on("gesturemove", fn, null, context, arg1, arg2, arg3)

Parameters:
type <string> "gesturemove"
fn <function> The method the event invokes. It receives the event facade of the underlying DOM event (mousemove or touchmove.touches[0]) which contains position co-ordinates.
cfg <Object> Optional. An object which specifies:
standAlone (defaults to false)
true, if the subscriber should be notified even if a "gesturemovestart" has not occured on the same node.
root (defaults to document)
The node to which the internal DOM listeners should be attached.
preventDefault (defaults to false)
Can be set to true/false to prevent default behavior as soon as the touchmove or mousemove is received. As with gesturemovestart, can also be set to function which returns true/false based on the event facade passed to it.

gesturemoveend

gesturemoveend ( type , fn , cfg )
Sets up a "gesturemoveend" event, that is fired on touch devices in response to a single finger "touchend", and on mouse based devices in response to a "mouseup".

By default this event is only fired when the same node has received a "gesturemove" or "gesturemovestart" event. The subscriber can set standAlone to true, in the configuration properties, if they want to listen for this event without a preceding "gesturemovestart" or "gesturemove".

By default this event sets up it's internal "touchend" and "mouseup" DOM listeners on the document element. The subscriber can set the root configuration property, to specify which node to attach DOM listeners to, if different from the document.

This event can also be listened for using node.delegate().

It is recommended that you use Y.bind to set up context and additional arguments for your event handler, however if you want to pass the context and arguments as additional signature arguments to on/delegate, you need to provide a null value for the configuration object, e.g: node.on("gesturemoveend", fn, null, context, arg1, arg2, arg3)

Parameters:
type <string> "gesturemoveend"
fn <function> The method the event invokes. It receives the event facade of the underlying DOM event (mouseup or touchend.changedTouches[0]).
cfg <Object> Optional. An object which specifies:
standAlone (defaults to false)
true, if the subscriber should be notified even if a "gesturemovestart" or "gesturemove" has not occured on the same node.
root (defaults to document)
The node to which the internal DOM listeners should be attached.
preventDefault (defaults to false)
Can be set to true/false to prevent default behavior as soon as the touchend or mouseup is received. As with gesturemovestart, can also be set to function which returns true/false based on the event facade passed to it.

gesturemovestart

gesturemovestart ( type , fn , cfg )
Sets up a "gesturemovestart" event, that is fired on touch devices in response to a single finger "touchstart", and on mouse based devices in response to a "mousedown". The subscriber can specify the minimum time and distance thresholds which should be crossed before the "gesturemovestart" is fired and for the mouse, which button should initiate a "gesturemovestart". This event can also be listened for using node.delegate().

It is recommended that you use Y.bind to set up context and additional arguments for your event handler, however if you want to pass the context and arguments as additional signature arguments to on/delegate, you need to provide a null value for the configuration object, e.g: node.on("gesturemovestart", fn, null, context, arg1, arg2, arg3)

Parameters:
type <string> "gesturemovestart"
fn <function> The method the event invokes. It receives the event facade of the underlying DOM event (mousedown or touchstart.touches[0]) which contains position co-ordinates.
cfg <Object> Optional. An object which specifies:
minDistance (defaults to 0)
The minimum distance threshold which should be crossed before the gesturemovestart is fired
minTime (defaults to 0)
The minimum time threshold for which the finger/mouse should be help down before the gesturemovestart is fired
button (no default)
In the case of a mouse input device, if the event should only be fired for a specific mouse button.
preventDefault (defaults to false)
Can be set to true/false to prevent default behavior as soon as the touchstart or mousedown is received (that is before minTime or minDistance thresholds are crossed, and so before the gesturemovestart listener is notified) so that things like text selection and context popups (on touch devices) can be prevented. This property can also be set to a function, which returns true or false, based on the event facade passed to it (for example, DragDrop can determine if the target is a valid handle or not before preventing default).

hashchange

hashchange ( e )

Synthetic window.onhashchange event that normalizes differences across browsers and provides support for browsers that don't natively support onhashchange.

This event is provided by the history-hash module.

Usage example: 

YUI().use('history-hash', function (Y) {
  Y.on('hashchange', function (e) {
    // Handle hashchange events on the current window.
  }, Y.config.win);
});
Parameters:
e <EventFacade> Event facade with the following additional properties:
oldHash
Previous hash fragment value before the change.
oldUrl
Previous URL (including the hash fragment) before the change.
newHash
New hash fragment value after the change.
newUrl
New URL (including the hash fragment) after the change.

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

mousewheel

mousewheel ( type , fn , context , args )
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.

valueChange

valueChange ( e )

Synthetic event that fires when the value property of an input field or textarea changes as a result of a keystroke, mouse operation, or input method editor (IME) input event.

Unlike the onchange event, this event fires when the value actually changes and not when the element loses focus. This event also reports IME and multi-stroke input more reliably than oninput or the various key events across browsers.

This event is provided by the event-valuechange module.

Usage example: 

YUI().use('event-valuechange', function (Y) {
  Y.one('input').on('valueChange', function (e) {
    // Handle valueChange events on the first input element on the page.
  });
});
Parameters:
e <EventFacade> Event facade with the following additional properties:
prevVal (String)
Previous value before the latest change.
newVal (String)
New value after the latest change.

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.

Properties

Copyright © 2010 Yahoo! Inc. All rights reserved.