16.13 Creating Custom Web Controls

You want to create a custom Web control that ASP .NET pages can use.

Technique

Just as Windows Forms allows you to create custom controls for use on a form, ASP.NET contains a similar mechanism. To create a new custom control, select the Web Control Library from the project templates in the New Project dialog. When the project is created, the main C# file opens, allowing you to add any necessary properties and methods . The properties appear within the Property Browser when a user uses the custom control on his or her Web Form. To maintain consistency, the attributes that can be placed on each property are the same as those used by Windows Forms controls. For instance, to change the category for a property, use the Category attribute, passing the name of the category for the property within the Property Browser.

Because the final output of any Web control is HTML, you perform rendering by using an HtmlTextWriter object within the Render method. The HtmlTextWriter allows you to write regular HTML using the Write method or to use a hierarchical approach ”by using the WriteBeginTag followed by any attributes using the WriteAttribute method and finally closing the tag using WriteEndTag . Listing 16.9 shows how to create a custom gauge control. Although far from being perfect, it does demonstrate the principle just explained. Once the control is created, add it to the toolbox by right-clicking on the toolbox and selecting Add Item. Click the Browse button and locate your control's assembly. You can then create a new ASP.NET Web application and place your custom control on the new page.

Listing 16.9 Gauge Custom Web Control

 using System; using System.Web.UI; using System.Web.UI.WebControls; using System.ComponentModel; using System.Drawing.Drawing2D; using System.Drawing; namespace _14_CustomWebControl {     [DefaultProperty("Text"),     ToolboxData("<{0}:WebCustomControl1 runat=server></{0}:WebCustomControl1>")]     public class WebCustomControl1 : System.Web.UI.WebControls.WebControl     {         private string text;         private int level = 50;         private Color gaugeColor = Color.Red;         public WebCustomControl1()         {             this.Height = 100;             this.Width = 50;         }         [Bindable(true),         Category("Appearance"),         DefaultValue("")]         public string Text         {             get             {                 return text;             }             set             {                 text = value;             }         }         public int Percentage         {             get             {                 return this.level;             }             set             {                 if( value < 0 )                     this.level = 0;                 else if( value > 100 )                     this.level = 100;                 else                     this.level = value;             }         }         public Color GaugeColor         {             get             {                 return gaugeColor;             }             set             {                 gaugeColor = value;             }         }         protected override void Render(HtmlTextWriter output)         {             output.Write( "<TABLE cellspacing='0' cellpadding='0' height='" +                 Height + "' width='" + Width + "'>" );             output.Write( "<TR height='" + (100-level).ToString() +                 "' bgcolor='" + ColorTranslator.ToHtml( Color.LightGray ) +                 "'><TD/></TR>" );             output.Write( "<TR height='" + level + "' bgcolor='"                 + ColorTranslator.ToHtml( gaugeColor ) + "'><TD/></TR>" );             output.Write( "</TABLE>" );             output.Write( text );         }     } } 

Comments

All of the ASP.NET controls that you have used so far use the same methods shown here. The ultimate goal of any Web control is to create an HTML-based representation of itself. The HTML equivalent of the Button control, for instance, is an HTML Input control with a type attribute of button . When creating the Render method, you can do a few things to help the design of your control.

You might find it easier to use the Web Form designer to visually create how you want your final control to appear. Doing so lets you see the resultant HTML code that you can then simply place within the Write method of the HtmlTextWriter . You naturally want to replace any HTML control attributes with the properties defined in your class, as shown in Listing 16.9.

Your control might be a composite of different HTML controls. The HtmlTextWriter is designed to write the final output, but that doesn't mean your code has to be the one that utilizes that object. In other words, you can create an instance of an ASP.NET control, set any necessary properties, and then call the RenderControl method of that control passing the HtmlTextWriter as the parameter. The following example shows how to use an ASP.NET TextBox and Label control to render a custom Web control:

 protected override void Render(HtmlTextWriter output) {     Label lbl = new Label();     TextBox tb = new TextBox();     lbl.Text = "Please enter your name: ";     lbl.RenderControl( output );     tb.RenderControl( output ); }