Using Custom ASP.NET Controls in SharePoint 2007
Like ASP.NET Web Parts you can also use ASP.NET Controls in SharePoint 2007. I have put together a comparison between them in context of their use in SharePoint:
Similarities
- Custom Properties are supported
- Can exist inside as well as outside a web part zone
- Can be used in a master page or page layout
- Needs a SafeControl entry in web.config file
- Runs under SharePoint and current user context
Advantage of Web Parts
- Web Part Gallery is available to manage them at site collection level
- Can be added/removed using web browser or SharePoint Designer or even a C# code
- When inside a Web Part Zone, Web Parts can be moved around and also personalized by end-users using a web browser
- Default/Custom Editor Part can be used to manage properties through web browser
- Audience targeting can be used
- Can be used in a content/site page
Advantage of Controls
- Cannot be added/removed using web browser or C# code. It can be added/removed only using SharePoint Designer
- Useful for scenarios where a control needs to be in every page of site/web or if output is not visible in UI
- Can be used to put content in web page header dynamically. For example: a custom meta tag or a stylesheet based on current user, web, file or some other business rule
SharePoint also uses custom WebControls a lot. Some examples ("<" and "/>" tags have been removed from beginning and end of each line):
- SharePoint:CssLink runat="server"
- SharePoint:ScriptLink language="javascript" name="core.js" Defer="true" runat="server"
- SharePoint:SPCalendarNavigator id="CalendarNavigatorId" runat="server"
- PublishingWebControls:RichImageField id="ImageField" FieldName="PublishingPageImage" runat="server"
To create a custom Control:
- Create a Class Library project
- Inherit from WebControl class in System.Web.UI.WebControls namespace or Control class in System.Web.UI namespace
- Override the "Render" or "RenderContents" method
To use the custom Web Control:
- Put the custom control assembly in Bin directory of Web application (GAC may also be used)
- Mark it as a safe control in web.config
- Open master page or a page layout file
- Register the control using Register directive and assign a TagPrefix
- Use the control using the TagPrefix and Class name
Some tips from the MSDN article "Walkthrough: Developing and Using a Custom Server Control" :
- If your control renders a user interface (UI) element or any other visible element on the client, you should derive your control from System.Web.UI.WebControls.WebControl (or a derived class)
- If your control renders an element that is not visible in the client browser, such as a hidden element or a meta element, derive your control from System.Web.UI.Control
- If your control extends the functionality of an existing control, such as the Button, Label, or Image controls, you can derive from that control
- In general, when your control derives from WebControl and renders a single element, you should override the RenderContents method (and not the Render method) to render content within the control's tags
- ToolboxDataAttribute specifies the format string for the element. The string becomes the control's markup when the control is double-clicked in the toolbox or dragged from the toolbox onto the design surface
Sample code: following code adds current web's Title as content of Keywords Meta Tag
public class CustomMetaTag : WebControl {
protected override HtmlTextWriterTag TagKey {
get { return HtmlTextWriterTag.Meta; }
}
protected override void AddAttributesToRender(HtmlTextWriter writer) {
base.AddAttributesToRender(writer);
writer.AddAttribute(HtmlTextWriterAttribute.Name, "keywords");
SPWeb web = SPControl.GetContextWeb(Context);
writer.AddAttribute(HtmlTextWriterAttribute.Content, web.Title);
}
}
Note: a very good example of using a custom WebControl is given in this blog entry by Waldek Mastykarz -> Extending the SharePoint:FieldValue WebControl