HOW TO Load a Custom Script with Dependencies

http://www.asp.net/ajaxLibrary/HOW%20TO%20Load%20a%20Custom%20Script%20with%20Dependencies.ashx

HOW TO Load a Custom Script with Dependencies

The ASP.NET Ajax Library Script Loader can be used to load Microsoft scripts, jQuery scripts and even custom scripts. By using the Script Loader you can take advantage of parallel script loading which allows pages to load more quickly and also handle script dependencies more easily. Custom scripts can be loaded using the standard <script> element or by calling  Sys.loadScripts which accepts a path to the script that should be loaded. However, neither of these techniques automatically handles loading dependencies that a script may have. A common example of script dependencies can be seen with the various jQuery plug-ins that are available. Each plug-in script has a dependency on jQuery and it's important that the scripts are loaded after jQuery has been loaded. In other cases a script may define a function called Calculate that in turn calls a function located in another script. The order that these scripts are loaded in doesn't matter as long as both functions are available once the Calculate function is called by the program.

In cases where a custom script has dependencies on one or more scripts a custom metadata file can be created to define the dependencies. This metadata file can define all the scripts involved using the Script Loader's  Sys.loader.defineScripts function. The metadata script defines the custom scripts to load as well as any dependencies they may have. Dependencies that a script has can be defined using the "dependencies" property or the "executionDependencies" property. Additional details about each property are shown next:

dependencies: Use this property when a dependency script must be loaded before a custom script can be loaded. Dependencies must be loaded in sequential order, one after the other, to ensure correct execution order and that each script has its dependencies when it executes. Using this property causes the Script Loader to load scripts in serial.

executionDependencies: An executionDependency must be loaded by the time the custom script is actually used in a page but does not have to be loaded first. For example, if a script contains a function that uses a function defined in another script, it only has an ‘execution dependency’ on the other script so it is acceptable to load the function before the other. This is the best approach to take whenever possible since it allows the Script Loader to load scripts in parallel which minimizes a page's load time.

An example of using the Script Loader's defineScripts method is shown next. This example loads the jQuery UI script which has a dependency on jQuery (jQuery must be loaded first):

view plain copy to clipboard print ?

1. Sys.loader.defineScripts(null,  
2. [  
3.     {  
4.         name: "jQueryUI",  
5.         releaseUrl: "/Content/Scripts/jquery-ui-1.7.1.custom.min.js",  
6.         debugUrl: "/Content/Scripts/jquery-ui-1.7.1.custom.js",  
7.         dependencies: ["jQuery"]  
8.         isLoaded: !!(window.jQuery && jQuery.ui)  
9.     }  
10. ]);  

The name property defines how the scripts will be refenced using the Script Loader. For example, to use the jQuery UI script the following call can be made:

Sys.require(Sys.scripts.jQueryUI);

The releaseUrl and debugUrl properties define the path to the respective release and debug versions of the script. The version loaded depends on the value of the Sys.debug property which is false by default when using the ' start.js' script and true by default when using the 'start.debug.js' script. A debugUrl need not be provided, in which case the releaseUrl would always be used. The dependencies property defines that jQuery (which is defined in the start.js file) is a dependency that must be loaded first. Finally, the isLoaded property ensures that the jQuery UI script is only loaded once by checking for the existence of jQuery.ui in the DOM, in case it has already been included via a <script> element. 

The following code demonstrates how multiple jQuery plug-ins and a custom script all with a dependency on jQuery can be defined using defineScripts. Notice that the dependencies property value is passed as the first parameter to defineScripts since each script has a requirement on jQuery. Although it can be defined on each script as shown earlier, defining it in one place reduces duplication and results in a smaller file. The first parameter is a set of default values to apply to each of the scripts you define.

view plain copy to clipboard print ?

1. Sys.loader.defineScripts({  
2.    dependencies: ["jQuery"]   
3. },  
4. [  
5.     {  
6.         name: "jQueryUI",  
7.         releaseUrl: "/Scripts/jquery-ui-1.7.1.custom.min.js",  
8.         debugUrl: "/Scripts/jquery-ui-1.7.1.custom.js",  
9.         isLoaded: !!(window.jQuery && jQuery.ui)  
10.     },  
11.     {  
12.         name: "jQueryExtensions",  
13.         releaseUrl: "/Scripts/jquery.extensions.js",  
14.         isLoaded: !!(window.jQuery && jQuery.fn.convertNullToEmptyString)  
15.     },  
16.     {  
17.         name: "jQueryInputMask",  
18.         releaseUrl: "/Scripts/jquery.maskedinput-1.2.2.min.js",  
19.         debugUrl: "/Scripts/jquery.maskedinput-1.2.2.js",  
20.         isLoaded: !!(window.jQuery && jQuery.fn.mask)  
21.     },  
22.     {  
23.         name: "jQueryNumeric",  
24.         releaseURl: /Scripts/jquery.numeric.js",  
25.         isLoaded: !!(window.jQuery && jQuery.fn.numeric)  
26.     },  
27.     {  
28.         name: "jQueryBlockUI",  
29.         releaseUrl: "/Scripts/jquery.blockui.js",  
30.         isLoaded: !!(window.jQuery && jQuery.fn.block)  
31.     },  
32.     {  
33.         name: "jQueryBgIFrame",  
34.         releaseUrl: "/Scripts/jquery.bgiframe.min.js",  
35.         debugUrl: "/Scripts/jquery.bgiframe.js",  
36.         isLoaded: !!(window.jQuery && jQuery.fn.bgIframe)  
37.     },  
38.     {  
39.         name: "orderScript",  
40.         releaseUrl: "/Scripts/Order.js",  
41.         isLoaded: !!window.AttachMasks  
42.     }  
43. ]);  

Figure 1 shows the order in which the scripts are loaded once the metadata file is loaded by the Script Loader. Note that jQuery is loaded before all of the other scripts that require it.



Figure 1. By using a metadata file dependencies can be defined and loaded in the proper order.

In cases where a script has a dependency that doesn't need to be loaded first the executionDependencies property can be used. For example, if a script named Calculations.js has a function that calls a function located in a separate file named Rules.js the following metadata file can be created:

view plain copy to clipboard print ?

1. //AppScriptsRegister.js   
2. Sys.loader.defineScripts(null,  
3. [  
4.     {  
5.         name: "Calculations",  
6.         releaseUrl: "../Scripts/Calculations.js",  
7.         debugUrl: "../Scripts/Calculations.debug.js",  
8.         executionDependencies: ["Rules"],  
9.         isLoaded: !!window.Add  
10.     },  
11.     {  
12.         name: "Rules",  
13.         releaseUrl: "../Scripts/Rules.js",  
14.         debugUrl: "../Scripts/Rules.debug.js",  
15.         isLoaded: !!window.Validate  
16.     }  
17. ]);  

This example allows the Script Loader to load the Calculations.js and Rules.js scripts in parallel. The Calculations.js can be loaded with the Script Loader using the following code:

view plain copy to clipboard print ?

1. <script src="../Scripts/Start.js" type="text/javascript"></script>  
2. <script src="../Scripts/AppScriptsRegister.js" type="text/javascript"></script>  
3. <script type="text/javascript">  
4.   
5.     Sys.require([Sys.scripts.Calculations]);  
6.   
7.       
8. </script>