Getting Started

To use the YUI Loader Utility, insert its script file into the page. Note that, unlike all other YUI components, the YUI Loader Utility does not require that the Yahoo Global Object be present on the page prior to loading — in fact, the YUI Loader Utility includes the Yahoo Global Object (so you should not load both packages on the same page). The YUI Loader Utility also includes the YUI Get Utility; again, if you are using YUI Loader you should not load Get separately.

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

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

Simple Use Case: Adding YUI Components to the Page with the insert() Method

YUI Loader makes it a simple thing to get started using YUI components. Place the YUI Loader script on the page, tell it what you want to load, and let it sort out all of the dependencies on your behalf:

<!-- Load the YUI Loader script: -->
<script src="http://yui.yahooapis.com/2.9.0/build/yuiloader/yuiloader-min.js"></script>
 

<!-- Load the YUI Loader script: -->
<script src="http://yui.yahooapis.com/2.9.0/build/yuiloader/yuiloader-min.js"></script>
 

// Instantiate and configure Loader:
var loader = new YAHOO.util.YUILoader({
 
    // Identify the components you want to load.  Loader will automatically identify
    // any additional dependencies required for the specified components.
    require: ["colorpicker", "treeview"],
 
    // Configure loader to pull in optional dependencies.  For example, animation
    // is an optional dependency for slider.
    loadOptional: true,
 
    // The function to call when all script/css resources have been loaded
    onSuccess: function() {
        //this is your callback function; you can use
        //this space to call all of your instantiation
        //logic for the components you just loaded.
    },
 
    // Configure the Get utility to timeout after 10 seconds for any given node insert
    timeout: 10000,
 
    // Combine YUI files into a single request (per file type) by using the Yahoo! CDN combo service.
    combine: true
});
 
// Load the files using the insert() method. The insert method takes an optional
// configuration object, and in this case we have configured everything in
// the constructor, so we don't need to pass anything to insert().
loader.insert();
 

// Instantiate and configure Loader:
var loader = new YAHOO.util.YUILoader({
 
    // Identify the components you want to load.  Loader will automatically identify
    // any additional dependencies required for the specified components.
    require: ["colorpicker", "treeview"],
 
    // Configure loader to pull in optional dependencies.  For example, animation
    // is an optional dependency for slider.
    loadOptional: true,
 
    // The function to call when all script/css resources have been loaded
    onSuccess: function() {
        //this is your callback function; you can use
        //this space to call all of your instantiation
        //logic for the components you just loaded.
    },
 
    // Configure the Get utility to timeout after 10 seconds for any given node insert
    timeout: 10000,
 
    // Combine YUI files into a single request (per file type) by using the Yahoo! CDN combo service.
    combine: true
});
 
// Load the files using the insert() method. The insert method takes an optional
// configuration object, and in this case we have configured everything in
// the constructor, so we don't need to pass anything to insert().
loader.insert();
 

In the example above, the YUI Loader script will load from Yahoo servers, calculate the full merged dependency list for the Color Picker and TreeView Controls, load the dependencies on the page by inserting dynamic <link> and <script> nodes, and then execute your callback logic (in which you can make use of Color Picker and TreeView).

Load a Private Copy of YUI with the sandbox() Method

Different versions of the same library can sometimes conflict with each other. When you insert YUI onto a page that may have another version of the library on it already, it is sometimes preferable to use a privately-scoped copy of YUI rather than sharing it globally with the entire page. YUI Loader's sandbox method provides a way to do this.

sandbox() uses the YUI Connection Manager to fetch the script source, evaluates it inside of an anonymous function, and returns a reference to a well-known local variable that can be used without risk of having it overwritten by other code on the page. The code that is evaluated looks like this:

(function() {
 
    var YAHOO = [YUI library source];
 
    return YAHOO;
 
})();
 

(function() {
 
    var YAHOO = [YUI library source];
 
    return YAHOO;
 
})();
 

Setting up a sandbox:

<!-- Load the YUI Loader script: -->
<script src="http://yui.yahooapis.com/2.9.0/build/yuiloader/yuiloader-min.js"></script>
 

<!-- Load the YUI Loader script: -->
<script src="http://yui.yahooapis.com/2.9.0/build/yuiloader/yuiloader-min.js"></script>
 

