Wednesday, January 20, 2010

How to reference the jQuery libraries from within your SharePoint environment

If you’ve decided that you want to implement a modern client-centric approach to your SharePoint page customizations you may well decide to use jQuery as a major ingredient.  If you do then you will need to decide how to reference the jQuery library scripts from within your pages.  In this article I will show you how to use the AdditionalPageHead delegate control to implement an elegant approach to solving this puzzle.

SharePoint 2007 provides us with a very elegant way to insert items into the head section of our HTML pages. These insertions might typically be referencing additional CSS or JavaScript resources. The mechanism that is provided by SharePoint is a DelegateControl with an ID of AdditionalPageHead. The cool fact about the AdditionalPageHead delegate control is that it allows multiple controls to be injected into it!
You can read the following articles to see examples of using the AdditionalPageHead delegate control to perform these types of common tasks:
A good scenario for thinking about using this type of approach might be if you are developing a WebPart which makes use of jQuery. In this case you will want to deploy your custom WebPart as a feature and have all of the resources packaged correctly so that everything comes together at runtime. These resources include:
  • The jQuery library JavaScript files
  • Your WebPart class
  • JavaScript behaviours for your WebPart
  • CSS styles for your WebPart
You would separate out the resources that are specific to your web part from the jQuery library which should form part of the common infrastructure of your page so that other features can reference it. So we would create 2 features and deploy them separately:
  • CommonPageHeadInfrastructure - A feature that includes a custom web control which writes common JavaScript and CSS references into the page head region and a Feature definition which injects the custom control into the AdditionalPageHead delegate control.
  • CustomWebPartFeature - A feature which encapsulates the functionality of your custom web part.
The web control that you create to write out your common JS and CSS references is a simple control which inherits from Control and writes out the references from within its Render method like so:

public class PageHeadContentControl : Control
{
    protected override void Render(System.Web.UI.HtmlTextWriter writer)
    {
        writer.Write("<script type="text/javascript" src="/_layouts/1033/jquery-1.2.6.min.js"></script>") ;
    }
} 

And you would deploy that control into the delegate control using a technique similar to what is shown in this article.

As for your custom web part, you would create it as you normally would and, when creating your Child Controls, register your scripts in the typical manner with the ScriptManager like so:As for your custom web part, you would create it as you normally would and, when creating your Child Controls, register your scripts in the typical manner with the ScriptManager like so:"

var scriptPath = "/_layouts/1033/YourFeatureName/YourScriptFileName.js";
var scriptKey = "YourFeatureNameScriptIncludeKey" ;

var type = this.GetType() ;
var cs = Page.ClientScript;

if (!cs.IsClientScriptIncludeRegistered(type, scriptKey))
{
    cs.RegisterClientScriptInclude(cstype, scriptKey, scriptPath);
}  

Of course this means that you must deploy the YourScriptFileName.js file as part of your feature. You can learn about the structure for doing that by reading this article.

No comments:

Post a Comment