Integrating SharePoint 2007 and jQuery [Part One]

In the first part of this article I'll talk about how you can enable the jQuery JavaScript library in SharePoint 2007 sites and pages. The second part of this article will focus on using jQuery in SharePoint 2007 sites and pages.

When I was at PDC’08, I attended a session about the jQuery JavaScript library (watch online). A few weeks before that Scott Guthrie announced that Microsoft would support, and even ship jQuery together with Visual Studio, along with Microsoft’s own AJAX implementation: ASP.NET AJAX. If you’ve never heard about jQuery, I defenitly recommend you to to check it out, there are some great tutorials available. The defenition of jQuery reads: "jQuery is a fast and concise JavaScript Library that simplifies HTML document traversing, event handling, animating, and Ajax interactions for rapid web development. jQuery is designed to change the way that you write JavaScript." In my opinion jQuery is great because it simplifies a lot the JavaScript that you have to write if you’d like to do fancy AJAX stuff, selecting HTML elements for example is a breeze. Secondly jQuery has a big community that develops plugins for various scenarios. I already wrote and talked quite a bit about integrating ASP.NET AJAX with SharePoint 2007, so let’s check out how you can integrate jQuery as well!

First things first: you need to get the jQuery library from the official website. It comes in three varieties: uncompressed (with debug information, use it while you develop), packed (smaller, use it for production) and minified (needs to be uncompressed at the client, so slower but even smaller). The jQuery library is just a JavaScript (JS) file, so it can be loaded from any web page (html, aspx, etc). If you’d like to have IntelliSense when writing code in Visual Studio 2008 for jQuery (highly recommended of course), you need to download a Visual Studio hotfix. Now you’re good to go to make use of jQuery in your development environment.

Before I show you some things you can accomplish with jQuery in your SharePoint sites, let’s think about how we can make the jQuery library available on the ASPX pages of our SharePoint sites. There are two things that need to be done: first the JS file (the library itself) should be deployed to a location which can be accessed by SharePoint pages, secondly the library should be loaded by the SharePoint pages.

Deploying the jQuery JS file is quite easy: I recommend deploying it to the C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS folder on every Front End Web Server of your SharePoint Server Farm. By doing so, the file can be loaded by making use of the URL http://yoursite/_layouts/ jquery-1.2.6.min.js or http://yoursite/subsite/_layouts/ jquery-1.2.6.min.js, since the _layouts part of the URL always points to the LAYOUTS folder in the 12-hive.

Making sure that SharePoint pages will load the library can be accomplished in a couple of ways:

1) Load the library in the page you want to use it
This can be done very easily by adding for example a Content Editor Web Part to the page (or modifying the page with an editor), containing the following HTML:

<script type="text/javascript" src="/_layouts/jquery-1.2.6.min.js"></script>

2) Add the script to the master page
You can add the same script tag to the master page that is used by your SharePoint sites as well, typically in the HEAD tag:

<HEAD runat="server">
    . . .
    <script type="text/javascript" src="/_layouts/jquery-1.2.6.min.js"></script>
    . . .
</HEAD>

This may look very easy, but remember modifying out-of-the-box files in the 12 hive is typically not supported. So if your sites use the default master page, this is a no-go. Additionally it could be that you’ve to multiple master pages (e.g. system and site master pages) which complicate the situation.

3) Use the AdditionalPageHead Delegate Control (my favorite!)
By providing the contents for the AdditionalPageHead Delegate Control that is used by all the out-of-the-box master pages, you can make sure the the jQuery library is loaded by all the SharePoint pages. The AdditionalPageHead Delegate Control allows multiple controls to provide contents, so it’s a great extensibility scenario. To accomplish this you need to build a web user control (ASCX file), that contains the script tag to load the jQuery library:

<%@ Control Language="VB" ClassName="jQueryControl" %>
<script type="text/javascript" src="/_layouts//jquery-1.2.6.min.js"></script>

There is no code-behind file required. This control needs to be deployed to the C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\CONTROLTEMPLATES folder on the hard drive of every SharePoint Front End Web Server. Additionally you need to have a feature that will add the control to the AdditionalPageHead Delegate Control, the feature’s manifest will look like this (assuming the control is named jQueryControl.ascx):

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Control
    Id="AdditionalPageHead"
    ControlSrc="~/_controltemplates/jQueryControl ascx />
</Elements>

The feature can be scoped to any level, when it’s activated on a certain level, all the pages will automatically have the script tag in their HEAD tags. Pretty cool, isn’t it?

You can do all of this manually, but it’s of course much nicer to package the jQuery library JS file, the user control and the corresponding feature into a SharePoint Solution (WSP). I’ve created a sample Solution file, that contains a feature scoped to the Web level so the jQuery library can easily be deployed and enabled or disabled per SharePoint site. There is also an installer available that guides you through the installation process by making use of a nice wizard. You can find the solution, installer and sources as a part of the SmartTools project on CodePlex (direct link to the releases).

Ok, now we are ready to make use of jQuery in our SharePoint sites, in the second part of this article I'll show you some cool stuff you can do by integrating jQuery with SharePoint 2007.

Technorati Tags: ,,,,,,

6 Comments

  • I've been using jQuery even before I started SharePoint development, and it's always been an invaluable tool. And now with SharePoint, it's incredible how easy it is to do (or perhaps hack together, depends on the point of view) things, which would be next to impossible in SharePoint itself. Looking foward to seeing your ideas.

  • Super excited to see what kind of samples or ideas you do as well.

    I created a similar pattern for deploying jQuery and we are at the cusp of having the development team using it on a more regular basis now (did some pilot stuff) so it's perfect timing to examine how other people are using it with SharePoint to make sure we are on the right path, or to get some inspiration.

    Thank you as always for posting.

  • Good stuff - the AdditionalPageHead tip is a handy idea.

    jQuery really changes the way I customise SharePoint. I have used jQuery for AJAX web service calls to get user profile data from SharePoint (a nice approach as the server setup is simple compared with deploying ASP.Net AJAX!), to customise UI elements that aren't easy to reach through CSS and themes, and am now creating a custom field for manipulating list data on the client side.

    I reckon it eases the task of developing against SharePoint as it really simplifies UI and data manipulation on the client.

  • Good one, Jan!
    I also use JQuery on our current project. I am combining approaches 2 and 3 when referencing jQuery: In our custom master page I added script reference inside tag, and I use AdditionalPageHead to reference some of jQuery plugins when needed, but without delegate control.

  • Changed from using the "Add the script to the master page" method to the "AdditionalPageHead Delegate Control" one.

    Thank you for this tip.

  • Hi Jan,

    I wanted to know how to populate list item descriptions as pop-ups flyouts using JQuery with Sharepoint 07.

    Any ideas? ??

Comments have been disabled for this content.