var loader = new YAHOO.util.YUILoader();
loader.sandbox({
    require: ["treeview"], // what to load
    base: 'http://yui.yahooapis.com/2.9.0/build/', // where on my local domain the library lives
    loadOptional: true, // pull in optional components
 
    // Executed once the sandbox is successfully created
    onSuccess: function(o) {
        // o.reference is our sandboxed YAHOO object
        var ref = o.reference;
        YAHOO.log("new ref is equal to YAHOO? " + (ref === YAHOO)); // false
 
        // TreeView can now be used.  Note that YAHOO.widget.TreeView does
        // *not* exist, because it was included only on the sandboxed YAHOO
        // object.
        ref.util.Event.onAvailable("treediv", function() {
                var tree = new ref.widget.TreeView("treediv");
                var n = new ref.widget.TextNode("node 1", tree.getRoot());
                new ref.widget.TextNode("node 2", n);
                new ref.widget.TextNode("node 3", n);
                tree.draw();
            });
    }, 
 
    // Each time a resource is retrieved, onProgress will be executed
    onProgress: function(o) {
        log("progress:" + o.name);
    },
 
    // Executed if the the utility failed to create the sandbox
    onFailure: function(msg, xhrobj) {
        var m = "LOAD FAILED: " + msg;
        // if the failure was from the Connection Manager, the object
        // returned by that utility will be provided.
        if (xhrobj) {
            m += ", " + YAHOO.lang.dump(xhrobj);
        }
        YAHOO.log(m);
    },
 
    // varName: "YAHOO", // What reference should be returned? YAHOO is the default
 
    // filter: 'debug' // load the debug version of the library
});
 

var loader = new YAHOO.util.YUILoader();
loader.sandbox({
    require: ["treeview"], // what to load
    base: 'http://yui.yahooapis.com/2.9.0/build/', // where on my local domain the library lives
    loadOptional: true, // pull in optional components
 
    // Executed once the sandbox is successfully created
    onSuccess: function(o) {
        // o.reference is our sandboxed YAHOO object
        var ref = o.reference;
        YAHOO.log("new ref is equal to YAHOO? " + (ref === YAHOO)); // false
 
        // TreeView can now be used.  Note that YAHOO.widget.TreeView does
        // *not* exist, because it was included only on the sandboxed YAHOO
        // object.
        ref.util.Event.onAvailable("treediv", function() {
                var tree = new ref.widget.TreeView("treediv");
                var n = new ref.widget.TextNode("node 1", tree.getRoot());
                new ref.widget.TextNode("node 2", n);
                new ref.widget.TextNode("node 3", n);
                tree.draw();
            });
    },
 
    // Each time a resource is retrieved, onProgress will be executed
    onProgress: function(o) {
        log("progress:" + o.name);
    },
 
    // Executed if the the utility failed to create the sandbox
    onFailure: function(msg, xhrobj) {
        var m = "LOAD FAILED: " + msg;
        // if the failure was from the Connection Manager, the object
        // returned by that utility will be provided.
        if (xhrobj) {
            m += ", " + YAHOO.lang.dump(xhrobj);
        }
        YAHOO.log(m);
    },
 
    // varName: "YAHOO", // What reference should be returned? YAHOO is the default
 
    // filter: 'debug' // load the debug version of the library
});
 

This feature can be used with other JavaScript libraries as long as they conform to a pattern similiar to YUI's in which all functionality resides within a variable that is not forced into the global namespace (e.g., uses var LIBRARY instead of LIBRARY or window.LIBRARY). To sandbox something other than YUI, use the varName config to specify the reference that should be returned to the onSuccess handler.

Note: since the sandbox method uses Connection Manager to fetch the script source, it is limited by the "same origin" domain restrictions common to all XHR connections. To use the sandbox feature, you will need to serve the YUI files from the domain of the page that will use the sandbox or set up a proxy on the local domain to fetch the remote resource.

Configuration Options

The following configuration options are supported by the YUI Loader Utility. These can be set in the YUI Loader constructor, set individually on a YUI Loader instance, or provided to insert(), calculate() or sandbox():

          myFilter: {
              'searchExp': "-min\\.js",
              'replaceStr': "-debug.js"
          }
         

Using Skins with YUI Loader

YUI as of version 2.3.0 moved to a skinning model for controlling the presentation of UI controls. With that release, a default skin, sam, was introduced. By default, YUI Loader will bring in the sam assets for any YUI component you require for which a skin exists.

