Delegate Control (Control Templatization)
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
Windows SharePoint Services 3.0 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="http://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="http://schemas.microsoft.com/sharepoint/">
<Control
Id="SmallSearchInputBox"
Sequence="50"
ControlClass="MySearchControl"
ControlAssembly="MyAssembly"/>
</Elements>
The DelegateControl is embedded inside Windows SharePoint Services 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 Windows SharePoint Services. 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, Windows SharePoint Services 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 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