Rendering Methods of WebControl

If your control renders a visual HTML element, you should derive from the WebControl class. We'll use the term Web control to denote a class that derives from WebControl . The WebControl class provides methods that allow you to modify the tag rendered by a Web control, add attributes to the rendered tag, and write content (sometimes referred to as inner HTML ) within the rendered tags. Table 8-2 lists the methods of WebControl that provide rendering functionality. Like the rendering methods of Control that we described in Table 8-1, these methods take only one argument ”an instance of the HtmlTextWriter class.

Table 8-2. The Rendering Methods of the WebControl Class

Method	Description
protected virtual void AddAttributesToRender(HtmlTextWriter writer)	Enables a Web control to specify name /value pairs, which are rendered as attributes on the tag of the HTML element. When overriding AddAttributesToRender , you must invoke the corresponding method of the base class; otherwise , your control will lose important functionality. The base WebControl class renders many of the control's properties as HTML attributes in its implementation of this method. For example, WebControl renders its ClientID property as the id HTML attribute. WebControl also renders any style properties that are set on your control as CSS values in an HTML style attribute. We'll provide an example of overriding the AddAttributesToRender method in the HoverLabel sample in the next section.
public virtual void RenderBeginTag(HtmlTextWriter writer)	Enables a Web control to write a begin tag to the output stream. You should override this method when you want to provide a different implementation for the begin tag ”for example, when you want to generate multiple begin tags, such as <table><tr><td> . If your control generates a single tag and you want to override the default <span> tag that WebControl generates, you should override either the TagKey property or the TagName property that we described in Chapter 7 (in Table 7-4), instead of overriding RenderBeginTag.
protected virtual void RenderContents(HtmlTextWriter writer)	Enables a Web control to render content within the control's tags. By default, this method renders the tree of child controls. Override this method if you want to write text (inner HTML) or other content within your control's tags. Be sure to invoke the corresponding method of the base class if you want to use the default logic to render your child controls. We'll provide an example of overriding this method in the HoverLabel sample in the next section.
public virtual void RenderEndTag(HtmlTextWriter writer)	Enables a Web control to write an end tag to the output stream. You need to override this method only to provide a matching end tag for the tag created by the RenderBeginTag method (if you overrode that method in your control). For example, if you render multiple begin tags ( <table><tr><td> ) in RenderBeginTag , you must render the end tags </table></tr></td> in RenderEndTag .

To implement rendering in a class that derives from WebControl , you should override one or more of the methods listed in Table 8-2 instead of overriding the Render method as you would if your control derived from Control . Overriding a method other than Render is important because the base WebControl class provides tag-rendering capabilities that you will lose if you override Render in your Web control. The best way to understand this is by examining the implementation of some of the rendering methods in WebControl . WebControl implements Render as shown in the following code:

 protectedoverridevoidRender(HtmlTextWriterwriter){ RenderBeginTag(writer); RenderContents(writer); RenderEndTag(writer); }

WebControl implements RenderBeginTag as follows :

 publicvirtualvoidRenderBeginTag(HtmlTextWriterwriter){ AddAttributesToRender(writer); HtmlTextWriterTagtagKey=TagKey; if(tagKey!=HtmlTextWriterTag.Unknown){ writer.RenderBeginTag(tagKey); } else{ writer.RenderBeginTag(this.TagName); } }

Finally, WebControl implements RenderContents as follows:

 protectedvirtualvoidRenderContents(HtmlTextWriterwriter){ //ThisinvokestheRendermethodoftheControlclass, //whichinturninvokesRenderChildrentorender //childcontrols. base.Render(writer); }

When you want to render content within your Web control's tags, you should override the RenderContents method, as we'll show in the HoverLabel example in the next section. With some Web controls, it is necessary to override the Render method, as we'll demonstrate in Chapter 12.