Rendering Methods of the Control Class


Rendering Methods of the Control Class

The base Control class defines three methods for rendering , which Table 8-1 shows. All three methods take an instance of the HtmlTextWriter class as their only parameter. This object encapsulates the HTTP response stream into which the control will render its output. We'll examine the HtmlTextWriter class later in this chapter, in the section " HtmlTextWriter and Related Enumerations."

Table 8-1. The Rendering Methods of the Control Class

Method

Description

protected virtual void Render(HtmlTextWriter writer)

Enables a control to render itself by writing markup text. You should override this method to render content when your control derives directly from the Control class.

protected virtual void RenderChildren(HtmlTextWriter writer)

Renders a control's children into the stream represented by the HtmlTextWriter object. By default, children are rendered in the order in which they are added to the Controls collection of a control. Override this method only if you want to replace the default logic. For example, you might override this method if you want to intersperse text between child controls.

public void Render ­Control(HtmlTextWriter writer)

Renders a control. Render is protected, while RenderControl is public and allows a class that consumes (uses) the control to render it. For example, when a page renders its control tree, RenderControl is invoked on each child control. A control's designer also invokes RenderControl to render the control on a visual design surface. As a control developer, you will invoke the RenderControl method when you want to render a child control. Under the hood, RenderControl invokes Render when a control's Visible property is true .

Page Rendering

As we described in Chapter 2, " Page Programming Model," a page is an HTTP handler, which has the ultimate responsibility of writing to the response stream. However, a page is also a control (the Page class derives indirectly from Control ) and has the same rendering capabilities as other controls. This makes it possible for a page to render itself and its children by using the rendering methods described in Table 8-1 in a recursive manner.

Every page has a control tree that represents the child controls contained in the page, as we described in Chapter 2. The page represents the root of the control tree. To render the control tree, a page creates an instance of an HtmlTextWriter class, which encapsulates the response stream, and then passes the HtmlTextWriter object to its RenderControl method. The RenderControl method checks whether the Visible property of a control is true . If it is, RenderControl invokes the Render method. The default implementation of the Render method invokes the RenderChildren method, which by default invokes the RenderControl method on each child control. This leads to a recursive rendering of the control tree. Each control in the tree is rendered unless its Visible property is assigned a value of false . If a control's Visible property is false , that control and its children are excluded from the rendering logic. The public RenderControl method is needed in addition to the Render method because Render is protected.

The page-rendering logic is best understood by examining the call to RenderControl in the Page class and the implementation of the RenderControl , Render , and RenderChildren methods of the Control class.

The invocation of the RenderControl method in the Page class is as follows :

 RenderControl(newHtmlTextWriter(Response.Output)); 

The Control class implements the RenderControl , Render, and RenderChildren methods as follows:

 publicvoidRenderControl(HtmlTextWriterwriter){ if(Visible){ Render(writer); } } protectedvirtualvoidRender(HtmlTextWriterwriter){ RenderChildren(writer); } protectedvirtualvoidRenderChildren(HtmlTextWriterwriter){ foreach(ControlcinControls){ c.RenderControl(writer); } } 

As the code shows, the rendering methods of the Control class set up the rendering architecture but do not write any characters to the output stream. Content gets written to the stream because the controls in the page's control tree are derived classes (such as Button , Label , and TextBox ) that override the Render method (or the rendering methods of the WebControl class) to write content such as tags and text.

If you override the Render method or the RenderChildren method, you should invoke the corresponding method of the base class to ensure that the children of your control are recursively rendered (unless you specifically do not want to use the default logic to render child controls). The order of invocation is important, and you must invoke the base class's method exactly where you want children to be rendered.



Developing Microsoft ASP. NET Server Controls and Components
Developing Microsoft ASP.NET Server Controls and Components (Pro-Developer)
ISBN: 0735615829
EAN: 2147483647
Year: 2005
Pages: 183

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net