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