jQuery and SharePoint

jQuery is a JavaScript library. It's becoming the mainstream JavaScript framework of choice across many solutions e.g. Microsoft are taking it up for SharePoint 14, even though its an open source project and they have their own Microsoft ASP.NET AJAX framework.

Getting Started with jQuery and SharePoint

Installing jQuery into your Farm

First things first you need to find a smart way to get jQuery reference into your pages. By far the neatest way is Jan Tielens Smart Tools - SmartTools.jQuerySetup_v1_2.zip. This will add the reference as a ASCX in the 12 Hive CONTROLTEMPLATES and register it as a feature with a delegate control entry. It will also add the .js library files into your 12 hive too. Simply run setup on your SharePoint farm and you're away!

Adding Your Own Scripts

If you're doing AJAX calls, you want to load the jQuery library as soon as possible so your $.ajax (and helper method) calls can start loading while the page renders.  If you're using the *AdditionalPageHead Delegate Control*you may want to move if in the master to directly under the open HEAD tag.  If you use a < SCRIPT > tag to include jQuery, place it just under the open HEAD tag.

You also want to load other scripts asynchoronously.  Always using < SCRIPT > tags will cause each script to block the next.  A better approach is to use a $.getScript() call or dynamically create the < SCRIPT > tag and append it to the HEAD.  jQuery's $.getScript() method appends a random query string parameter to the request which prevents the browser from using the cache.  For most scripts, I prefer dynamic < SCRIPT > tags because you more frequently use the cache (304 NOT MODIFIED). 

To achieve this, your second < SCRIPT > tag in the HEAD is the loader.  The loader should load JavaScript or related CSS in parallel with the remaining SharePoint script load (e.g., core.js).  Here's an example of a loader script:

<script type="text/javascript" src="/javascripts/jquery.min.js"></script>
<script type="text/javascript">
/*
 * includeScript plugin
 * Copyright (c) 2009 Paul Grenier (endusersharepoint.com)
 * Licensed under the MIT (MIT-LICENSE.txt)
 */
(function($){
	var _debug = function(msg,type){
		if (window.console && window.console.log){
			if (!type){type="log";}
			console[type](msg);
			return true;
		}
		return false;
	};
	$.fn.includeFile = function(options, callback){
		var defaults = {"tag":"script",
						"url":"",
						"media":"screen",
						"rel":"stylesheet"
						},
			o = $.extend({},defaults,options),
			head = this[0],
			file = document.createElement(o.tag);
		switch (o.tag){
			case "script":
				file.src = o.url;
				file.type = o.type?o.type:"text/javascript";
				if (o.charset){file.charset=o.charset;}
				if (o.defer){file.defer="defer";}
				break;
			case "link":
				file.type = o.type?o.type:"text/css";
				file.rel = "stylesheet";
				file.href = o.url;
				file.media = "screen";
				if (o.target){file.target=o.target;}
				if (o.rev){file.rev=o.rev;}
				if (o.hreflang){file.hreflang=o.hreflang;}
				if (o.charset){file.charset=o.charset;}
				if (callback){_debug("not all browsers support callback for <"+o.tag+">","warn");}
				break;
			default:
				_debug("unknown tag: <"+o.tag+">","error");
				return $(this);
		}
 		file.onload = file.onreadystatechange = function(){
			if (!this.readyState || this.readyState == "loaded" || this.readyState == "complete"){
				if (callback && typeof callback=="function"){callback(o);}
				file.onload = file.onreadystatechange = null;
			}
		};
		head.appendChild(file); //using the jQuery object and append methods force an xhr
		return $(this);
	};
})(jQuery);
//end plugin

//start instructions
$("head:first")
.includeFile({"url":"/javascripts/accordion-nav.js"},function(){
	$("head:first").includeFile({"tag":"link","url":"/javascripts/leftnav.css"}); //load the css file as a callback so it degrades
})
.includeFile({"url":"/javascripts/expand-collapse-all.js"}) //another call chained from the first
.includeFile({"url":"/javascripts/ows.js"}); //end with semi-colon

//end instructions
</script>

Another benefit of this pattern is that Firebug can see all of these scripts and classes (not always possible with AJAX loads using the $.getScript or similar methods.

However, seeing a returned 304 NOT MODIFIED means that the browser is still requesting the file every time.  For further performance gain, you can edit the web.config to return "cacheable" in the response headers for certain file types.  This will eliminate the 304 NOT MODIFIED message because the browser does not make a new request.  See Optimization, BLOB caching and HTTP 304s

Debugging jQuery and SharePoint

By far the most recommended approach is a tool called FireBug. This allows you to debug your script and also jump into breakpoints and have a console window very much like the immediate window in the Visual Studio IDE.
This is a great article on how to use FireBug with jQuery. Essentially if you don't find you are hitting any breakpoints you can add to your javascript code to force it

debugger;

If you want to debug with browsers other than FireFox, then you can use the Jquery Debugger Plugin to log values directly onto the page itself into a DIV that you mark with an ID of "DEBUG". It's not as nice as FireBug, but it works across browsers.

Selecting elements on SharePoint ASPX pages with jQuery

If you're looking at jQuery in SharePoint, $("#...") selector will only return first element because IDs should be unique (however, SP often renders multiple elements with the same ID) and also because of issues with special characters, use $("[id='...']") instead e.g. $("[id='foobar']") instead of $("#foobar").

Finding stuff in the jQuery API

@Autosponge referred me to a great tool called the jQuery API which is an Adobe AIR app to find all the methods!

Using the Google AJAX Libraries API to load jQuery

jQuery can also be loaded from the Google web servers into SharePoint. This method brings the following advantages:

• Reduced bandwidth usage on your server.
• Browsers only allow a certain number of connections to the same server, so this allows another connection to be opened in parallel.
• User's browser cache may already contain the jQuery JavaScript file thanks to other sites using the Google API.
• No need to manage deployment of the jQuery JavaScript files and version can be switched easily.
• The file is downloaded from the user's nearest geographical location.

To use the API replace your existing reference to jQuery with the following:

<script type="text/javascript" src="http://www.google.com/jsapi"></script>
<script type="text/javascript">
	google.load("jquery", "1.3.2");
</script>

See more on the AJAX Libraries API site.

External References

• jQuery: the SharePoint Band Aid
• Integrating SharePoint 2007 and jQuery by Jan Tielens
• jQuery A fresh look at what you can do by Joel Oleson
• EndUserSharePoint.com - JavaScript
• Great web cast series on jQuery
• Calling SharePoint web services with JQuery

Labels

jquery jquery Delete

javascript javascript Delete

debugging debugging Delete

Enter labels to add to this page:

 

Looking for a label? Just start typing.