As we go forward, the YUI ecosystem will grow to support a number of different skins for various components. As this occurs, you'll want to be able to specify which skin you wish to use for a given component. YUI Loader allows you to specify both a global default skin (which defaults to sam unless you specify otherwise) and one or more alternative skins for each component you require. You control this using the skin property of your Loader instance.

Returning to our simple use case, here's how we might configure TreeView to use an alternative skin, myTVSkin, and Color Picker to use a skin called myCPSkin.

<!-- Load the YUI Loader script: -->
<script src="http://yui.yahooapis.com/2.9.0/build/yuiloader/yuiloader-min.js"></script>
 

<!-- Load the YUI Loader script: -->
<script src="http://yui.yahooapis.com/2.9.0/build/yuiloader/yuiloader-min.js"></script>
 

loader = new YAHOO.util.YUILoader({
    require: ["colorpicker", "treeview"],
 
    //Set your skins member here:
    skin: {
 
        // Specifies the location of the skin relative to the build
        // directory for the skinnable component.
        base: 'assets/skins/',
 
        // The default skin, which is automatically applied if not
        // overriden by a component-specific skin definition.
        // Change this in to apply a different skin globally 
        defaultSkin: 'sam',
 
        // Any component-specific overrides can be specified here,
        // making it possible to load different skins for different
        // components. It is possible to load more than one skin
        // for a given component as well.
        overrides: { 
            colorpicker: ['myCPSkin'],
            treeview: ['myTVSkin']
        }
    },
 
    onSuccess: function(o) {
        //callback logic goes here
    }
});
 
loader.insert();
 

loader = new YAHOO.util.YUILoader({
    require: ["colorpicker", "treeview"],
 
    //Set your skins member here:
    skin: {
 
        // Specifies the location of the skin relative to the build
        // directory for the skinnable component.
        base: 'assets/skins/',
 
        // The default skin, which is automatically applied if not
        // overriden by a component-specific skin definition.
        // Change this in to apply a different skin globally 
        defaultSkin: 'sam',
 
        // Any component-specific overrides can be specified here,
        // making it possible to load different skins for different
        // components. It is possible to load more than one skin
        // for a given component as well.
        overrides: {
            colorpicker: ['myCPSkin'],
            treeview: ['myTVSkin']
        }
    },
 
    onSuccess: function(o) {
        //callback logic goes here
    }
});
 
loader.insert();
 

Much more information about skinning and creating custom skins can be found in the article entitled "Skinning YUI."

Using addModule to Add Non-YUI Content with YUI Loader

YUI Loader knows all YUI components and their required and optional dependencies. When you build applications on top of YUI, you can tell YUI Loader about your own custom components and their dependencies as well using YUI Loader's addModule method.

addModule is called from a YUI Loader instance and takes as its argument a configuration object that defines the metadata associated with the module you are adding. The configuration object's members include:

//Add the module to YUILoader
loader.addModule({
    name: "json", //module name; must be unique
    type: "js", //can be "js" or "css"
    fullpath: "http://www.json.org/json2.js", //can use a path instead, extending base path
    varName: "JSON" // a variable that will be available when the script is loaded.  Needed
                    // in order to act on the script immediately in Safari 2.x and below.
    //requires: ['yahoo', 'event'] //if this module had dependencies, we could define here
});
 

//Add the module to YUILoader
loader.addModule({
    name: "json", //module name; must be unique
    type: "js", //can be "js" or "css"
    fullpath: "http://www.json.org/json2.js", //can use a path instead, extending base path
    varName: "JSON" // a variable that will be available when the script is loaded.  Needed
                    // in order to act on the script immediately in Safari 2.x and below.
    //requires: ['yahoo', 'event'] //if this module had dependencies, we could define here
});
 

When loading external scripts that you do not control, specify a varName property. YUI Loader will determine when the script is fully loaded by polling for this property. This is only needed in order to support external scripts in Safari 2.x. All other A-Grade browsers will work correctly without specifying a varName. See the addModule example and its accompanying tutorial for more information about using varName properties.

When you do control the the content, and when that content is meant to be used with YUI, the best way to notify YUI Loader that loading is complete is to use the YAHOO.register method. YAHOO.register is the same method that YUI components use to register themselves with the YAHOO object and record information about themselves in the YAHOO.env registry.

YAHOO.register takes three arguments:

