YUI Library Home

YUI Library Examples: YUI Loader Utility (beta): Using addModule to Add Custom (Non-YUI) Content with YUILoader

YUI Loader Utility (beta): Using addModule to Add Custom (Non-YUI) Content with YUILoader

The YUILoader Utility is designed, of course, to help you put YUI components on the page. But your applications will frequently consist of a YUI-component foundation with your own application logic built on top. In other words, when you're loading YUI components you'll often want to load your own components as well.

This example shows you how to create a custom (non-YUI) module and load it via YUILoader. Click the "Load JSON" button below to load Douglas Crockford's JSON utility from JSON.org via YUILoader. Keep an eye on the Logger Control console at right to follow the logic as it executes after you click the button.

Note: in 2.4.1 Defining custom modules that override existing YUI skins requires a specific syntax. See the example code below for details.

Using addModule to Add Custom Modules via YUILoader

The purpose of this example is to illustrate one mechanism for adding custom (non-YUI) content to the page using the YUILoader Utility. For full documentation on this feature of the YUILoader, please refer to the "Using addModule" section of the YUILoader Utility User's Guide.

Identifying an External Module to Load: The JSON Utility

Douglas Crockford, the inventor of JSON, has written a JSON Utility that helps you verify that information you've brought into the page as JSON is indeed limited to constructs that fit the JSON specification; this utility helps prevent some forms of malicious attacks embedded in JSON data from being successful in damaging you application or compromising its security.

In this example, we'll use YUILoader's addModule function to load the JSON Utility from http://www.json.org/json.js.

Invoke addModule to Make YUILoader Aware of the JSON Utility

addModule and pass in relevant metadata about our new module:

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

Note that in this case we're not setting up a dependency relationship between the JSON Utility and any other YUI components. However, in the commented-out last line above, we could use the requires member of the configuration object to make the JSON Utility depend on other YUI components or other custom components that we've defined.

Full Source for This Example

The addModule step is the most important elements of this example with respect to adding non-YUI content to the page via YUILoader. The full source of the example, including the use of the YUI Button Control to actuate the loading of the JSON Utility, follows here.

The varName property is required for external scripts that need to run in Safari 2.x or lower. This is the name a variable that the downloaded script will contain. The onSuccess handler will only be executed once this property is detected.

1<!--Container for our call-to-action button--> 
2<div id="jsonInsertButtonContainer"></div> 
3  
4<!--Container to which we'll append success message--> 
5<div id="jsonContainer"></div> 
6 
7<script type="text/javascript"> 
8//create our Button Instance which will trigger Loader to 
9//load the JSON utility from json.org. 
10YAHOO.example.buttoninit = function() { 
11 
12    //Create the button instance: 
13    var oButton = new YAHOO.widget.Button({  
14        id: "jsonInsertButton",   
15        type: "button",   
16        label: "Click here to load JSON Utility",   
17        container: "jsonInsertButtonContainer"   
18    }); 
19    YAHOO.log("Button created; click button to begin loading JSON.", "info", "example"); 
20 
21    //Create a handler that handles the button click; 
22    //it logs the click, hides the button, then fires  
23    //the function (loaderinit) that brings in JSON: 
24    var onButtonClick = function() { 
25        YAHOO.log("Button clicked; hiding button now and loading JSON", "info", "example"); 
26        YAHOO.util.Dom.setStyle("jsonInsertButtonContainer", "display", "none"); 
27        YAHOO.example.loaderinit(); 
28    } 
29     
30    //attach the handler to the Button's click event: 
31    oButton.on("click", onButtonClick); 
32}; 
33 
34//Once the jsonInsertButtonContainer element is on the page, we can create 
35//our button instance; in this case, the onContentReady deferral is unnecessary, 
36//because we're writing the element to the page before this script, 
37//but in many cases the onContentReady wrapper gives you added 
38//flexibility and it comes at low expense: 
39YAHOO.util.Event.onAvailable("jsonInsertButtonContainer",  
40                                YAHOO.example.buttoninit); 
41 
42//Once JSON is loaded, we want to simply display a message that indicates 
43//we were successful in bringing it into the page: 
44YAHOO.example.onJsonLoad = function( ){ 
45     
46    //Indicate on the page that the operation succeeded: 
47    YAHOO.util.Dom.get("jsonContainer").innerHTML = "The JSON utility was successfully loaded into the page.  Scroll through the Logger Console output at right to review the timeline of steps that were followed by the script; note that most recent log messages appear at the top."; 
48     
49    //Log the completion of the process: 
50    YAHOO.log("JSON utility was successfully loaded into the page, and the page was updated to indicate success.  The process is complete.", "info", "example"); 
51 
52}; 
53 
54YAHOO.example.loaderinit = function() { 
55    YAHOO.log("YAHOO.example.loaderinit firing; we'll define our custom JSON module and load it now.", "info", "example"); 
56     
57    //Begin by creating a new Loader instance: 
58    var loader = new YAHOO.util.YUILoader(); 
59     
60    //Add the module to YUILoader 
61    loader.addModule({ 
62        name: "json", //module name; must be unique 
63        type: "js", //can be "js" or "css" 
64        fullpath: "http://www.json.org/json2.js", //can use a path instead, extending base path 
65        varName: "JSON" // a variable that will be available when the script is loaded.  Needed 
66                        // in order to act on the script immediately in Safari 2.x and below. 
67        //requires: ['yahoo', 'event'] //if this module had dependencies, we could define here 
68    }); 
69 
70    loader.require("json"); //include the new  module 
71 
72    // set the function that should exectute when the file loads 
73    loader.onSuccess = YAHOO.example.onJsonLoad; 
74 
75    //Insert JSON utility on the page 
76    loader.insert(); 
77     
78}; 
79</script> 
view plain | print | ?

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:

1// first load treeview 
2new YAHOO.util.YUILoader({ 
3    require: ['treeview'], 
4    onSuccess: function() { 
5        // when treeview is finished loading, define and load the custom tree modules 
6        var loader = new YAHOO.util.YUILoader(); 
7        // define the css module that overrides the default treeview css 
8        loader.addModule({ 
9          name:'customtreecss', 
10          type:'css', 
11          fullpath:'http://domain/customtree.css', 
12          requires:['treeview'] 
13        });  
14        // define the script module that extends treeview 
15        loader.addModule({ 
16          name:'customtree', 
17          type:'js', 
18          fullpath:'http://domain/customtree.js', 
19          // make the css file a requirement for the script 
20          requires:['customtreecss'] 
21        });  
22        loader.onSuccess = function() { 
23            // build the custom tree 
24        }; 
25        loader.insert(); 
26    } 
27}).insert(); // insert the treeview component immediately 
28}); 
view plain | print | ?

YUI Logger Output:

Logger Console

INFO 2045ms (+2009) 8:36:59 PM:
LogReader  instance0
LogReader initialized
INFO 36ms (+36) 8:36:57 PM:
example
Button created; click button to begin loading JSON.
INFO 0ms (+0) 8:36:57 PM:
global
Logger initialized

More YUI Loader Utility (beta) Resources:

Copyright © 2008 Yahoo! Inc. All rights reserved.

Privacy Policy - Terms of Service - Copyright Policy - Job Openings