Delegate Control

  • Article

Contains a certain predefined element of the SharePoint Products and Technologies environment to replace with another control through a SharePoint Feature.

Real World Example

A user wants to replace the built-in search control with a richer version. He creates a Feature that includes a delegate control to override the delegate control placeholder.

Technical Details

The following code example shows a delegate control placeholder defined in the built-in pages. A delegate control that matches the control ID renders in its place at run time.

<SharePoint:DelegateControl  ControlId="SmallSearchInputBox"/>

Following is the definition of the SmallSearchInputBox control included in the OSearchBasicFeature feature provided in Microsoft Office SharePoint Server 2007. Any Web site that is running under a Web application that has this Feature activated would render this control in place of the delegate placeholder.

<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
   <Control Id="SmallSearchInputBox" Sequence="50" ControlClass="Microsoft.SharePoint.Portal.WebControls.SearchBoxEx" ControlAssembly="Microsoft.SharePoint.Portal, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c">
      <Property Name="GoImageUrl">/_layouts/images/gosearch.gif</Property>
      <Property Name="GoImageUrlRTL">/_layouts/images/goRTL.gif</Property>
      <Property Name="GoImageActiveUrl">/_layouts/images/gosearch.gif</Property>
      <Property Name="GoImageActiveUrlRTL">/_layouts/images/goRTL.gif</Property>
      <Property Name="DropDownMode">ShowDD</Property>
      <Property Name="SearchResultPageURL">/_layouts/osssearchresults.aspx</Property>
      <Property Name="ScopeDisplayGroupName"></Property>
      <Property Name="FrameType">None</Property>
   </Control>
</Elements>

A delegate control Feature can override the default control placeholder without using an assembly if a control template user control is referenced. Also, if multiple delegate controls exist for a single placeholder that is not marked as multiple, the intended delegate control will require a lower sequence number as follows.

<Control Id="SmallSearchInputBox" Sequence="40" ControlSrc="~/_controltemplates/mycustomarea.ascx"/>

Support Details

Delegate controls rely on server-side code in the form of ASCX pages or of compiled classes, which both can expose the risk of server-side performance or security issues.

A given delegate control will not render, even though the Feature that defines it is activated on a specific Web site, if the delegate control placeholder tag is not available on the page that should be rendering it. This could occur if a delegate control is used on a site that was upgraded but which is still customized, because the page within the site will not contain the delegate control placeholder. Another cause of this problem can be a designer inadvertently removing a placeholder control from a page.