Reusability in ASP .NET, Part 2 Dino Esposito Download the code for this article:Cutting0109.exe (41KB) Browse the code for this article at Code Center:Custom Controls O ne of the key improvements in ASP .NET over classic ASP is the introduction of server controls. When you want to use a control from the Microsoft® .NET Framework as a server control, you must mark it with the runat=server attribute to make it visible toâ€"and programmable onâ€"the server.       Web controls in ASP .NET are abstracted from the set of ordinary HTML tags, with some notable additions. For instance, the framework provides you with the Table control (which is similar to the HTML table tag), but also the derived Calendar and DataGrid controls. Overall, Web controls offer a more consistent and uniform programming interface than the basic HTML controls from which they're derived.       Most Web controls in the .NET Framework have a Text attribute that makes it easier to work with them. For example, the standard HTML checkbox doesn't have a Text property. To associate text with it, you must wrap the whole thing in a <span> tag.

<span> <input type=checkbox . . .> Text of the checkbox </span>
                                    

However, the corresponding <asp:checkbox> Web control exposes a Text property. When rendered to an HTML stream, this Text property is translated back to the <span> tag.       While pure HTML controls must expose a programming interface that approximates the features of the corresponding HTML tags, derived Web controls don't have this limitation. As a result, they can have methods, properties, and events defined to mix programming comfort, flexibility, and effectiveness. A Simple Custom Control       An ASP .NET custom control is a class that's normally derived either from the Control base class, or from a more specific existing class (like DataGrid). If you're building a control from scratch, you probably want to derive it from the Control class. However, if you want to create a slightly modified version of another control, use an existing control as a base class. This lets you take advantage of object-orientation and inheritance.       The control in Figure 1 acts like an extended version of the TextBox control. Because it's built atop TextBox, it inherits all the standard features of textboxes plus some CSS style settings. This derived textbox will default to having a thin, flat black border and a beige background; its text will appear in Verdana with an extra-small font size. Figure 2 shows how it looks in a test page. Figure 2Flat TextBox       In Figure 1, the control also registers a custom handler for the textbox's OnLoad event. Notice that OnLoad fires after the attributes set in the page have been processed. This means that if you want to show some default text whenever the Text property is empty, you can do so with the following code:

public void OnLoad(Object s, EventArgs e) { if (this.Text == "") this.Text
                                        = "<Enter some text>"; } 

<%@ Register TagPrefix="d" Namespace="BWSLib" Assembly="FlatTextBox" %>
                                    

csc /t:library flattextbox.cs 

<d:FlatTextBox runat="server" id="myCtl" /> 

<d:FlatTextBox runat="server" id="myCtl" TextMode="MultiLine" Rows="5"
                                        /> 

public override String Text { get { return base.Text; } set { if (value.Length
                                        > this.MaxLength) base.Text = value.Substring(1, this.MaxLength); else base.Text
                                        = value; } } 

get { return base.Text; } 

get { return Text; } 

This happens because reading the value of any property is resolved in terms of its get accessor. So a statement like "return Text" in the get accessor will call itself recursively until you blow the stack. The same considerations apply to set accessors.       You may also define a brand new Text property that is managed independently from the Text property of the base class. In this case, though, you must explicitly prefix the Text property with a keyword called new (as opposed to override). Figure 3Input Maximum Length = 4       In light of this, running the following code snippet in an ASP .NET page will generate the page shown in Figure 3, where the string "Enter some text" is cut down to the first four characters (Ente).

<d:FlatTextBox runat="server" id="myCtl" maxlength="4" /> 

public override TextBoxMode TextMode { get { return base.TextMode; } } 

So now there's no way for client applications to change the value stored in the TextBoxMode property of this derived control. If you attempt to do that anyway, you get the compiler error shown in Figure 5. Figure 5Compiler Error As you can see, the error message tells you that the error is not due to a missing property, but to the attempt to use a property that has been declared read-only. Thanks to the power of object-oriented programming, this happens only in the derived class. From the ASP .NET perspective, this is a way to build specialized components that can be programmed as native elements of the .NET Framework. A Labeled TextBox       When you use a textbox in a Web application, you usually associate it with a descriptive label. Is there a way to automate this process, saving yourself the burden of repeatedly declaring an <asp:label> control each time? Yes, of course.       Figure 6 shows the code necessary to build the LabeledTextBox class. It derives from TextBox and defines a few extra properties such as Label, LabelCssClass, and LabelOnTop. Label contains the text to be used for the description. LabelCssClass is a string that contains the name of the CSS class to associate with the label. LabelOnTop is a Boolean value that, when set to true, causes the control to draw the label atop the textbox instead of to the left of it.       When writing custom controls, you should pay attention to the CreateChildControls method. You might want to override it whenever your control contains children. In this case, you override this method, build instances of children, and add them to the Controls collection of the parent class. You can append it to the bottom of the collection through the Add method. Alternatively, you can insert the new child control at any valid position using AddAt.       The following code shows an alternative way to build a control that combines one label and one textbox.

