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);
})();
