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