Creating Web User Controls

Web user controls are very much like Windows user controls, with the obvious difference that they're designed for use in Web applications. Like user controls, Web user controls can be composites of other controls, or you can draw them from scratch. (Although your options for drawing them from scratch are more limited in Web user controls because of the limitations of browsers. One option is to make the Web user control display an image that you can change when the control is clicked, activated, and so on.)

Although Web user controls are based on the System.Web.UI.UserControl class, which is very different from the user control System.Windows.Forms.UserControl class, programming them is similar. To demonstrate just how similar, we'll re-create the same user control we just created as a Web user control.

To follow along, create a new Web application called ch11_03 now, and then add a Web user control to this application by using Project, Add Web User Control. When you select this menu item, the Add New Item dialog box opens, as you see in Figure 11.8. Accept the default name for the new Web user control, WebUserControl1 , by clicking Open .

Figure 11.8. The Add New Item dialog box.

graphics/11fig08.jpg

This creates the new Web user control you see in Figure 11.9. The new Web user control's class is WebUserControl1 , and at design time, it looks like a small standard Web page. We've already added the label we'll use in this control to the Web control, as you also see in Figure 11.9.

Figure 11.9. A new Web user control.

graphics/11fig09.jpg

As far as the C# code goes, programming a Web user control in C# is so close to programming a user control that we can use the same code. All we have to do is to borrow the code from our user control example, ch11_01, and drop it into the code designer for the new user control. Here's what that looks like in WebUserControl1.ascx.cs:

 public class WebUserControl1 : System.Web.UI.UserControl {   protected System.Web.UI.WebControls.Label Label1;   #region Web Form Designer generated code  public delegate void NewTextDelegate(object UserControl1, string text);   public event NewTextDelegate NewText;   public Color DisplayColor   {   get   {   return Label1.BackColor;   }   set   {   Label1.BackColor = value;   }   }   public void DrawText(string text)   {   Label1.Text = text;   NewText(this, text);   }  }

This implements the DisplayColor property, the DrawText method, and the NewText event in our Web user control. It was as simple as that.

This is the point where things start to differ from user controls. As you recall, all we had to do to make a user control available to other projects was to compile it. The IDE can't work that closely with the Web server, however, which means that you have to follow a different procedure to add our Web user control to the ch11_03 Web application.

Here's what you do: Open the Web application's main form in a form designer, and then drag the WebUserControl1.ascx entry from the Solution Explorer onto that form, adding the Web user control, WebUserControl11 , to the form as you see in Figure 11.10. Because the Web user control has not been compiled, the IDE doesn't know what it will look like at runtime, so it gives it a generic button-like appearance at design time, as you can see in the figure.

Figure 11.10. Adding a Web user control to a Web application.

graphics/11fig10.jpg

Dragging this control to the Web form creates a new Web user control, WebUserControl11 , in the Web application's main Web form, WebForm1.aspx. Here's what this new control looks like in ASP.NET, in WebForm1.aspx:

 <%@ Page language="c#" Codebehind="WebForm1.aspx.cs" AutoEventWireup="false"   Inherits="ch11_03.WebForm1" %>  <%@ Register TagPrefix="uc1" TagName="WebUserControl1"   Src="WebUserControl1.ascx" %>  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" > <HTML>  <HEAD>   <title>WebForm1</title>   <meta name="GENERATOR" Content="Microsoft Visual Studio .NET 7.1">   <meta name="CODE_LANGUAGE" Content="C#">   <meta name=vs_defaultClientScript content="JavaScript">   <meta name=vs_targetSchema     content="http://schemas.microsoft.com/intellisense/ie5">  </HEAD>  <body MS_POSITIONING="GridLayout">   <form id="Form1" method="post" runat="server"> <asp:Label id=Label1 style=   "Z-INDEX: 101; LEFT: 204px; POSITION: absolute; TOP: 10px" runat="server" Font-Size="X-Large">Web User Controls</asp:Label>  <uc1:WebUserControl1 id=WebUserControl11 runat="server"></uc1:WebUserControl1>  </form>  </body> </HTML>

On the other hand, because this control will not actually be compiled until runtime, the IDE does not automatically add the user control, WebUserControl11 , to the "code-behind" file for our Web application, WebForm1.aspx.cs. To use this control in code, you have to declare it in WebForm1.aspx.cs like this:

 public class WebForm1 : System.Web.UI.Page {   protected System.Web.UI.WebControls.Label Label1;  protected WebUserControl1 WebUserControl11;  .     .     .

That adds the Web user control to our code designer, which means you can work with the control's properties, methods , and events in code. Note that because the control hasn't been compiled, you can't work with its properties in the properties window at design time. You can, however, set properties (such as setting the DisplayColor property to System.Drawing.Color.aquamarine ) when the Web form containing the control loads, which we'll do in the ch11_03 example like this:

 private void Page_Load(object sender, System.EventArgs e) {  WebUserControl11.DisplayColor = System.Drawing.Color.Aquamarine;  }

As in the user control example we saw earlier today, we can also add a button with the caption Click Me! to call the DrawText method, except this time we'll use that method to display the text "Web User Controls!" (not "User Controls!" ) in the label in our Web user control:

 private void Button1_Click(object sender, System.EventArgs e) {  WebUserControl11.DrawText("Web User Controls!");  }

The DrawText method will also fire the NewText event in the Web user control. In our Web application, we can connect an event handler, WebUserControl11_NewText , to that event. To do that, add this code to the InitializeComponent method in the Web Form Designer generated code in WebForm1.ascx.cs:

 private void InitializeComponent() {   this.Button1.Click += new System.EventHandler(this.Button1_Click);   this.Load += new System.EventHandler(this.Page_Load);  this.WebUserControl11.NewText += new   ch11_03.WebUserControl1.NewTextDelegate(WebUserControl11_NewText);  }

All that's left is to write the event handler WebUserControl11_NewText . In that event handler, we'll display the new text in our Web user control in a text box this way:

 private void WebUserControl11_NewText(object sender, string text) {   TextBox1.Text = text; }

And that's all we need. We've been able to duplicate the work we did with the UserControls example earlier, but this time we're using a Web user control.

You can see this example at work in Figure 11.11. When you click the Click Me! button, the new text is displayed in the Web user control and the text box, as you see in that figure.

Figure 11.11. Using a Web user control.

graphics/11fig11.jpg

That rounds off our discussion on user controls and Web user controls. When it comes to code reuse, it's hard to beat these types of custom-built controlsyou write them once and you can use them in dozens of applications.