YUI 3: YUI Global Object

Getting Started

Include Dependencies

To use the YUI Global Object, include the YUI seed file:

<script src="http://yui.yahooapis.com/3.0.0/build/yui/yui-min.js"></script>

<script src="http://yui.yahooapis.com/3.0.0/build/yui/yui-min.js"></script>

Using the YUI Global Object

This section describes how to use the YUI Global Object in further detail. It contains these subsections:

• Why the namespace change?
• YUI Core
• Use method
• Module List
• Loader

Why the namespace change?

1. Backward Compatibility: With the change from YAHOO to YUI we are guaranteed not to break backward compatibility. This allows you to use both YUI 2.x and YUI 3.x on the same page without fear of breaking existing code.
2. Sandboxing: The new YUI Global Object is now smarter than ever, allowing you to create an instance of YUI in your own namespace and only load the modules that you need. It makes it easier for multiple developers to work on different parts of the page with different modules with less worry of them stepping on each other's toes.
3. Versioning (future): In the future, we intend to version-stamp YUI modules; this will make it easier to support mulitple versions of YUI modules on the same page. While this will never be an optimal practice, it does make certain transitions easier to facilitate.
4. More Dynamic: With Loader built into the core, loading files when you need them just got easier.
5. Selector Powered: Using Selector as its base for node handling, you now get more power and ease of use for free.
6. Event Normalization: With the new Event Facade, you get maximum event normalization for cleaner cross browser code.

YUI Core

The YUI Global Object is an instantiatable object that allows you to create as many YUI instances as you need. Each completely configurable and loaded with only the modules that you need.

YUI().use('node', function(Y) {
    Y.one('#demo');
});

YUI().use('node', function(Y) {
    Y.one('#demo');
});

All of this functionality is available in the YUI Core:

Use method

The use method allows you to choose the modules that you want loaded into your YUI instance. You can pick and choose what you need, you don't have to load everything that was included on the page.

YUI().use('dd-drop', 'anim', function(Y) {
    // Y.DD is available
    // Y.Anim is available
});

YUI().use('dd-drop', 'anim', function(Y) {
    // Y.DD is available
    // Y.Anim is available
});

YUI().use('anim', function(Y) {
    // Y.DD is NOT available
    // Y.Anim is available
});

YUI().use('anim', function(Y) {
    // Y.DD is NOT available
    // Y.Anim is available
});

Use callback

You can pass a function in as the last argument to use. This function will execute after the YUI instance loads all the modules. This is required if you do not have all dependencies on the page.

The callback method has one argument passed, the YUI instance that we are dealing with. In this function you know that all the modules have been loaded and it's ok to use them.

YUI().use('animation', function(Y) {
    // Y.Anim is available
});

YUI().use('animation', function(Y) {
    // Y.Anim is available
});

Use shorthand

The use method contains a shorthand reference for all modules on the page. It uses the * as the module name.

This will load every module that is included on the page.

YUI().use('*', function(Y) {
    // Implementation code
});

YUI().use('*', function(Y) {
    // Implementation code
});

Note: This shorthand only loads modules that are already on the page. If you explicitly specify the module list on which your instance depends, YUI Loader will dynamically load any missing dependencies; this tends to be a more robust usage, because it can self-complete its requirements. Only use * if you are sure that your instance will never be used in a context in which one or more of its dependencies might be missing.

Module List

Here is a partial list of the modules and their descriptions.

Loader

Loader's functionality is now built into the YUI Global Object (as long as it's on the page) and puts its power behind the YUI.use method.

If you request a module that is not loaded on the page (or a dependency that is not loaded), loader will fetch a copy of that module (and its dependencies) and load them into your YUI instance.

YUI({
       base: '../../build/', // the base path to the YUI install
       charset: 'utf-8', // specify a charset for inserted nodes, default is utf-8
       loadOptional: true, // automatically load optional dependencies, default false
       combine: true, // use the Yahoo! CDN combo service for YUI resources, default is true unless 'base' has been changed
       filter: 'raw', // apply a filter to load the raw or debug version of YUI files
       timeout: 10000, // specify the amount of time to wait for a node to finish loading before aborting
       insertBefore: 'customstyles', // The insertion point for new nodes
       modules:  { // one or more external modules that can be loaded along side of YUI
           json_org: {
               fullpath: "http://www.json.org/json.js"
           },
           json2_org: {
               fullpath: "http://www.json.org/json2.js"
           }
       }
}).use('dd', function(Y) {
    // All YUI modules required to get drag and drop to work are now loaded.
});

YUI({
       base: '../../build/', // the base path to the YUI install
       charset: 'utf-8', // specify a charset for inserted nodes, default is utf-8
       loadOptional: true, // automatically load optional dependencies, default false
       combine: true, // use the Yahoo! CDN combo service for YUI resources, default is true unless 'base' has been changed
       filter: 'raw', // apply a filter to load the raw or debug version of YUI files
       timeout: 10000, // specify the amount of time to wait for a node to finish loading before aborting
       insertBefore: 'customstyles', // The insertion point for new nodes
       modules:  { // one or more external modules that can be loaded along side of YUI
           json_org: {
               fullpath: "http://www.json.org/json.js"
           },
           json2_org: {
               fullpath: "http://www.json.org/json2.js"
           }
       }
}).use('dd', function(Y) {
    // All YUI modules required to get drag and drop to work are now loaded.
});

