Loading jQuery Consistently in a .NET Web App
- by Rick Strahl
One thing that frequently comes up in discussions when using jQuery is how to best load the jQuery library (as well as other commonly used and updated libraries) in a Web application. Specifically the issue is the one of versioning and making sure that you can easily update and switch versions of script files with application wide settings in one place and having your script usage reflect those settings in the entire application on all pages that use the script. Although I use jQuery as an example here, the same concepts can be applied to any script library - for example in my Web libraries I use the same approach for jQuery.ui and my own internal jQuery support library. The concepts used here can be applied both in WebForms and MVC. Loading jQuery Properly From CDN Before we look at a generic way to load jQuery via some server logic, let me first point out my preferred way to embed jQuery into the page. I use the Google CDN to load jQuery and then use a fallback URL to handle the offline or no Internet connection scenario. Why use a CDN? CDN links tend to be loaded more quickly since they are very likely to be cached in user's browsers already as jQuery CDN is used by many, many sites on the Web. Using a CDN also removes load from your Web server and puts the load bearing on the CDN provider - in this case Google - rather than on your Web site. On the downside, CDN links gives the provider (Google, Microsoft) yet another way to track users through their Web usage. Here's how I use jQuery CDN plus a fallback link on my WebLog for example: <!DOCTYPE HTML>
<html>
<head>
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.min.js"></script>
<script>
if (typeof (jQuery) == 'undefined')
document.write(unescape("%3Cscript " + "src='/Weblog/wwSC.axd?r=Westwind.Web.Controls.Resources.jquery.js' %3E%3C/script%3E"));
</script>
<title>Rick Strahl's Web Log</title>
...
</head>
You can see that the CDN is referenced first, followed by a small script block that checks to see whether jQuery was loaded (jQuery object exists). If it didn't load another script reference is added to the document dynamically pointing to a backup URL. In this case my backup URL points at a WebResource in my Westwind.Web assembly, but the URL can also be local script like src="/scripts/jquery.min.js".
Important: Use the proper Protocol/Scheme for for CDN Urls
[updated based on comments]
If you're using a CDN to load an external script resource you should always make sure that the script is loaded with the same protocol as the parent page to avoid mixed content warnings by the browser. You don't want to load a script link to an http:// resource when you're on an https:// page. The easiest way to use this is by using a protocol relative URL:
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.min.js"></script>
which is an easy way to load resources from other domains. This URL syntax will automatically use the parent page's protocol (or more correctly scheme). As long as the remote domains support both http:// and https:// access this should work. BTW this also works in CSS (with some limitations) and links.
BTW, I didn't know about this until it was pointed out in the comments. This is a very useful feature for many things - ah the benefits of my blog to myself :-)
Version Numbers
When you use a CDN you notice that you have to reference a specific version of jQuery. When using local files you may not have to do this as you can rename your private copy of jQuery.js, but for CDN the references are always versioned. The version number is of course very important to ensure you getting the version you have tested with, but it's also important to the provider because it ensures that cached content is always correct. If an existing file was updated the updates might take a very long time to get past the locally cached content and won't refresh properly. The version number ensures you get the right version and not some cached content that has been changed but not updated in your cache.
On the other hand version numbers also mean that once you decide to use a new version of the script you now have to change all your script references in your pages.
Depending on whether you use some sort of master/layout page or not this may or may not be easy in your application. Even if you do use master/layout pages, chances are that you probably have a few of them and at the very least all of those have to be updated for the scripts. If you use individual pages for all content this issue then spreads to all of your pages. Search and Replace in Files will do the trick, but it's still something that's easy to forget and worry about.
Personaly I think it makes sense to have a single place where you can specify common script libraries that you want to load and more importantly which versions thereof and where they are loaded from.
Loading Scripts via Server Code
Script loading has always been important to me and as long as I can remember I've always built some custom script loading routines into my Web frameworks. WebForms makes this fairly easy because it has a reasonably useful script manager (ClientScriptManager and the ScriptManager) which allow injecting script into the page easily from anywhere in the Page cycle. What's nice about these components is that they allow scripts to be injected by controls so components can wrap up complex script/resource dependencies more easily without having to require long lists of CSS/Scripts/Image includes.
In MVC or pure script driven applications like Razor WebPages the process is more raw, requiring you to embed script references in the right place. But its also more immediate - it lets you know exactly which versions of scripts to use because you have to manually embed them. In WebForms with different controls loading resources this often can get confusing because it's quite possible to load multiple versions of the same script library into a page, the results of which are less than optimal…
In this post I look a simple routine that embeds jQuery into the page based on a few application wide configuration settings. It returns only a string of the script tags that can be manually embedded into a Page template.
It's a small function that merely a string of the script tags shown at the begging of this post along with some options on how that string is comprised. You'll be able to specify in one place which version loads and then all places where the help function is used will automatically reflect this selection. Options allow specification of the jQuery CDN Url, the fallback Url and where jQuery should be loaded from (script folder, Resource or CDN in my case). While this is specific to jQuery you can apply this to other resources as well. For example I use a similar approach with jQuery.ui as well using practically the same semantics.
Providing Resources in ControlResources
In my Westwind.Web Web utility library I have a class called ControlResources which is responsible for holding resource Urls, resource IDs and string contants that reference those resource IDs. The library also provides a few helper methods for loading common scriptscripts into a Web page. There are specific versions for WebForms which use the ClientScriptManager/ScriptManager and script link methods that can be used in any .NET technology that can embed an expression into the output template (or code for that matter).
The ControlResources class contains mostly static content - references to resources mostly. But it also contains a few static properties that configure script loading:
A Script LoadMode (CDN, Resource, or script url)
A default CDN Url
A fallback url
They are static properties in the ControlResources class:
public class ControlResources
{
/// <summary>
/// Determines what location jQuery is loaded from
/// </summary>
public static JQueryLoadModes jQueryLoadMode = JQueryLoadModes.ContentDeliveryNetwork;
/// <summary>
/// jQuery CDN Url on Google
/// </summary>
public static string jQueryCdnUrl = "//ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.min.js";
/// <summary>
/// jQuery CDN Url on Google
/// </summary>
public static string jQueryUiCdnUrl = "//ajax.googleapis.com/ajax/libs/jqueryui/1.8.16/jquery-ui.min.js";
/// <summary>
/// jQuery UI fallback Url if CDN is unavailable or WebResource is used
/// Note: The file needs to exist and hold the minimized version of jQuery ui
/// </summary>
public static string jQueryUiLocalFallbackUrl = "~/scripts/jquery-ui.min.js";
}
These static properties are fixed values that can be changed at application startup to reflect your preferences. Since they're static they are application wide settings and respected across the entire Web application running. It's best to set these default in Application_Init or similar startup code if you need to change them for your application:
protected void Application_Start(object sender, EventArgs e)
{
// Force jQuery to be loaded off Google Content Network
ControlResources.jQueryLoadMode = JQueryLoadModes.ContentDeliveryNetwork;
// Allow overriding of the Cdn url
ControlResources.jQueryCdnUrl = "http://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js";
// Route to our own internal handler
App.OnApplicationStart();
}
With these basic settings in place you can then embed expressions into a page easily.
In WebForms use:
<!DOCTYPE html>
<html>
<head runat="server">
<%= ControlResources.jQueryLink() %>
<script src="scripts/ww.jquery.min.js"></script>
</head>
In Razor use:
<!DOCTYPE html>
<html>
<head>
@Html.Raw(ControlResources.jQueryLink())
<script src="scripts/ww.jquery.min.js"></script>
</head>
Note that in Razor you need to use @Html.Raw() to force the string NOT to escape. Razor by default escapes string results and this ensures that the HTML content is properly expanded as raw HTML text.
Both the WebForms and Razor output produce:
<!DOCTYPE html>
<html>
<head> <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js" type="text/javascript"></script>
<script type="text/javascript"> if (typeof (jQuery) == 'undefined')
document.write(unescape("%3Cscript src='/WestWindWebToolkitWeb/WebResource.axd?d=-b6oWzgbpGb8uTaHDrCMv59VSmGhilZP5_T_B8anpGx7X-PmW_1eu1KoHDvox-XHqA1EEb-Tl2YAP3bBeebGN65tv-7-yAimtG4ZnoWH633pExpJor8Qp1aKbk-KQWSoNfRC7rQJHXVP4tC0reYzVw2&t=634535391996872492' type='text/javascript'%3E%3C/script%3E"));</script>
<script src="scripts/ww.jquery.min.js"></script>
</head>
which produces the desired effect for both CDN load and fallback URL.
The implementation of jQueryLink is pretty basic of course:
/// <summary>
/// Inserts a script link to load jQuery into the page based on the jQueryLoadModes settings
/// of this class. Default load is by CDN plus WebResource fallback
/// </summary>
/// <param name="url">
/// An optional explicit URL to load jQuery from. Url is resolved.
/// When specified no fallback is applied
/// </param>
/// <returns>full script tag and fallback script for jQuery to load</returns>
public static string jQueryLink(JQueryLoadModes jQueryLoadMode = JQueryLoadModes.Default, string url = null)
{
string jQueryUrl = string.Empty;
string fallbackScript = string.Empty;
if (jQueryLoadMode == JQueryLoadModes.Default)
jQueryLoadMode = ControlResources.jQueryLoadMode;
if (!string.IsNullOrEmpty(url))
jQueryUrl = WebUtils.ResolveUrl(url);
else if (jQueryLoadMode == JQueryLoadModes.WebResource)
{ Page page = new Page(); jQueryUrl = page.ClientScript.GetWebResourceUrl(typeof(ControlResources), ControlResources.JQUERY_SCRIPT_RESOURCE);
}
else if (jQueryLoadMode == JQueryLoadModes.ContentDeliveryNetwork)
{
jQueryUrl = ControlResources.jQueryCdnUrl;
if (!string.IsNullOrEmpty(jQueryCdnUrl))
{
// check if jquery loaded - if it didn't we're not online and use WebResource
fallbackScript =
@"<script type=""text/javascript"">if (typeof(jQuery) == 'undefined')
document.write(unescape(""%3Cscript src='{0}' type='text/javascript'%3E%3C/script%3E""));</script>";
fallbackScript = string.Format(fallbackScript, WebUtils.ResolveUrl(ControlResources.jQueryCdnFallbackUrl));
}
}
string output = "<script src=\"" + jQueryUrl + "\" type=\"text/javascript\"></script>";
// add in the CDN fallback script code
if (!string.IsNullOrEmpty(fallbackScript))
output += "\r\n" + fallbackScript + "\r\n";
return output;
}
There's one dependency here on WebUtils.ResolveUrl() which resolves Urls without access to a Page/Control (another one of those features that should be in the runtime, not in the WebForms or MVC engine).
You can see there's only a little bit of logic in this code that deals with potentially different load modes. I can load scripts from a Url, WebResources or - my preferred way - from CDN. Based on the static settings the scripts to embed are composed to be returned as simple string <script> tag(s).
I find this extremely useful especially when I'm not connected to the internet so that I can quickly swap in a local jQuery resource instead of loading from CDN. While CDN loading with the fallback works it can be a bit slow as the CDN is probed first before the fallback kicks in. Switching quickly in one place makes this trivial. It also makes it very easy once a new version of jQuery rolls around to move up to the new version and ensure that all pages are using the new version immediately.
I'm not trying to make this out as 'the' definite way to load your resources, but rather provide it here as a pointer so you can maybe apply your own logic to determine where scripts come from and how they load. You could even automate this some more by using configuration settings or reading the locations/preferences out of some sort of data/metadata store that can be dynamically updated instead via recompilation.
FWIW, I use a very similar approach for loading jQuery UI and my own ww.jquery library - the same concept can be applied to any kind of script you might be loading from different locations. Hopefully some of you find this a useful addition to your toolset.
Resources
Google CDN for jQuery
Full ControlResources Source Code
ControlResource Documentation
Westwind.Web NuGet
This method is part of the Westwind.Web library of the West Wind Web Toolkit or you can grab the Web library from NuGet and add to your Visual Studio project. This package includes a host of Web related utilities and script support features.
© Rick Strahl, West Wind Technologies, 2005-2011Posted in ASP.NET jQuery
Tweet
(function() {
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
po.src = 'https://apis.google.com/js/plusone.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
})();
