Delegate Control (Control Templatization)
Applies to: SharePoint Foundation 2010
Microsoft SharePoint Foundation implements a straightforward mechanism to declare candidate controls for a particular functionality and provides a mechanism for choosing a single functionality provider. Through a Feature you can identify controls and control templates that serve as candidates for a chosen functionality.
Controls are identified based on the functionality that is provided by the control. You can register controls for these functionalities through Feature elements. You specify which sort of control to use, a sequence number, and a URL to either a control template or an assembly, as shown in the following code examples:
<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
<Control
Id="SmallSearchInputBox"
Sequence="100"
Url="/templates/mysearchcontrol.ascx"/>
</Elements>
The following control replaces the previous control because it specifies a lower sequence number.
<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
<Control
Id="SmallSearchInputBox"
Sequence="50"
ControlClass="MySearchControl"
ControlAssembly="MyAssembly"/>
</Elements>
The DelegateControl is embedded inside SharePoint Foundation pages and acts based on this information, as follows:
<SharePoint:DelegateControl ControlId="SmallSearchInputBox"/>
At run time, this control accepts the union of control elements declared at the server farm, Web application, site collection, and Web site levels. The control that has the lowest sequence number is added to the control tree by means of the DelegateControl. In the case of a sequence tie, the order of controls is arbitrary.
The sequence number of the DelegateControl can be used to integrate a portal search control in SharePoint Foundation. The default search control has a sequence number of 100, and a portal search, for example, could be activated at the site collection level with a sequence number of 50. In this way, SharePoint Foundation replaces the default search control with the portal search control in all places where the search control is invoked.
For example, the following example shows the SmallSearchInputBox delegate control:
<SharePoint:DelegateControl runat="server" ControlId="SmallSearchInputBox"/>
This control might instantiate a custom control candidate like the following:
<MySearch:SuperSearchControl/>
The parent delegate control sets properties on the custom control. Use the Property element within DelegateControl to set properties of associated custom controls, using reflection.
Note
Setting the AllowMultipleControls property to true causes all matching candidate controls to be added to the page as children of the delegate control according to the order specified by the Sequence attribute.
A delegate control is not inherently designable because it is ignorant of the actual control that gets instantiated inside it. The best it can do is render the design-time HTML of the chosen control for the particular instance. At best, the designer provides an option to "hardcode" the control, meaning replace the SharePoint:DelegateControl with the current control that is being returned via the Features infrastructure. The developer can then customize the control.
Possible scopes:
Farm: Yes
Web Application: Yes
Site Collection: Yes
Web Site: Yes
See Also
Tasks
How to: Customize a Delegate Control