New Delegate controls in Sharepoint 2013

For Seattle.master, I’ve found these three new DelegateControls

• PromotedActions
• the top-right section of the page
•  
•  
• SuiteBarBrandingDelegate
• allow you to override the content that is displayed in the top-left corner of every site. Normally, there’s a text reading "SharePoint" like this
• 
• SuiteLinksDelegate 
• allow us to modify the default links, and to add our own links, in the "suit links" section
• 

Reference: 

SharePoint Delegate Control with example

General delegates are also called as ambassadors, diplomats, representatives etc.
SharePoint has a couple of delegate controls like

1. AdditionalPageHead
2. GlobalSiteLink0
3. GlobalSiteLink1
4. GlobalSiteLink2
5. PublishingConsole
6. QuickLaunchDataSource
7. SmallSearchInputBox
8. TopNavigationDataSource

Apart from the above controls, we can also create our own custom delegate controls
The XML schema for delegate control is below:

<?xml version="1.0" encoding="utf-8" ?> <Elements xmlns="http://schemas.microsoft.com/sharepoint/">  <Control Id="SmallSearchInputBox" Sequence="100" Url="/templates/mysearchcontrol.ascx"/> </Elements>

In above, properties for the delegate control as Control Id, Sequence and URL. We identify the delegate controls based on Control Id, Sequence number. The Sequence number defines the rank of the delegate, URL describes the source location of the control.
delegate control who’s Sequence id is less has most significant role in SharePoint site and will render on the site as first preference.
 What is the use of delegate control?
Using the delegate control a developer can customize the SharePoint site controls without editing or even touching the master page.
Note: We are not customizing the existing (default) delegate control but we are creating our own control loading onto the SharePoint site.

Let’s suppose assume one scenario, if we want to customize the SharePoint search box (by default SharePoint 2010 site has got input search box with one textbox and one button beside) see figure 1

Figure 1 – SharePoint 2010 Default Search Box

Now I will try to customize the default search box, the requirement is to display the search box with scope drop down list, and also customizing the search button image with a arrow image button.
First open Visual Studio 2010 and click New > Project see figure 2

Figure 2 – Creating New Visual Studio 2010 Project

After project got created, I have deleted the not in use file (you can keep it there won’t be any problem if you don’t delete) because of maintaing clean solution I have removed user control, webpart related files see figure 3

Figure 3 – Solution Explorer File Structure

Then add the following code in Elements.xml file

<?xml version="1.0" encoding="utf-8"?> <Elements xmlns="http://schemas.microsoft.com/sharepoint/" >   <!--<Module Name="VisualWebPart1" List="113" Url="_catalogs/wp">     <File Path="VisualWebPart1\VisualWebPart1.webpart" Url="CustomDelegateControl_VisualWebPart1.webpart" Type="GhostableInLibrary" >       <Property Name="Group" Value="Custom" />     </File>   </Module>-->   <Control      Id="SmallSearchInputBox"      Sequence="23"      ControlClass="Microsoft.SharePoint.Portal.WebControls.SearchBoxEx"      ControlAssembly="Microsoft.Office.Server.Search, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c">     <Property Name="QueryPromptString">This control is customized.....</Property>     <Property Name="SearchBoxTableClass">search-box</Property>     <Property Name="GoImageUrl">/_layouts/images/goviewfiles.png</Property>     <Property Name="GoImageUrlRTL">/_layouts/images/goviewfiles.png</Property>     <Property Name="GoImageActiveUrl">/_layouts/images/goviewfiles.png</Property>     <Property Name="GoImageActiveUrlRTL">/_layouts/images/goviewfiles.png</Property>     <Property Name="UseSiteDefaults">true</Property>     <Property Name="FrameType">None</Property>   </Control> </Elements>

In the Element.xml file I have commented the Module section see figure 4

Figure 4 – Custom Delegate Control Element.xml file

Now we are almost done, try to build, deploy and activate the feature which will result in change of SharePoint default search box with your customized control on fly without modifying the master page see figure 5

Figure 5 – SharePoint 2010 Custom Search Input Box

Delegate Control & its use in sharepoint 2010

The Delegate Controls comes into picture when want to brand a SharePoint Site. The delegate control acts like a container control which encapsulates default content (set of child controls inside it). The default content (set of child controls associated with delegate) can be substituted by a specific control, by creating a feature. The ability to override or substitute the delegate controls brings the power & flexibility to brand SharePoint Sites.

The out-of-box SharePoint Foundation Master Page defines many controls like Top Navigation Data Source, Left Navigation Data Source, Search Box and Additional Page Head etc as delegate controls. 

