Rick Strahl's Weblog  

Wind, waves, code and everything in between...
.NET • C# • Markdown • WPF • All Things Web
Contact   •   Articles   •   Products   •   Support   •   Advertise
Sponsored by:
Markdown Monster - The Markdown Editor for Windows

Loading jQuery Consistently in a .NET Web App


:P
On this page:

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

Posted in ASP.NET  jQuery  

The Voices of Reason


 

LaptopHeaven
October 10, 2011

# re: Loading jQuery Consistently in a .NET Web App

Calling script references explicitly with https is not a good thing. Browsers won't cache SSL content, so your request for the script will occur every time.

You can use this format, which will use the protocol used for the current page request:

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js" type="text/javascript"></script>

Betty
October 10, 2011

# re: Loading jQuery Consistently in a .NET Web App

Tip: If you skip out the protocol in script references (but leave the //) it will use the current http/https for the request.

eg

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.min.js"></script>
    <script>

Tyrone
October 10, 2011

# re: Loading jQuery Consistently in a .NET Web App

To avoid the mixed content warnings for the CDN link, you can reference the URL without specifying the protocol (http: or https:) like so:

//ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.min.js

Yes, this looks awkward; but leaving off the protocol is legal and all major browsers understand that and it would just use the current protocol to make the request.

Rick Strahl
October 10, 2011

# re: Loading jQuery Consistently in a .NET Web App

Wow I did not know you can leave out the protocol and just use // to auto-switch! Updated post to reflect that - thanks!!!

Charlie
October 10, 2011

# re: Loading jQuery Consistently in a .NET Web App

As well as the // tip everyone has mentioned, you want to move that code as far down to the end of the body as you can. You can optimise the detection a little too.

We're being picky...great blog nonetheless!

    <script src="//ajax.googleapis.com/ajax/libs/jquery/1.5.1/jquery.min.js"></script>
    <script>window.jQuery || document.write("<script src='/js/jquery/jquery- 1.5.1.min.js'>\x3C/script>")</script>
    .. other js scripts ..
  </body>
</html>

Rick Strahl
October 10, 2011

# re: Loading jQuery Consistently in a .NET Web App

@LaptopHeaven - Not sure that's correct. I see https content for scripts cached unless I do a full refresh. IE9, FF and Chrome all cache the https script reference.

LaptopHeaven
October 10, 2011

# re: Loading jQuery Consistently in a .NET Web App

@Rick After some research, I stand corrected. Browsers used to not cache ssl, but the browser landscape is changing so rapidly, it's hard to keep up.

Dave Ward
October 10, 2011

# re: Loading jQuery Consistently in a .NET Web App

I originally made the same mistake of claiming that SSL assets aren't cached to disk (because they usually aren't), but the Google CDN serves up its HTTPS copy of jQuery with headers that instruct browsers to cache it to disk.

However, the more important issue when it comes to HTTP vs. HTTPS CDN references is that they're treated as separate resources for purposes of caching. Even if you have the HTTP-loaded copy on disk, it won't be used for a cache hit if you encounter an HTTPS reference afterward (and vice versa). So, using the HTTPS reference as infrequently as possible ensures the greatest chance of that cross-site caching hit.

I wrote a bit about that here: http://encosia.com/cripple-the-google-cdns-caching-with-a-single-character/

Kieron McIntyre
October 12, 2011

# re: Loading jQuery Consistently in a .NET Web App

I was under the impression that it was best practice for scripts to be loaded at the base of the page to minimise effects on parallel loading.

Kieron McIntyre
October 12, 2011

# re: Loading jQuery Consistently in a .NET Web App

Also, it might be worth consider that by using the URL http://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js you can retrieve the latest jQuery library and not restricting yourself to a specific version.

Rick Strahl
October 12, 2011

# re: Loading jQuery Consistently in a .NET Web App

@Kieron - It's a preference. Scripts block while loading so nothing else loads until scripts have download, so yes if you have lots of scripts to load it might be a good idea to do it at the bottom of the page. With cached scripts however the overhead of loading should be minimal.

Anthony
October 16, 2011

# re: Loading jQuery Consistently in a .NET Web App

In your code example I've noticed you use string.IsNullOrEmpty. Wouldn't it be safer to use IsNullOrWhiteSpace instead?

http://msdn.microsoft.com/en-us/library/system.string.isnullorwhitespace.aspx

Rick Strahl
October 16, 2011

# re: Loading jQuery Consistently in a .NET Web App

@Anthony - possibly. Pure force of habit - IsNullOrWhiteSpace() is new in .NET 4.0 so I haven't really used it much. Frankly the intent of what's set is more important. I think IsNullOrEmpty() describes the intent better even if feature wise it's probably better to use the other. But chances of somebody using a non-empty string with only whitespace are pretty slim.

Jacob
October 31, 2011

# re: Loading jQuery Consistently in a .NET Web App

@LaptopHeaven. Browsers cache SSL get requests to RAM. You are probably confused by disk caching - which is not done by default (although some browsers like firefox can change the default).

So it's not that much of a performance hit to request the jquery script once per visit.

If you are on a SSL site, it is however a bad idea NOT to reference all resources from https because the browser will just popup security errors, turn off the lock/secure icon, or in the case of chrome, may not load your resource at all.

West Wind  © Rick Strahl, West Wind Technologies, 2005 - 2024