Delegate Controls are generic controls found in all of the out-of-the-box master pages in SharePoint, a Delegate Control provides the ability to dynamically render ASP.net controls (candidates) in master pages extending the functionality of SharePoint without the need to directly modify any of those master pages.
So Basically, a Delegate Control provides a “plug-in” framework making its child candidates (ASP.NET user Controls) pluggable and replaceable.
Some of the available delegate controls in the master pages are:
In this post we will take a look at using the AdditionalPageHead Delegate control to quickly add a jQuery reference in SharePoint master pages.
Implementing jQuery in a custom SharePoint solution where one the following is required:
- Custom validation for the out of the box Add/Edit List Forms.
- jQuery Ajax calls for external web services.
- Some Branding.
The Common Approach:
To reference scripts in SharePoint or to add them to any page, we can either modify the master page and manually add a script reference to it, or (if modifying the master page isn’t an option) we can add the script reference inside a custom web part then add the web part to all of the required pages.
Or we can use Delegate controls!
The Delegate Control Approach:
We can use a custom ASP.net User Control (that includes the script reference) in the AdditionalPageHead Delegate Control implemented through a feature, which can be activated and deactivated, sequenced or scoped (Farm, WebApp, Site Collection, Website ).
All of the out-of-the-box SharePoint master pages (v4.master, default.master, minimal.master, and nightandday.master) include the AddtioalPageHead in the HEAD section of the HTML markup:
Create a new SharePoint 2010 Empty Project:
- Name: SharePoint.jQuery
- Trust Level: Deploy as a farm solution.
- This solution will deploy the jQuery library and any other scripts to the layouts folder, and it will deploy a user control to the control templates folder, the jQuery/Scripts will be reference in that user control, and the user control will be rendered on all of the pages through the master page AdditonaPageHead delegate control.
- The final solution should include have following structure: (details on the main components are discussed further below).
Add the SharePoint Layouts mapped folder to the project, then place the following files inside the auto generated folder SharePoint.jQuery:
- jQuery-1.x.min.js (jQuery Library).
- jQuery-1.x-vsdoc.js (Optional for Visual Studio Intellisence).
- Initial file contents:
Create a new User Control:
- Name: jQueryUC.ascx
- Clear all the code inside the .ascx file and add the following lines:
- Delete the code behind file and the designer file.
Create a new SharePoint Empty Element:
- Name: SharePoint.jQuery
- File Contents:
- Here we added a Control element with a sequence, set the ControlSrc to the path of the user Control created in the previous steps, then set the Id attribute to AdditionalPageHead.
- Add the element file to the SharePoint.jQuery Feature, set the Scope to Site.
- The control declared in this element file will be selected by SharePoint foundation as a candidate control for the delegate control, and it will be instantiated .
- During runt-time the delegate control will take the union of control elements declared and based on the sequence number the delegate control will add this control to the controls tree.
That’s it! Deploy the solution and test your jQuery Code.
This is a fairly simple example, with jQuery and any other scripts libraries Implemented using delegate controls you can accomplish a lot customizations faster and efficiently, some of those are:
- Modifying OOB pages/forms without the need of creating custom ones. (Adding a text box to a form/ hiding elements in a page/ changing links in site Nav ).
- Make the page more “active”, meaning that it can respond more rapidly to user actions.
- Perform additional custom validation in OOB forms.
- Cross-reference external data sources with web services.