Getting Started

The Get Utility's only dependency is the Yahoo Global Object. To use the Get Utility, include the following source files in your web page:

<!-- Dependencies --> 
<script src="http://yui.yahooapis.com/2.9.0/build/yahoo/yahoo-min.js" ></script>
<script src="http://yui.yahooapis.com/2.9.0/build/get/get-min.js" ></script>
 

<!-- Dependencies -->
<script src="http://yui.yahooapis.com/2.9.0/build/yahoo/yahoo-min.js" ></script>
<script src="http://yui.yahooapis.com/2.9.0/build/get/get-min.js" ></script>
 

With the Get Utility present, you can make use of it to fetch script (YAHOO.util.Get.script()) and/or CSS (YAHOO.util.Get.css()) resources to the page. The script and css methods each take the following arguments:

1. URL(s): A string or an array of strings designating the URL(s) you wish to load into the page;
2. options: An optional object containing configuration information for the transaction; see the Configuring a Get Utility Transaction section below for the full list of configuraton members you can include here.

A sample request for a file might look like this:

var objTransaction = YAHOO.util.Get.script("http://json.org/json.js", { 
    onSuccess: function() {
        alert("file loaded");
    }
});
//objTransaction will be an object with a single field, tId, 
//which is a unique identifier of the transaction following the pattern
//"q0", "q1", "q2"..."qn".
 

var objTransaction = YAHOO.util.Get.script("http://json.org/json.js", {
    onSuccess: function() {
        alert("file loaded");
    }
});
//objTransaction will be an object with a single field, tId, 
//which is a unique identifier of the transaction following the pattern
//"q0", "q1", "q2"..."qn".
 

Configuring a Get Utility Transaction

The Get Utility is configured via the second argument to the script or css method. This optional argument comprises an object containing one or more of the following fields:

Making Use of Arguments Supplied to Your Callback

As noted in the section above, your callback method (whether onSuccess or onFailure) will have access to the data member supplied in the configuration object, assuming you provided one. But the data member is just one of several fields included in the object passed to your callback. Here's a summary of the fields contained in that argument object:

All of these fields are accessible on the object passed to your onSuccess callback:

var successHandler = function(o) {
    //Here, o contains all of the fields described in the table
    //above:
    o.purge(); //removes the script node immediately after executing;
    YAHOO.log(o.data); //the data you passed in your configuration
                       //object
}
 
var objTransaction = YAHOO.util.Get.script("http://json.org/json.js", { 
    onSuccess: successHandler,
    data: {
        field1: value1,
        field2: value2
    }
});
 

var successHandler = function(o) {
    //Here, o contains all of the fields described in the table
    //above:
    o.purge(); //removes the script node immediately after executing;
    YAHOO.log(o.data); //the data you passed in your configuration
                       //object
}
 
var objTransaction = YAHOO.util.Get.script("http://json.org/json.js", {
    onSuccess: successHandler,
    data: {
        field1: value1,
        field2: value2
    }
});
 

Using the Get Utility to Insert Script Nodes

When you use the YAHOO.util.Get.script() method to add one or more script nodes to the page, the Get Utility implements the following steps:

1. A script node is appended to the target window for the first script file requested;
2. the src attribute of the new script node is set to the specified URL;
3. the script, in a successful transaction, is loaded and executed;
4. the script node's load event fires;
5. the Get Utility checks to see if more URLs remain to be loaded; if so, it recurses to step 1;
6. if this was the last of the URLs specified for this transaction, the Get Utility invokes the onSuccess callback (if one has been specified);

The following is the general code pattern used to get scripts:

var handlerData = {
    //data you wish to pass to your success or failure
    //handlers.
};
 
var successHandler = function(oData) {
    //code to execute when all requested scripts have been
    //loaded; this code can make use of the contents of those
    //scripts, whether it's functional code or JSON data.
};
 
var aURLs = [
    "/url1.js",
    "/url2.js",
    "/url3.js" //and so on
];
 
YAHOO.util.Get.script(aURLs, {
    onSuccess: successHandler,
    data:      handlerData
});
 

var handlerData = {
    //data you wish to pass to your success or failure
    //handlers.
};
 
var successHandler = function(oData) {
    //code to execute when all requested scripts have been
    //loaded; this code can make use of the contents of those
    //scripts, whether it's functional code or JSON data.
};
 
var aURLs = [
    "/url1.js",
    "/url2.js",
    "/url3.js" //and so on
];
 
YAHOO.util.Get.script(aURLs, {
    onSuccess: successHandler,
    data:      handlerData
});
 

Using the Get Utility to Insert CSS Files

When you use the YAHOO.util.Get.css() method to add one or more CSS files to the page, the Get Utility follows the same steps described above for scripts. Generally speaking, the same code pattern holds as well. Note that Firefox and Safari at present do not support the load event on link nodes, so it is possible for CSS requests to load out of order in those browsers. This can result in a different progressive display of styled in Firefox and Safari versus other browsers during CSS loading.

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

The Get Utility is fully supported on Apple's iPhone and the Nokia N-Series browsers; you can expect functional parity between their implementation and those on the supported A-Grade browsers.

Known Issues

Cross domain restriction when operating in an iframe in Internet Explorer 6

Internet Explorer 6 will not evaluate script content if the page initiating the request is in an iframe, if the source of the script is from a different domain.

Limited failure detection

Most browsers do not consider a 404 error when inserting a node a failure, and will fire the onSuccess handler in this case rather than the onFailure handler.

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.