protected override void CreateChildControls() { m_textBox = new TextBox();
                                        m_textBox.Text = m_Text; m_label = new Label(); m_label.Text = m_Label + "  ";
                                        this.Controls.Add(m_label); this.Controls.Add(m_textBox); } 

protected override void Render(HtmlTextWriter output) 

m_label = new Label(); m_label.Text = m_labelText; m_label.RenderControl(output);
                                    

m_label.RenderControl(output); if (m_LabelOnTop) output.WriteLine("<br>");
                                        else output.WriteLine("  "); base.Render(output); 

Figure 8LabeledTextBoxes in Action The code renders the label first, followed by a literal control that acts as the separator, and finally the textbox. Figure 7 shows the source code of an ASP .NET page that uses the control. Figure 8 shows the output of the page. Figure 9 shows the generated HTML code for the two LabeledTextBox controls in Figure 7. Figure 9HTML Generated for LabeledTextBoxes Maintaining State in Controls       Web pages, including ASP .NET pages, get invoked multiple times in the same session. You cannot save any control information from call to call because the control's lifetime is tied to the page. When the page is dismissed on the server and sent as HTML to the browser, all the controls that were instantiated on the page are marked as ready for the garbage collector.       When the server loads an ASP .NET page, all the controls it contains go through a sequential process entailing several steps. Although the communication between client and server is stateless, the user's experience must be seamless. ASP .NET, in conjunction with the page and the controls, manages to provide this apparent continuity.       ASP .NET controls have a ViewState property for storing information that must be persisted across multiple page invocations. ViewState plays a key role in allowing controls to start working upon postback events in the same state they were in at the end of the previous request. Figure 10Control's Lifecycle       In Figure 10 you can see the various steps that form the control's lifecycle once the host page has been requested again. First, the control is initialized and its previous state is restored with a call to its LoadViewState method. LoadViewState populates the control's ViewState collection with all the control-specific information that was saved during the previous invocation. A control can save information for type and size, and the process for restoring state can be customized by overriding the LoadViewState method. At this stage, ViewState holds an exact copy of the data that the control stored at the end of the previous request. This information comes across as form data and basically is the same data you could access through the Request.Form collection. This information includes the state of the client-side HTML elements like the status of checkboxes and dropdown lists and the contents of one textbox.       Some of the data, of course, may have changed during client-side user interaction. The posted information is merged with the freshly restored ViewState data and only at this point can the state of the control be considered consistent and ready to use.       As the next step, the control's OnLoad event is fired, giving it a chance to apply additional changes to its state, distinguishing between the first and successive accesses. Any change detected between the current and previous postbacks will generate a RaisePostBackDataEvent event for the control. After that, the runtime executes the server-side code associated with the client-side event and prepares the rendering of the control.       Controls can persist custom data by storing it in ViewState. ViewState is an instance of the StateBag class, which is basically a collection. To store something in ViewState, do the following:

ViewState["MyData"] = . . . 

public String Text { get { return (String) ViewState["Text"]; } set { ViewState["Text"]
                                        = value; } } 

<d:InputForm runat="server" > <FormField id="ffFirstName" Label="First
                                        Name" Text="" /> <FormField id="ffLastName" Label="Last Name" Text="Esposito"
                                        /> <FormField id="ffAddress" Label="Address" /> <FormField id="ffCity"
                                        Label="City" /> </d:InputForm> 

InputForm is the primary control that creates the surrounding table and governs the behavior, the position, and the content of the child labels and textboxes. Figure 11InputForm Output In Figure 11 you can see the expected output of such an InputForm control: a table with two columns, one for labels and one for textboxes. In terms of raw HTML, the control is merely a table with two columns of cells: one for labels and one for textboxes.

<table> <tr> <td><span>Label</span></td>
                                        <td><input type=text></td> </tr> ••• </table> 

<expo:InputForm runat="server" id="iform"> <asp:label runat="server"
                                        id="x" Text="???" /> <FormField id="ffFirstName" Label="First Name" />
                                        </expo:InputForm> 

[ ControlBuilderAttribute(typeof(MyControlBuilder)) ] public class InputForm
                                        : TextBox {...} 

protected override void AddParsedSubObject(Object obj) { if (obj is BWSLib.FormField)
                                        m_formFields.Add(obj); }