ne complaint about Microsoft Windows SharePoint Services (WSS) 2.0 and Microsoft SharePoint Portal Server 2003 was the difficulty in making changes to the environment after it was deployed. Officially, changing a site definition isn’t supported after it has been used to create other sites. Of course, that was then.
Now, Windows SharePoint Services 3.0 and Microsoft Office SharePoint Server (MOSS) 2007 offer many ways to make changes to sites after they have been provisioned. The introduction of SharePoint Features (note the capital “F”) has opened up an entire world to changing master pages, page layouts, and pages themselves. Further, SharePoint now includes a new technique—delegate controls—that allows for more fine-grained control over partsof the page.
If you think about the entire SharePoint model and using Web Parts, it’s all about decoupling the designer from the specific data on the page. The designer of an application defines the framework, including Web Part zones. It does not, however, specify every type of Web Part that can be used or the code that is used to generate the output of the Web Part. Including the main data has been delegated to the Web Parts on the page.
That solution is great for the parts of the web page that you want users to be able to control, but what about regions of the page that you don’t necessarily want the users to be able to change? It’s possible technically to create locked Web Part zones, but that approach is painful and requires more than a passing knowledge of how Web Parts work. You need a simpler process that allows you to add new functionality to every page on a site without having the hassle of locked Web Part zones and the associated management code that is required.
The challenge, then, is how do you light up functionality for one site and not another. Perhaps even more challenging is lighting up different sets of functionality for different sites. You might, for instance, want to implement one kind of additional security for some sites and not for others. Similarly, you may want to ensure that corporate-wide announcements are included on some pages and not others.
Such situations are where delegate controls come in handy. A delegate controlallows you to light up functionality on a site-by-site basis and provides the scope to add a single control that doesn’t take over the entire page. Delegate controls are stand-ins for the actual controls you want to incorporate when you’re building a master page or designing a page layout. Instead of adding that specific search functionality, for example, you can add a delegate control. During run time SharePoint swaps out the delegate control with the best control for the matching functionality, which will be discussed in more detail shortly.
Declarations in Sequence
When you create a delegate control in a feature part of a page, the declaration is a sequence number. The lower the sequence number attached to a control, the better the chance that the control will be used to replace the associated delegate control, and the best control is defined as the control that has the lowest sequence number. When SharePoint selects the control to replace the delegate control, it looks through the list of activated controls and selects the best control or controls. If the delegate control is set to not allow multiple controls—such as in a page header, for instance—then it selects the control defined with the lowest sequence number.
For instance, take a look at this delegate control definition from the OSearchBasicFeature, which comes with MOSS:
/_layouts/images/gosearch.gif /_layouts/images/goRTL.gif /_layouts/images/gosearch.gif /_layouts/images/goRTL.gif ShowDD /_layouts/osssearchresults.aspx None
In this definition the control is given a name: the name that must match the name used on the master page, in the page layout, or on the page. Delegate controls can either be web controls, as specified in the preceding example, or user controls. If you’re specifying a user control, use a Url attribute in the control instead of the ControlClass and ControlAssemblyattributes.
The preceding XML example demonstrates how to define the delegate control for SharePoint; however, it doesn’t put the control on the page, which is the responsibility of the
Placing the Delegate Control
If you crack open default.master in WSS you’ll find a delegate control with a ControlId attribute: SmallSearchInputBox It matches the Id attribute of the previous Controltag:
This tag places the delegate control inside of a master page’s placeholder, which means you can use delegate controls to override the search control by not specifying the placeholder in the ASPX file as well as by creating and activating a new feature with a lower sequence number control on the site. In other words, there are many ways to customize the output: one way that requires a completely new page and another way that can be controlled by features.
Why would you have both? One sample case might be for a search control on an ecommerce site, where the pages typically have the same look and feel throughout the site except for the page that displays the checkout process. Generally, although checkout pages have the same basic appearance as the other pages on the site, they will appear different, usually by virtue of having fewer distractions. The idea, naturally, is a design that encourages users to complete the purchase without being unduly distracted. For instance, as the user is checking out it might be appropriate to suppress the availability of the search box even if the site is embellished with enhanced search features.
Another place where you can find a delegate control on the master page is for additional page headers. This control is from the WSS default.masterfile:
This delegate control is set to allow multiple controls, which also might be useful for an ecommerce site where you want the page header to add keywords dynamically. You can build a control that emits metatags to add to the header. For instance, you might create a control that emits keywords based on where the user is in the navigation. It might also emit other metatags that allow the site’s internal search engine to do a better job of indexing the site.
Extra, Extra HTML
What about situations where you need to wrap the delegate control in some static HTML? Although it’s possible to include HTML around the DelegateControl, that approach emits the HTML whether the DelegateControl exists or not. Two attributes—PrefixHtml and SuffixHtml—control the HTML to be emitted before the delegate control and the HTML to be emitted after the delegate control, respectively. This technique allows you to add HTML only when a delegate control exists. You’ll find that the out-of-the-box SharePoint templates do this when they want to emit a
The Scopeattribute is another delegate control attribute. While it may appear to be seemingly useless, it does allow you to filter delegate controls to those deployed by features of the same scope. This attribute allows you to make certain delegate controls work throughout the entire farm, not just within a single web site or web application. Farm features are activated automatically when they are installed, allowing the template designer to create points that must be applied everywhere.
The out-of-the-box default.masterdefines these delegate controls for you to override:
Of these, only the AdditionalPageHead is set to allow multiple controls. Notice that PublishingConsoleis defined, which is true even if MOSS isn’t installed.
Delegate controls are an important option for creating solutions that can be mixed and matched with other options. The ability to isolate one feature on a site from another feature can be an important tool in the SharePoint developer’s toolbox.