It's no secret that jQuery is one of the most impressive JavaScript libraries out there today. The extensibility and API for programming with jQuery is clean and light. Microsoft is even jumping on the jQuery bandwagon and jQuery will actually ship with VS2010. The merit of jQuery leads me to the topic of this blog post and I will show you my preferred way to bring jQuery to SharePoint for use in Web Parts and Page Layouts.

The Internals of the WSP


There are a few locations in the SharePoint hive that are important to note when deploying script files and controls for this solution to SharePoint:

  1. CONTROLTEMPLATES – we will be using this directory to deploy a delegate control for handling the script registration on the page.
  2. FEATURES – naturally, we will be deploying jQuery for SharePoint as SharePoint feature.
  3. LAYOUTS – this directory will be used to store the jQuery library (.js). This implementation will require that the files reside in the LAYOUTS\1033 directory (1033 is the LCID for en-US, so if you're using a different culture, this directory name will be different).

The feature references an ASCX file from the CONTROLTEMPLATES directory as a delegate control. The control will be a delegate for the AdditionalPageHead control in the SharePoint Master Page. This is configured by the CAML in controls.xml and feature.xml.

  • feature.xml
    <?xml version="1.0" encoding="utf-8" ?>
    <Feature Id="98201925-13C6-41c0-B56C-9D96A529C006"
             Title="jQuery for SharePoint"
             Description="Installs jQuery 1.3.2 into the Master Page of the site."
             Scope="Site"
             Version="1.0.0.0" 
             Hidden="FALSE" 
             DefaultResourceFile="core"
             xmlns="http://schemas.microsoft.com/sharepoint/">
      <ElementManifests>
        <ElementManifest Location="controls.xml" />
      </ElementManifests>
    </Feature>
          
  • controls.xml
    <?xml version="1.0" encoding="utf-8" ?>
    <Elements xmlns="http://schemas.microsoft.com/sharepoint/">
      <Control
        Id="AdditionalPageHead"
        ControlSrc="~/_controltemplates/jQueryForSharePoint/jQueryDelegate.ascx"
        Sequence="2" />
    </Elements>
          
  • jQueryDelegate.ascx
    <%@ Assembly Name="Aptera.Samples.jQuerySharePoint" %>
    <%@ Register Tagprefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls" Assembly="Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
    <%@ Control Language="C#" ClassName="jQueryDelegate" %>
    
    <SharePoint:ScriptLink 
      ID="jQuery" 
      Name="jQueryForSharePoint/jQuery-1.3.2.min.js" 
      runat="server" />
          

You'll notice that the control definition introduces the SharePoint ScriptLink control, which some of you may be familiar with. This control will register a JavaScript file by specifying the file name in the Name property of the control. The ScriptLink control assumes that your script files reside in the LAYOUTS\1033 folder, so the path in the Name property is relative to the LAYOUTS\1033 directory. Once we have the solution deployed, we can activate the feature from the Site Collection settings.

Now that I have the jQuery for SharePoint package installed, how can I ensure that jQuery is installed in SharePoint for any of my Web Parts or Page Layouts moving forward? We will be using activation dependencies to ensure that jQuery is activated before activating any features that depend on jQuery.

You'll notice from the solution diagram above that there is also a jQueryWebParts feature in the solution. The CAML for this feature requires that the jQueryForSharePoint feature be activated before this feature can be activated. This method can be used for any feature you deploy that requires jQuery.

<?xml version="1.0" encoding="utf-8" ?>
<Feature Id="6B6F0982-26ED-44db-B12B-3E389BCA1E16" 
         Title="jQuery Enabled Web Parts" 
         Description="A collection of Web Parts built using jQuery 1.3.2. Activation of this feature requires feature jQuery for SharePoint"
         Scope="Site"
         Version="1.0.0.0" 
         Hidden="FALSE" 
         DefaultResourceFile="core"
         xmlns="http://schemas.microsoft.com/sharepoint/">
  <ActivationDependencies>
    <!-- Require jQuery for SharePoint -->
    <ActivationDependency FeatureId="98201925-13C6-41c0-B56C-9D96A529C006"/>
  </ActivationDependencies>
  <ElementManifests>
    <ElementManifest Location="webParts.xml"/>
    <ElementFile Location="HelloPart.webpart"/>
  </ElementManifests>
</Feature>
  

As you can see, I am unable to activate my jQuery Web Parts before jQuery has been activated.

Alternatives

One alternative to using a feature to deploy jQuery is to use class resources. Class resources are files that are deployed with a SharePoint solution package that are specifically included with a Web Part, so in this case we would bundle jQuery with the Web Part. The problem with class resources for this implementation is that although they are quite handy, they require more work than does our chosen approach. The feature approach also allows us the flexibility to build applications for SharePoint in a more modular or componentized fashion.

Feel free to download the source code for this solution, but be aware that I did not use VSeWSS for this solution. Rather, I used the method that Andrew Connell uses for building solution packages. I feel that it gives me more control over the build and packaging process, so that is my avenue of choice.