If you’ve already begun using Microsoft’s new Ajax Script Loader with a CDN-hosted version of jQuery, today’s release of jQuery 1.4 may have left you wondering how to upgrade. Personally, I didn’t want to wait on a new version of Start.js, nor did I want to abandon the script loader now that I’ve become accustomed to its benefits.

No doubt, an upcoming ASP.NET Ajax Library iteration will update Start.js’ jQuery definition to reference jQuery 1.4.x. Regardless, knowing how to patch the script loader on your own terms is something that will be of recurring usefulness.

Luckily, the script loader is open and extensible enough that it’s possible to change which script versions are used. So, I want to briefly show you how the script loader defines JavaScript includes and how you can patch those definitions without modifying Start.js itself.

Using the script loader to inject jQuery

If you aren’t familiar with the script loader itself or with using it to asynchronously request jQuery, I recommend checking out its documentation and examples on the new ASP.NET Ajax Wiki.

To use it most basically, simply include a reference to Start.js either locally or on the Microsoft CDN, and then use this JavaScript to instruct the script loader to inject jQuery into the page:

// Instruct the script loader to request
//  jQuery in the background.
Sys.require(Sys.scripts.jQuery);
 
// This callback runs later, after jQuery
//  has been asynchronously loaded.
Sys.onReady(function () {
  console.log("Loaded jQuery " + jQuery.fn.jquery);
});

Monitoring the request in Firebug illuminates what that Sys.require statement triggered in the background:

As you can see, the end result is pretty straightforward. The primary benefit of this asynchronous loading technique is that scripts loaded through the script loader are non-blocking and may be loaded in parallel. By contrast, JavaScript includes referenced through HTML script elements block all rendering and further requests until they are parsed and executed. The difference is often significant.

Now, if only it were injecting jQuery 1.4 instead of 1.3.2.

Understanding how Sys.scripts.jQuery is defined

The Sys.scripts.jQuery parameter to the script loader is actually just a JavaScript object that defines a few parameters about the include. Here is how that is defined in Start.js (edited slightly for readability here):

var path = (window.location.protocol === "https" ? "https" : "http") 
           + "://ajax.microsoft.com/ajax/";
 
loader.defineScripts(null, [
 { name: "jQuery",
   releaseUrl: path + "jquery/jquery-1.3.2.min.js",
   debugUrl: path + "jquery/jquery-1.3.2.js",
   isLoaded: !!window.jQuery
 }
]);

If you’re using a local copy of Start.js, one option is to modify this jQuery script definition inside Start.js itself. However, I discourage that alternative. Not only would it require constant, manual maintenance after every new release, but it isn’t an option when using the Microsoft Ajax CDN’s copy of Start.js.

Defining a new target for it

Another option is to simply modify the Sys.scripts.jQuery object itself. Letting Start.js initialize the definition with jQuery 1.3.2’s path doesn’t hurt anything as long as we redefine it before calling Sys.require.

Inspecting the Sys.scripts collection in Firebug reveals how straightforward that modification will be:

Thanks to to the power of interactively interrogating the object in Firebug, it becomes clear that updating the releaseUrl and debugUrl properties of that object should be all that is necessary.

Updating the example to use jQuery 1.4

Because jQuery 1.4 isn’t available on the Microsoft CDN yet, I’m going to target Google’s AJAX Libraries CDN for jQuery instead. Once Microsoft’s CDN is updated with jQuery 1.4.x, this approach will work for either CDN.

// These re-definitions must be executed after 
//  Start.js, but before Sys.require.
var CDN = "http://ajax.googleapis.com/ajax/libs";
 
Sys.scripts.jQuery.releaseUrl = CDN + "/jquery/1.4.1/jquery.min.js";
Sys.scripts.jQuery.debugUrl   = CDN + "/jquery/1.4.1/jquery.js";
 
// Instruct the script loader to request
//  jQuery in the background.
Sys.require(Sys.scripts.jQuery);
 
// This callback runs later, after jQuery
//  has been asynchronously loaded.
Sys.onReady(function () {
  console.log"Loaded jQuery " + jQuery.fn.jquery);
});

That’s all there is to it. Reviewing the requests in Firebug again, you can see that the same Sys.require statement is indeed now loading jQuery 1.4 from Google’s CDN:

Bonus: jQuery Validate 1.6

As I write this, Start.js’ definition for Sys.scripts.jQueryValidate is still targeting version 1.5.5 of the plugin, but 1.6 is the current version.

Using what’s been covered in this post, pointing the script loader at the newest version of jQuery Validate is no problem:

var MSCDN = "http://ajax.microsoft.com/ajax";
var GoogCDN = "http://ajax.googleapis.com/ajax/libs";
 
// Please forgive my ugly formatting to make this fit. Do not try 
//  this at home (unless your editor is only 492px too).
Sys.scripts.jQuery.releaseUrl = 
  GoogCDN + "/jquery/1.4.1/jquery.min.js";
Sys.scripts.jQuery.debugUrl = 
  GoogCDN + "/jquery/1.4.1/jquery.js";
 
Sys.scripts.jQueryValidate.releaseUrl = 
  MSCDN + "/jQuery.Validate/1.6/jQuery.Validate.min.js";
Sys.scripts.jQueryValidate.debugUrl = 
  MSCDN + "/jQuery.Validate/1.6/jQuery.Validate.js";
 
// Instruct the script loader to request
//  jQuery and jQuery Validate in the background.
Sys.require([Sys.scripts.jQuery, Sys.scripts.jQueryValidate]);
 
// This callback runs later, after both jQuery
//  and jQuery Validate have been loaded.
Sys.onReady(function () {
  console.log("Loaded jQuery " + jQuery.fn.jquery);
});

The jQuery Validate situation is a good example of why knowing how to update these script definitions yourself is worthwhile. Because the script loader was designed to be so flexible, there’s no need to wait on a new release of Start.js or give up its benefits.