YUI recommends YUI3.
YUI 2 has been deprecated since 2011. This site acts as an archive for files and documentation.
This documentation is no longer maintained.
The YAHOO Global Object provides a single global namespace within which all YUI Library code resides. It must be included on every page that utilizes the YUI Library, and it must appear before any of the other YUI component.
The YAHOO Global Object also contains a number of methods that are used throughout the library.
The YAHOO Global Object must be included before any of the other script files that are part of YUI:
<!-- YAHOO Global Object source file --> <script type="text/javascript" src="http://yui.yahooapis.com/2.9.0/build/yahoo/yahoo-min.js"></script> <!-- Additional source files go here -->
<!-- YAHOO Global Object source file --> <script type="text/javascript" src="http://yui.yahooapis.com/2.9.0/build/yahoo/yahoo-min.js"></script> <!-- Additional source files go here -->
Instead of copying and pasting the filepaths above, try letting the YUI dependency Configurator determine the optimal file list for your desired components; the Configurator uses YUI Loader to write out the full HTML for including the precise files you need for your implementation.
Note: If you are loading components via the YUI Loader, this component is included in the YUI Loader package — you do not need to load it separately. If YUI Loader is on the page, so is the YAHOO Global Object.
Where these files come from: The files included using the text above will be served from Yahoo! servers. JavaScript files are minified, meaning that comments and white space have been removed to make them more efficient to download. To use the full, commented versions or the -debug
versions of YUI JavaScript files, please download the library distribution and host the files on your own server.
Order matters: As is the case generally with JavaScript and CSS, order matters; these files should be included in the order specified above. If you include files in the wrong order, errors may result.
The YAHOO Object automatically generates namespaces for
YAHOO.util
,
YAHOO.widget
,
YAHOO.env
,
YAHOO.tool
,
and YAHOO.example
. These namespaces are reserved for script
that is included in the YUI release. Additional namespaces can be created
to contain custom applications built upon the library:
// Creates a namespace for "myproduct1" YAHOO.namespace("myproduct1"); YAHOO.myproduct1.Class1 = function(info) { alert(info); }; // Creates a namespace for "myproduct2", and for "mysubproject1" YAHOO.namespace("myproduct2.mysubproject1"); YAHOO.myproduct2.mysubproject1.Class1 = function(info) { alert(info); };
// Creates a namespace for "myproduct1" YAHOO.namespace("myproduct1"); YAHOO.myproduct1.Class1 = function(info) { alert(info); }; // Creates a namespace for "myproduct2", and for "mysubproject1" YAHOO.namespace("myproduct2.mysubproject1"); YAHOO.myproduct2.mysubproject1.Class1 = function(info) { alert(info); };
YAHOO.lang
contains javascript language utilities and extensions that are used in the YUI library.
// true, an array literal is an array YAHOO.lang.isArray([1, 2]); // false, an object literal is not an array YAHOO.lang.isArray({"one": "two"}); // however, when declared as an array, it is true function() { var a = new Array(); a["one"] = "two"; return YAHOO.lang.isArray(a); }(); // false, a collection of elements is like an array, but isn't YAHOO.lang.isArray(document.getElementsByTagName("body")); // true, false is a boolean YAHOO.lang.isBoolean(false); // false, 1 and the string "true" are not booleans YAHOO.lang.isBoolean(1); YAHOO.lang.isBoolean("true"); // null is null, but false, undefined and "" are not YAHOO.lang.isNull(null); // true YAHOO.lang.isNull(undefined); // false YAHOO.lang.isNull(""); // false // a function is a function, but an object is not YAHOO.lang.isFunction(function(){}); // true YAHOO.lang.isFunction({foo: "bar"}); // false // true, ints and floats are numbers YAHOO.lang.isNumber(0); YAHOO.lang.isNumber(123.123); // false, strings that can be cast to numbers aren't really numbers YAHOO.lang.isNumber("123.123"); // false, undefined numbers and infinity are not numbers we want to use YAHOO.lang.isNumber(1/0); // true, objects, functions, and arrays are objects YAHOO.lang.isObject({}); YAHOO.lang.isObject(function(){}); YAHOO.lang.isObject([1,2]); // false, primitives are not objects YAHOO.lang.isObject(1); YAHOO.lang.isObject(true); YAHOO.lang.isObject("{}"); // strings YAHOO.lang.isString("{}"); // true YAHOO.lang.isString({foo: "bar"}); // false YAHOO.lang.isString(123); // false YAHOO.lang.isString(true); // false // undefined is undefined, but null and false are not YAHOO.lang.isUndefined(undefined); // true YAHOO.lang.isUndefined(false); // false YAHOO.lang.isUndefined(null); // false
// true, an array literal is an array YAHOO.lang.isArray([1, 2]); // false, an object literal is not an array YAHOO.lang.isArray({"one": "two"}); // however, when declared as an array, it is true function() { var a = new Array(); a["one"] = "two"; return YAHOO.lang.isArray(a); }(); // false, a collection of elements is like an array, but isn't YAHOO.lang.isArray(document.getElementsByTagName("body")); // true, false is a boolean YAHOO.lang.isBoolean(false); // false, 1 and the string "true" are not booleans YAHOO.lang.isBoolean(1); YAHOO.lang.isBoolean("true"); // null is null, but false, undefined and "" are not YAHOO.lang.isNull(null); // true YAHOO.lang.isNull(undefined); // false YAHOO.lang.isNull(""); // false // a function is a function, but an object is not YAHOO.lang.isFunction(function(){}); // true YAHOO.lang.isFunction({foo: "bar"}); // false // true, ints and floats are numbers YAHOO.lang.isNumber(0); YAHOO.lang.isNumber(123.123); // false, strings that can be cast to numbers aren't really numbers YAHOO.lang.isNumber("123.123"); // false, undefined numbers and infinity are not numbers we want to use YAHOO.lang.isNumber(1/0); // true, objects, functions, and arrays are objects YAHOO.lang.isObject({}); YAHOO.lang.isObject(function(){}); YAHOO.lang.isObject([1,2]); // false, primitives are not objects YAHOO.lang.isObject(1); YAHOO.lang.isObject(true); YAHOO.lang.isObject("{}"); // strings YAHOO.lang.isString("{}"); // true YAHOO.lang.isString({foo: "bar"}); // false YAHOO.lang.isString(123); // false YAHOO.lang.isString(true); // false // undefined is undefined, but null and false are not YAHOO.lang.isUndefined(undefined); // true YAHOO.lang.isUndefined(false); // false YAHOO.lang.isUndefined(null); // false
YAHOO.lang.hasOwnProperty
can be used to filter out properties that
were added to the Object prototype when iterating over an object
that is being used as a hash table. This feature is natively
supported across all current A-Grade browsers, but it wasn't added
to Safari until recently; all internal usage of the hasOwnProperty
test within YUI will use the version in YAHOO.lang
for the
forseeable future, and we recommend that you do the same in your own
implementations. YAHOO.lang.hasOwnProperty
will use
the native browser function unless it isn't available.
// this is what we are protecting against Object.prototype.myCustomFunction = function(x) { alert(x); } var o = {}; o["foo"] = "bar"; o["marco"] = "polo"; // this is where we need the protection for (var i in o) { if (YAHOO.lang.hasOwnProperty(o, i)) { alert("good key: " + i); } else { alert("bad key: " + i); } }
// this is what we are protecting against Object.prototype.myCustomFunction = function(x) { alert(x); } var o = {}; o["foo"] = "bar"; o["marco"] = "polo"; // this is where we need the protection for (var i in o) { if (YAHOO.lang.hasOwnProperty(o, i)) { alert("good key: " + i); } else { alert("bad key: " + i); } }
YAHOO.lang.extend
provides a simple mechanism for setting up the prototype, constructor,
and superclass properties for objects that are extending other objects.
It also prevents the constructor of the extended object (ie, the superclass) from being
executed twice. YAHOO.lang.extend
was relocated into the YAHOO.lang
package in version 2.9.0.
YAHOO.extend
is a deprecated alias for YAHOO.lang.extend
.
YAHOO.namespace("test"); YAHOO.test.Class1 = function(info) { alert("Class1: " + info); }; YAHOO.test.Class1.prototype.testMethod = function(info) { alert("Class1: " + info); }; YAHOO.test.Class2 = function(info) { // chain the constructors YAHOO.test.Class2.superclass.constructor.call(this, info); alert("Class2: " + info); }; // Class2 extends Class1. Must be done immediately after the Class2 constructor YAHOO.lang.extend(YAHOO.test.Class2, YAHOO.test.Class1); YAHOO.test.Class2.prototype.testMethod = function(info) { // chain the method YAHOO.test.Class2.superclass.testMethod.call(this, info); alert("Class2: " + info); }; var class2Instance = new YAHOO.test.Class2("constructor executed"); class2Instance.testMethod("testMethod invoked");
YAHOO.namespace("test"); YAHOO.test.Class1 = function(info) { alert("Class1: " + info); }; YAHOO.test.Class1.prototype.testMethod = function(info) { alert("Class1: " + info); }; YAHOO.test.Class2 = function(info) { // chain the constructors YAHOO.test.Class2.superclass.constructor.call(this, info); alert("Class2: " + info); }; // Class2 extends Class1. Must be done immediately after the Class2 constructor YAHOO.lang.extend(YAHOO.test.Class2, YAHOO.test.Class1); YAHOO.test.Class2.prototype.testMethod = function(info) { // chain the method YAHOO.test.Class2.superclass.testMethod.call(this, info); alert("Class2: " + info); }; var class2Instance = new YAHOO.test.Class2("constructor executed"); class2Instance.testMethod("testMethod invoked");
YAHOO.lang.augment
provides a way to reuse code by applying some or
all of the prototype properties in one object to another object. YAHOO.augment
is
a deprecated alias for YAHOO.lang.augment
.
<!-- debugger output for environments without "console" --> <div id="consoleelement"> </div>
<!-- debugger output for environments without "console" --> <div id="consoleelement"> </div>
//////////////////////////////////////////////////////////////////////////// // The ConsoleProvider example will log to the console if available, or a // div with id="consoleelement" if the console is not available //////////////////////////////////////////////////////////////////////////// YAHOO.example.ConsoleProvider = function() { }; YAHOO.example.ConsoleProvider.prototype = { log: function(msg) { // use the error console if available (FF+FireBug or Safari) if (typeof console != "undefined") { console.log(msg); // write the msg to a well-known div element } else { var el = document.getElementById("consoleelement"); if (el) { el.innerHTML += "<p>" + msg + "</p>"; } } } }; //////////////////////////////////////////////////////////////////////////// // Define a class that should be able to write debug messages //////////////////////////////////////////////////////////////////////////// YAHOO.example.ClassWithLogging = function() { }; YAHOO.lang.augment(YAHOO.example.ClassWithLogging, YAHOO.example.ConsoleProvider); //////////////////////////////////////////////////////////////////////////// // Try it out //////////////////////////////////////////////////////////////////////////// var c = new YAHOO.example.ClassWithLogging(); c.log("worked");
//////////////////////////////////////////////////////////////////////////// // The ConsoleProvider example will log to the console if available, or a // div with id="consoleelement" if the console is not available //////////////////////////////////////////////////////////////////////////// YAHOO.example.ConsoleProvider = function() { }; YAHOO.example.ConsoleProvider.prototype = { log: function(msg) { // use the error console if available (FF+FireBug or Safari) if (typeof console != "undefined") { console.log(msg); // write the msg to a well-known div element } else { var el = document.getElementById("consoleelement"); if (el) { el.innerHTML += "<p>" + msg + "</p>"; } } } }; //////////////////////////////////////////////////////////////////////////// // Define a class that should be able to write debug messages //////////////////////////////////////////////////////////////////////////// YAHOO.example.ClassWithLogging = function() { }; YAHOO.lang.augment(YAHOO.example.ClassWithLogging, YAHOO.example.ConsoleProvider); //////////////////////////////////////////////////////////////////////////// // Try it out //////////////////////////////////////////////////////////////////////////// var c = new YAHOO.example.ClassWithLogging(); c.log("worked");
YAHOO.log
is included in the Yahoo Global Object so that logging code can be
included anywhere in YUI code (or in your own code) even if the YUI Logger Control is not on the page; this prevents errors from appearing as you begin removing debugging instrumentation from your project. YAHOO.log
executes YAHOO.widget.Logger.log
if the Logger Control
is available; otherwise, it does nothing. See the documentation for
the Logger Control for more information about how to make use of it in your work.
YAHOO.namespace("test"); YAHOO.test.Class1 = function(info) { YAHOO.log("Class1: " + info, "error", "Class1"); };
YAHOO.namespace("test"); YAHOO.test.Class1 = function(info) { YAHOO.log("Class1: " + info, "error", "Class1"); };
YAHOO.env
contains information the browsing environment. In particular, it
contains information about all of the YUI components that have been loaded on
the page. This data is accessible by any component by using YAHOO.env.getVersion
,
but it is especially useful for environments where the library is dynamically loaded.
Instead of using polling techniques to determine when YAHOO
and the rest of the YUI
Library is loaded, you can define within YAHOO_config
a callback method that will be invoked every time a new YUI module is
inserted into the page. Your callback method, defined as YAHOO_config.listener
, will receive as an argument an information object containing the following information:
property | type | description |
---|---|---|
name |
string | The name of the YUI component that has just loaded. The name is an arbitrary string corresponding to a YUI component. Current YUI component names can be found in the YUI Module Names section below. |
version |
string | The version in use (e.g., "2.9.0"). |
build |
number | The build number of the current version. This is a continuously incremented integer that will grow larger with each version of the library. |
versions |
array | An array containing the string version information for all versions of this component that have been registered during the current page session. This can help identify issues that were the result of multiple versions of a module on the page. |
builds |
array | An array containing the numeric build information for all versions of this component that have been registered during the current page session. |
mainClass |
object | The principal object/class for the registered component. This object will have been stamped with its current version and build information. If mainClass.VERSION != version or mainClass.BUILD != build , multiple versions of pieces of the library have been loaded, potentially causing issues. |
In the extended code sample below, the YAHOO_config
object is used to register a listener that fires when YUI components are loaded:
<html> <head> <script type="text/javascript"> // will be called each time a module is loaded function mycallback(info) { // see the table in the documentation above for // the contents of the info object passed in here // as your argument. alert(info.name + " loaded"); // once the logger is on the page we can get to work if (info.name == "logger") { YAHOO.widget.Logger.enableBrowserConsole() var l = new YAHOO.widget.LogWriter("("); YAHOO.example.EnvTest = function() { function log(msg,cat) { var c=c||"info"; YAHOO.log(msg,c,"LangTest"); } return { init: function() { new YAHOO.widget.LogReader("logoutput"); log("init"); }, showInfo: function(e, module){ // YAHOO.env.getVersion returns the same data // object that YAHOO_config.listener receives var info = YAHOO.env.getVersion(module); log("name: " + info.name); log("version: " + info.version); log("build: " + info.build); log("versions: " + info.versions); log("builds: " + info.builds); log("mainClass version: " + info.mainClass.VERSION); } }; } (); YAHOO.util.Event.addListener(window, "load", YAHOO.example.EnvTest.init); YAHOO.util.Event.addListener("showeventbutton", "click", YAHOO.example.EnvTest.showInfo, "event"); } } YAHOO_config = { listener: mycallback }; </script> <script src = "../src/js/YAHOO.js" ></script> <script src = "http://yui.yahooapis.com/2.9.0/build/event/event.js" ></script> <script src = "http://yui.yahooapis.com/2.9.0/build/dom/dom.js" ></script> <script src = "http://yui.yahooapis.com/2.9.0/build/dragdrop/dragdrop.js" ></script> <script src = "http://yui.yahooapis.com/2.9.0/build/logger/logger.js" ></script> <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/logger/assets/logger.css"> <style> #logoutput {float: right}</style> </head> <body> <input type="button" id="showeventbutton" value="show event version" /> <div id="logoutput"></div> </body> </html>
<html> <head> <script type="text/javascript"> // will be called each time a module is loaded function mycallback(info) { // see the table in the documentation above for // the contents of the info object passed in here // as your argument. alert(info.name + " loaded"); // once the logger is on the page we can get to work if (info.name == "logger") { YAHOO.widget.Logger.enableBrowserConsole() var l = new YAHOO.widget.LogWriter("("); YAHOO.example.EnvTest = function() { function log(msg,cat) { var c=c||"info"; YAHOO.log(msg,c,"LangTest"); } return { init: function() { new YAHOO.widget.LogReader("logoutput"); log("init"); }, showInfo: function(e, module){ // YAHOO.env.getVersion returns the same data // object that YAHOO_config.listener receives var info = YAHOO.env.getVersion(module); log("name: " + info.name); log("version: " + info.version); log("build: " + info.build); log("versions: " + info.versions); log("builds: " + info.builds); log("mainClass version: " + info.mainClass.VERSION); } }; } (); YAHOO.util.Event.addListener(window, "load", YAHOO.example.EnvTest.init); YAHOO.util.Event.addListener("showeventbutton", "click", YAHOO.example.EnvTest.showInfo, "event"); } } YAHOO_config = { listener: mycallback }; </script> <script src = "../src/js/YAHOO.js" ></script> <script src = "http://yui.yahooapis.com/2.9.0/build/event/event.js" ></script> <script src = "http://yui.yahooapis.com/2.9.0/build/dom/dom.js" ></script> <script src = "http://yui.yahooapis.com/2.9.0/build/dragdrop/dragdrop.js" ></script> <script src = "http://yui.yahooapis.com/2.9.0/build/logger/logger.js" ></script> <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/logger/assets/logger.css"> <style> #logoutput {float: right}</style> </head> <body> <input type="button" id="showeventbutton" value="show event version" /> <div id="logoutput"></div> </body> </html>
Each YUI component has a corresponding module name that is used as a unique identifier within YUI scripts. For example, the Event Utility is internally referred to as "event"
. The Yahoo Global Object and other components (such as the YUILoader Utility) make use of these unique module names. Here is the full list of YUI module names.
About this Section: YUI generally works well with mobile browsers that are based on A-Grade browser foundations. For example, Nokia's N-series phones, including the N95, use a browser based on Webkit — the same foundation shared by Apple's Safari browser, which is found on the iPhone. The fundamental challenges in developing for this emerging class of full, A-Grade-derived browsers on handheld devices are:
There are other considerations, many of them device/browser specific (for example, current versions of the iPhone's Safari browser do not support Flash). The goal of these sections on YUI User's Guides is to provide you some preliminary insights about how specific components perform on this emerging class of mobile devices. Although we have not done exhaustive testing, and although these browsers are revving quickly and present a moving target, our goal is to provide some early, provisional advice to help you get started as you contemplate how your YUI-based application will render in the mobile world.
More Information:
The YAHOO global works without known issues in tested mobile environments. In a future release of the library, YAHOO.env.ua will be expanded to include detection for certain "A-Grade" mobile browsers. Until then, you can use the following code to detect a number of interesting mobile browsers:
var mobile = false, ua = navigator.userAgent, m; if (YAHOO.env.ua.webkit) { if (/ Mobile\//.test(ua)) { mobile = "iPhone"; } else { m=ua.match(/NokiaN[^\/]*/); if (m) { mobile = m[0]; // Nokia N-series, ex: NokiaN95 } } } else if (YAHOO.env.ua.opera) { m=ua.match(/Opera Mini[^;]*/); if (m) { mobile = m[0]; // ex: Opera Mini/2.0.4509/1316 } } if (!mobile) { // code here won't execute in the detected mobile browsers }
var mobile = false, ua = navigator.userAgent, m; if (YAHOO.env.ua.webkit) { if (/ Mobile\//.test(ua)) { mobile = "iPhone"; } else { m=ua.match(/NokiaN[^\/]*/); if (m) { mobile = m[0]; // Nokia N-series, ex: NokiaN95 } } } else if (YAHOO.env.ua.opera) { m=ua.match(/Opera Mini[^;]*/); if (m) { mobile = m[0]; // ex: Opera Mini/2.0.4509/1316 } } if (!mobile) { // code here won't execute in the detected mobile browsers }
The YUI Library and related topics are discussed on the on the YUILibrary.com forums.
Also be sure to check out YUIBlog for updates and articles about the YUI Library written by the library's developers.
The YUI Library's public bug tracking and feature request repositories are located on the YUILibrary.com site. Before filing new feature requests or bug reports, please review our reporting guidelines.
All YUI 2.x users should review the YUI 2.8.2 security bulletin, which discusses a vulnerability present in YUI 2.4.0-2.8.1.
Copyright © 2013 Yahoo! Inc. All rights reserved.