The valid configuration options for Loader are as follows:

• 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).
  • 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
• jsAttributes: attributes to apply to dynamic script nodes
• cssAttributes: attributes to apply to dynamic link 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
• modules: A list of module definitions. The valid module configuration data is as follows:
  • name: required, the component name
  • type: required, the component type (js or css)
  • path: required if fullpath is not specified, the path to the script from "base"
  • fullpath: required if path isn't specified, the full path to the script. "base" will not be used to build the url
  • requires: array of modules required by this component
  • optional: array of optional modules for this component
  • supersedes: array of the modules this component replaces
  • after: array of modules the components which, if present, should be sorted above this one
  • rollup: the number of superseded modules required for automatic rollup

Lang

Lang contains javascript language utilities and extensions that are used in the YUI library.

var Y = YUI();
 
// true, an array literal is an array
Y.Lang.isArray([1, 2]);
 
// false, an object literal is not an array
Y.Lang.isArray({"one": "two"});
 
// however, when declared as an array, it is true
function() {
    var a = new Array();
    a["one"] = "two";
    return Y.Lang.isArray(a);
}();
 
// false, a collection of elements is like an array, but isn't
Y.Lang.isArray(document.getElementsByTagName("body"));
 
// true, false is a boolean
Y.Lang.isBoolean(false);
 
// false, 1 and the string "true" are not booleans
Y.Lang.isBoolean(1);
Y.Lang.isBoolean("true");
 
// null is null, but false, undefined and "" are not
Y.Lang.isNull(null); // true
Y.Lang.isNull(undefined); // false
Y.Lang.isNull(""); // false
 
// a function is a function, but an object is not
Y.Lang.isFunction(function(){}); // true
Y.Lang.isFunction({foo: "bar"}); // false
 
// true, ints and floats are numbers
Y.Lang.isNumber(0);
Y.Lang.isNumber(123.123);
 
// false, strings that can be cast to numbers aren't really numbers
Y.Lang.isNumber("123.123");
 
// false, undefined numbers and infinity are not numbers we want to use
Y.Lang.isNumber(1/0);
 
// true, objects, functions, and arrays are objects
Y.Lang.isObject({});
Y.Lang.isObject(function(){});
Y.Lang.isObject([1,2]);
 
// false, primitives are not objects
Y.Lang.isObject(1);
Y.Lang.isObject(true);
Y.Lang.isObject("{}");
 
// strings
Y.Lang.isString("{}"); // true
Y.Lang.isString({foo: "bar"}); // false
Y.Lang.isString(123); // false
Y.Lang.isString(true); // false
 
// undefined is undefined, but null and false are not
Y.Lang.isUndefined(undefined); // true
Y.Lang.isUndefined(false); // false
Y.Lang.isUndefined(null); // false

var Y = YUI();
 
// true, an array literal is an array
Y.Lang.isArray([1, 2]);
 
// false, an object literal is not an array
Y.Lang.isArray({"one": "two"});
 
// however, when declared as an array, it is true
function() {
    var a = new Array();
    a["one"] = "two";
    return Y.Lang.isArray(a);
}();
 
// false, a collection of elements is like an array, but isn't
Y.Lang.isArray(document.getElementsByTagName("body"));
 
// true, false is a boolean
Y.Lang.isBoolean(false);
 
// false, 1 and the string "true" are not booleans
Y.Lang.isBoolean(1);
Y.Lang.isBoolean("true");
 
// null is null, but false, undefined and "" are not
Y.Lang.isNull(null); // true
Y.Lang.isNull(undefined); // false
Y.Lang.isNull(""); // false
 
// a function is a function, but an object is not
Y.Lang.isFunction(function(){}); // true
Y.Lang.isFunction({foo: "bar"}); // false
 
// true, ints and floats are numbers
Y.Lang.isNumber(0);
Y.Lang.isNumber(123.123);
 
// false, strings that can be cast to numbers aren't really numbers
Y.Lang.isNumber("123.123");
 
// false, undefined numbers and infinity are not numbers we want to use
Y.Lang.isNumber(1/0);
 
// true, objects, functions, and arrays are objects
Y.Lang.isObject({});
Y.Lang.isObject(function(){});
Y.Lang.isObject([1,2]);
 
// false, primitives are not objects
Y.Lang.isObject(1);
Y.Lang.isObject(true);
Y.Lang.isObject("{}");
 
// strings
Y.Lang.isString("{}"); // true
Y.Lang.isString({foo: "bar"}); // false
Y.Lang.isString(123); // false
Y.Lang.isString(true); // false
 
// undefined is undefined, but null and false are not
Y.Lang.isUndefined(undefined); // true
Y.Lang.isUndefined(false); // false
Y.Lang.isUndefined(null); // false

Support & Community