Replace SharePoint 2010 Search Box using Delegate Control

The list is illustrated below :-

<SharePoint:DelegateControl runat="server" ControlId="AdditionalPageHead" 

AllowMultipleControls="true"/>

<SharePoint:DelegateControl runat="server" ControlId="GlobalNavigation" />

<SharePoint:DelegateControl runat="server" ID="GlobalDelegate0" ControlId="GlobalSiteLink0" />

<SharePoint:DelegateControl ControlId="GlobalSiteLink2" ID="GlobalDelegate2" Scope="Farm"

 runat="server" />

<SharePoint:DelegateControl runat="server" ControlId="PublishingConsole" 

Id="PublishingConsoleDelegate">

</SharePoint:DelegateControl><SharePoint:DelegateControl ControlId="GlobalSiteLink3" Scope="Farm" 

runat="server" />

<SharePoint:DelegateControl runat="server" ControlId="SmallSearchInputBox" Version="4" />

<SharePoint:DelegateControl runat="server" ControlId="TopNavigationDataSource" 

Id="topNavigationDelegate"/>
    

The above listed delegate controls can be substituted at runtime to achieve custom branding. Let’s try to replace the Small Search Input box and see how the delegate control helps for this process. The whole idea is to define a feature for the Custom User Control with same control id mentioned in delegate and the lowest possible sequence number.

Here are the steps below :-
File ---> New Project ---> Empty SharePoint Project
Right Click Project –> Add New item –> User Control . Name it as ‘ReplaceSearchBox’

It automatically creates control templates folder and places the user control underneath that. Create any arbitrary control inside the user control. For the illustration purpose, I’ll add a Calendar Control inside the user control, to visually show a difference how the page looks after the delegate substitution.

<asp:Calendar ID="Calendar1" runat="server"></asp:Calendar>

It automatically creates control templates folder and places the user control underneath that.

Right Click Features –> Add Feature
Set the Feature Scope at Site (site-collection level)
Right Click Solution ---> Add New Item –> Empty Element

We’d be leveraging Elements.xml file for the delegate substitution process. Before jumping on to the substitution lets understand how the out-of-box Search Box is defined using Feature.

The Search Box is defined in both the Features ‘OSearchBasicFeature’ and ‘OSearchEnhancedFeature’ in the location 

C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\FEATURES

The definition looks like the following :-

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <Control 
        Id="SmallSearchInputBox" 
        Sequence="50"
        ControlClass="Microsoft.SharePoint.Portal.WebControls.SearchBoxEx" 

ControlAssembly="Microsoft.Office.Server.Search, Version=14.0.0.0, Culture=neutral, 

PublicKeyToken=71e9bce111e9429c">

    <Property Name="GoImageUrl">/_layouts/images/gosearch15.png</Property>
    <Property Name="GoImageUrlRTL">/_layouts/images/gosearchrtl15.png</Property>
    <Property Name="GoImageActiveUrl">/_layouts/images/gosearchhover15.png</Property>
    <Property Name="GoImageActiveUrlRTL">/_layouts/images/gosearchrtlhover15.png</Property>
    <Property Name="DropDownMode">ShowDD</Property>
        <Property Name="SearchResultPageURL">/_layouts/osssearchresults.aspx</Property>
    <Property Name="ScopeDisplayGroupName"></Property>
    <Property Name="FrameType">None</Property>
    </Control>    
</Elements>

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">

Here the Id & Sequence number of the control plays an important role. 

To substitute this out-of-box SmallSearchInput box, Let’s define Elements.xml file for Feature. The id of the control should match with id of control to be replaced. 

The Sequence number should be less than the sequence number of the out-of-box control. In this case we’re assigning sequence number as 10, so that the control with the lowest

 sequence number gets precedence.

    <Control Id="SmallSearchInputBox" Sequence="10"
      ControlSrc ="~/_controltemplates/ReplaceSearchBox/ReplaceSearchBox.ascx">        
    </Control>
</Elements>

Since we’re using an user control for substitution, we need to make sure that ControlSrc attribute is defined. There is no need to define ControlClass and ControlAssembly attribute here. 

I did define all the 3 attributes, but the substitution was not happening. I’ve learnt that it’s enough to define the ControlSrc attribute itself. Do not define all 3  attributes for user control, 

the substitution will not happen. If you are using Custom Control, it makes sense to use ControlClass and ControlAssembly attribute.

The final Solution Package looks like the following :-

Build the Project, Package it and Deploy.
Now you can see the the custom user control with Calendar replaces the Delegate control.