Getting Started

The YAHOO Global Object must be included before any of the other script files that are part of the YUI library:

<!-- YAHOO Global Object source file --> 
<script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/yahoo/yahoo-min.js" ></script>

<!-- Additional source files go here -->

Using the Utility Methods in YAHOO

• YAHOO.namespace
• YAHOO.lang
• YAHOO.lang.hasOwnProperty
• YAHOO.lang.extend
• YAHOO.lang.augment
• YAHOO.log
• YAHOO_config and YAHOO.env
• YUI Module Names

YAHOO.namespace

The YAHOO Object automatically generataes namespaces for YAHOO.util, YAHOO.widget, 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);
};

YAHOO.lang

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

YAHOO.lang.hasOwnProperty

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);
    }
}

YAHOO.lang.extend

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.5.2. 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.lang.augment

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>

<script>
////////////////////////////////////////////////////////////////////////////
// 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");

</script>

YAHOO.log

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_config and YAHOO.env

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 inserted into the page. Your callback method, defined as YAHOO_config.listener, will receive as an argument an information object containing the following information:

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 = "../../build/event/event.js" ></script>
<script src = "../../build/dom/dom.js" ></script>
<script src = "../../build/dragdrop/dragdrop.js" ></script>
<script src = "../../build/logger/logger.js" ></script>
<link rel="stylesheet" type="text/css" href="../../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>

YUI Module Names

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.

YUI on Mobile: Using YAHOO Global Object with "A-Grade" Mobile Browsers

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 }

Support & Community

The YUI Library and related topics are discussed on the on the ydn-javascript mailing list.

In addition, please visit the YUIBlog for updates and articles about the YUI Library written by the library's developers.

Filing Bugs & Feature Requests

The YUI Library's public bug tracking and feature request repositories are located on the YUI SourceForge project site. Before filing new feature requests or bug reports, please review our reporting guidelines.

• Guidelines for YUI feature requests and bug reports.
• Review current bug list or file a new bug.
• Review current feature requests or file a new feature request.