1. module name: (string) must be unique, not duplicating any YUI module names or any other custom module names you may have used;
2. core class or object: a reference to the core class for this component (e.g., YAHOO.util.Anim would be the core class for the Animation Utility);
3. environment object: (object) an object containing a version member and a build member indicating the current version and build information for the component.

For example, the Animation Utility in version 2.2.2 registered itself with the following code:

YAHOO.register("animation", YAHOO.util.Anim, {
    version: "2.9.0",
    build: "204"
});
 

YAHOO.register("animation", YAHOO.util.Anim, {
    version: "2.9.0",
    build: "204"
});
 

Reminder: Use of YAHOO.register obviates the need for a varName property when loading external scripts.

Overriding skins

In version 2.4.1 of the YUILoader, defining modules that override existing YUI skins requires that you load them in two phases: 1) The YUI component, 2) The custom component:

// first load treeview
new YAHOO.util.YUILoader({
    require: ['treeview'],
    onSuccess: function() {
        // when treeview is finished loading, define and load the custom tree modules
        var loader = new YAHOO.util.YUILoader();
        // define the css module that overrides the default treeview css
        loader.addModule({
          name:'customtreecss',
          type:'css',
          fullpath:'http://domain/customtree.css',
          requires:['treeview']
        }); 
        // define the script module that extends treeview
        loader.addModule({
          name:'customtree',
          type:'js',
          fullpath:'http://domain/customtree.js',
          // make the css file a requirement for the script
          requires:['customtreecss']
        }); 
        loader.onSuccess = function() {
            // build the custom tree
        };
        loader.insert();
    }
}).insert(); // insert the treeview component immediately
 

// first load treeview
new YAHOO.util.YUILoader({
    require: ['treeview'],
    onSuccess: function() {
        // when treeview is finished loading, define and load the custom tree modules
        var loader = new YAHOO.util.YUILoader();
        // define the css module that overrides the default treeview css
        loader.addModule({
          name:'customtreecss',
          type:'css',
          fullpath:'http://domain/customtree.css',
          requires:['treeview']
        });
        // define the script module that extends treeview
        loader.addModule({
          name:'customtree',
          type:'js',
          fullpath:'http://domain/customtree.js',
          // make the css file a requirement for the script
          requires:['customtreecss']
        });
        loader.onSuccess = function() {
            // build the custom tree
        };
        loader.insert();
    }
}).insert(); // insert the treeview component immediately
 

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". YUI Loader loads components based on these unique module names. Here is the full list of YUI module names. All except YUI Loader itself can be loaded via the Loader component.

YUI ships with some aggregate or "rollup" files, each comprising two or more modules, to help you reduce the number of HTTP requests you make while loading YUI content. Each aggregate file has its own module name.

Moreover, some modules provide the functionality of one or more modules in the above list — for example, YUI Loader includes the Get Utility.

When you choose to allowRollups, YUI Loader will choose the most appropriate set of files to meet your requirements while using the smallest number of included files. You can also specify an aggregate file directly as a requirement by requesting it by its own module name. The following is a list of modules that aggregate or include multiple modules:

Migrating from 2.3.x to 2.4+

YUI Loader's API changed, and its implementation simplified in the 2.4.0 release. 2.3.x implementations that use YAHOO.util.YUILoader instances will require changing the onLoadComplete property to onSuccess. YAHOO_config is no longer supported for loading YUI components. Implementations that used YAHOO_config will need to be reworked to use a YAHOO.util.YUILoader instance.

The verifier function is no longer supported for loading external scripts. Instead you must specify a varName property to support Safari 2.x when the script doesn't use YUI's register functionality.

If you are attempting to implement a version of YUI Loader earlier than 2.4.0, refer to the API documentation and examples in the distribution for that release. Older releases are archived on YUILibrary.com.

Known Issues

Unlike other properties, the filter property can't be set directly on an instance. It must be set by passing a configuration object to either the YUILoader constructor or the insert/sandbox method.

In 2.4.1 Defining custom modules that override existing YUI skins requires a specific syntax. See the addModule section for details.

YUI on Mobile: Using YUI Loader Utility with "A-Grade" Mobile Browsers

The YUI Loader is fully supported on Apple's iPhone and the Nokia N-Series browsers; you can expect it to perform identically on those browsers relative to the supported A-Grade browsers.

Support & Community

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.

Filing Bugs & Feature Requests

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.