Lesson 2: Creating Composite Custom Controls

Lesson 2: Creating Composite Custom Controls

Composite custom controls combine one or more server or HTML controls within a single control class, which can be compiled along with other control classes to create an assembly (.dll) that contains a custom control library. Once created, the custom control library can be loaded into Visual Studio .NET and used in the same way as the standard server and HTML controls.

Composite custom controls are functionally similar to user controls, but they reside in their own assemblies, so you can share the same control among multiple projects without having to copy the control to each project, as you must do with user controls. However, composite controls are somewhat more difficult to create because you can t draw them visually using the Visual Studio .NET Designer. You have many more options for defining their behavior, however, so composite controls are more complex than user controls.

After this lesson, you will be able to

• Create a two-project solution that you can use to develop and debug composite custom controls

• Add a composite custom control to a Web form in a test project by manually using the @Register directive and HTML tags

• Create a composite custom control s appearance by adding controls to it using the CreateChildControls method

• Create properties, methods, and events for a composite custom control

• Handle design-time changes to the control, such as resizing or repositioning on a Web form using grid layout

• Create new controls by deriving directly from a single server control

Estimated lesson time: 35 minutes

Creating and Using Composite Custom Controls

There are six steps to creating and using a custom control in a Web application:

1. Create a solution containing a custom control project.

2. Add a Web application project to the solution, and set it as the startup project. You will use the Web application project to test the custom control during development.

3. Add a project reference from the Web application to the custom control project, and add an HTML @Register directive and control element to use the custom control on a Web form.

4. Create the custom control s visual interface by adding existing controls to it through the custom control s CreateChildControls method.

5. Add the properties, methods, and events that the custom control provides.

6. Build and test the custom control.

The following sections describe these steps in greater detail.

Creating the Custom Control Project

Custom controls are simply classes that are built into an assembly. These custom control classes inherit much of their behavior from the WebControl class, and they implement various interfaces, depending on the type of control you re creating.

The easiest way to get started is to use the Web Control Library project template provided by Visual Studio .NET. To create a custom control using the project template, follow these steps:

1. From the File menu, point to New, and then select Project. Visual Studio .NET displays the New Project dialog box, as shown in Figure 11-5.

   

   Figure 11-5. Creating a new custom control project

2. Select the Web Control Library template icon from the Templates list, type the name of the project in the Name box, and click OK. Visual Studio .NET creates a project containing code for a single custom control named WebControl1, as shown in Figure 11-6.

   

   Figure 11-6. The custom control code template (Visual Basic .NET)

The code shown in Figure 11-6 serves as a template for creating a new custom control. The template includes a class named WebControl1 that contains one property, which is named Text as shown in the following code.

Visual Basic .NET

Imports System.ComponentModel Imports System.Web.UI <DefaultProperty("Text"), ToolboxData("<{0}:WebCustomControl1 _ runat=server></{0}:WebCustomControl1>")> Public Class WebCustomControl1 Inherits System.Web.UI.WebControls.WebControl Dim _text As String <Bindable(True), Category("Appearance"), DefaultValue("")> _ Property [Text]() As String Get Return _text End Get Set(ByVal Value As String) _text = Value End Set End Property Protected Overrides Sub Render(ByVal output As _ System.Web.UI.HtmlTextWriter) output.Write([Text]) End Sub End Class

Visual C#

using System; using System.Web.UI; using System.Web.UI.WebControls; using System.ComponentModel; namespace CompositeControls { /// <summary> /// Summary description for WebCustomControl1. /// </summary> [DefaultProperty("Text"), ToolboxData("<{0}:WebCustomControl1 runat=server></{0}:WebCustomControl1>")] public class WebCustomControl1 : System.Web.UI.WebControls.WebControl { private string text; [Bindable(true), Category("Appearance"), DefaultValue("")] public string Text { get { return text; } set { text = value; } } /// <summary> /// Render this control to the output parameter specified. /// </summary> /// <param name="output"> The HTML writer to write out to </param> protected override void Render(HtmlTextWriter output) { output.Write(Text); } } }

The preceding code contains some elements you might not have seen before. Table 11-1 describes each of these items in turn.

Table 11-1. The Custom Control Template

Part	Name	Description
<DefaultProperty("Text"), ToolboxData("<{0}: WebCustomControl1 runat=server></{0}: WebCustomControl1>")> [DefaultProperty("Text"), ToolboxData("<{0}: WebCustomControl1 runat=server></{0}: WebCustomControl1>")]	Class attributes	Class attributes determine the design-time settings for the control. These values help determine what appears in the Visual Studio .NET Properties window when the custom control is selected on a Web form.
Inherits System.Web.UI. WebControls.WebControl : System.Web.UI.WebControls.WebContro l	Base class	Custom controls are derived from one of the base control classes.
<Bindable(True), Category("Appearance"), DefaultValue("")> [Bindable(true), Category("Appearance"), DefaultValue("")]	Property attributes	Like class attributes, property attributes specify the design-time settings of a property.
Property [Text]() As String public string Text	Property definition	The property definition specifies what the property does at run time. The square brackets ([]) indicate that the property name can be a keyword (although in this case, it is not).
Protected Overrides Sub Render(ByVal output As System.Web.UI.HtmlTextWriter) protected override void Render(HtmlTextWriter output)	Render method	The Render method displays the custom control. This overrides the base class s Render method.

The following sections describe how to add to and modify these parts to create a composite custom control, but for more complete information about attributes, see the Visual Studio .NET Help topic Design-Time Attributes for Components.

Creating the Test Project

The custom control project created in the preceding section has the output type of Class Library. This means that the project can be used only from another application it can t run as a stand-alone application. To run and debug a custom control in Visual Studio .NET, you must add a second project to the current solution.

To create a custom control test project and add it to the current solution, follow these steps:

1. With the custom control project open, point to Add Project on the File menu, and then choose New Project. Visual Studio .NET displays the New Project dialog box.

2. Select ASP.NET Web Application from the Templates list, type the name of the project in the Location box, and click OK. Visual Studio .NET creates a new Web application project and adds it to the current solution.

3. In Solution Explorer, right-click the Web application project, and select Set As StartUp Project from the shortcut menu. Visual Studio .NET indicates that the Web application is the startup project by displaying the project name in boldface.

4. In Solution Explorer, right-click the Web application s References item, and select Add Reference from the shortcut menu. Visual Studio .NET displays the Add Reference dialog box, as shown in Figure 11-7.

   

   Figure 11-7. Adding a project reference

5. Click the Projects tab, click Select to add a reference from the custom control project to the Web application project, and then click OK. Visual Studio .NET adds the reference, as shown in Solution Explorer in Figure 11-8.

   

   Figure 11-8. The solution

Establishing a project reference as described in the preceding steps copies the custom control assembly (.dll) to the /bin directory of the Web application. This makes the custom control available to the Web application. Any changes to the custom control assembly are automatically copied to the Web application s /bin directory.

As you develop your custom control, remember that changes aren t updated in the test Web application until you rebuild the custom control. That happens automatically when you run the application, but not when you switch between the custom control and the test Web application in Design mode. To see changes to the control in Design mode, you must rebuild the custom control before switching to the test application.

Adding the Custom Control to the Test Project

To test and debug the custom control during development, you must add an instance of the control to a Web form in the test Web application created in the preceding section.

To add a custom control to a Web form, follow these steps:

1. In the test Web application, display a Web form, and switch to HTML mode by clicking the HTML tab at the bottom left corner of the Design window.

2. Add a Register directive to the top of the Web form. For example, the following directive registers the custom control assembly named CompositeControls:

   <%@ Register TagPrefix="Custom" Namespace="CompositeControls"  Assembly="CompositeControls" %>

3. Create an instance of the custom control on the Web form using HTML syntax. For example, the following HTML creates an instance of WebCustomControl1 created in the preceding section:

   <Custom:WebCustomControl1  runat="server" />

For custom controls, the Register directive s three attributes have the meanings described in Table 11-2.

Table 11-2. The Register Directive's Attributes

Attribute	Description
TagPrefix	This name identifies the group that the user control belongs to. For example, the tag prefix for ASP.NET server controls is asp . You use this prefix to create a naming convention to organize your custom controls.
Namespace	This is the project name and namespace within the custom control assembly that contains the controls to register. Microsoft Visual Basic .NET uses the project name as an implicit namespace, so for controls written in Visual Basic .NET, use the project name.
Assembly	This is the name of the assembly (.dll) containing the custom controls. The control assembly must be referenced by the Web application. As mentioned, referencing the assembly maintains a copy of it in the Web application s /bin directory.

The @Register directive s TagPrefix makes up the first part of the name you use in the custom control s HTML element. The second part is the project name and class name of the control within the assembly. TagPrefix= Custom and the class name WebCustomControl1 mean that you create the custom control using an HTML <Custom:WebCustomControl1 /> element.

Custom controls can exist alongside and interact with other controls on a Web form. For example, the following HTML shows the WebControl1 custom control next to a Button control:

<%@ Page Language="vb" AutoEventWireup="false" Codebehind="Default.aspx.vb"  Inherits="MCSDWebAppsVB.CustomControl"%> <%@ Register TagPrefix="Custom" NameSpace="CompositeControls "  Assembly="CompositeControls" %> <HTML> <body> <form  method="post" runat="server"> <asp:button  runat="server" /> <Custom:WebCustomControl1  runat="server"  Text="This is a custom control" /> </form> </body> </HTML>

Notice that the custom control includes an attribute for the Text property. The control s HTML attributes provide a way to set the control s properties from HTML. Unlike user controls, custom controls are displayed correctly in the Visual Studio .NET Designer, as shown in Figure 11-9.

Figure 11-9. The WebControl1 custom control on a Web form (at design time)

Another thing you should notice about custom controls is that when they are selected in the Visual Studio .NET Designer, their properties appear in the Properties window. Again, unlike user controls, custom controls are fully supported by Visual Studio .NET.

To use the custom control in code, simply refer to it as you would any other control. For example, the following Button Click event procedure increments the value shown in the WebCustomControl1 custom control:

Visual Basic .NET

Private Sub butAdd_Click(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles butAdd.Click ' Increment the Text property of the custom control. custTest.Text = Val(custTest.Text) + 1 End Sub

Visual C#

private void butAdd_Click(object sender, System.EventArgs e) { // Convert the string to a number. int intText = 0; try { intText = int.Parse(custTest.Text); } catch { intText = 0; } // Increment the number. intText ++; // Display result in control custTest.Text = intText.ToString(); }

When you run the preceding code as part of a test Web application, ASP.NET displays the Web form with the custom control and the Button server control, as shown in Figure 11-10.

Figure 11-10. The WebControl1 custom control on a Web form (at run time)

If you click the Button control in this example more than once, the displayed value never gets past 1. Whoa! What gives? The custom control template that Visual Studio .NET creates doesn t take steps to save properties between page displays. To do that, you ll need to add code, as described in the following sections.

Creating the Composite Control s Appearance

You create the visual interface of composite custom controls by adding existing server or HTML controls to the Controls collection in the CreateChildControls method. The custom control s CreateChildControls method overrides the method in the base class.

The following code shows how to create a composite custom control s appearance. The code creates a composite custom control named MathBox. The MathBox control contains TextBox, Button, and Label controls, which are declared at the class level so that they are available to all procedures in the class. The CreateChildControls procedure adds these controls and some Literal controls to the custom control s Controls collection to create the custom control s appearance.

Visual Basic .NET

Public Class MathBox Inherits System.Web.UI.WebControls.WebControl Dim txtMath As New TextBox() Dim butSum As New Button() Dim lblResult As New Label() ' Create control's appearance. Protected Overrides Sub CreateChildControls() ' Add the sub controls to this composite control. ' Set the TextMode property and add textbox. txtMath.TextMode = TextBoxMode.MultiLine Controls.Add(txtMath) ' Start a new line Controls.Add(New LiteralControl("<br>")) ' Set the Text property and add the Button control. butSum.Text = "Sum" Controls.Add(butSum) ' Add Label and Literals to display result. Controls.Add(New LiteralControl("&nbsp&nbspResult:&nbsp<b>")) Controls.Add(lblResult) Controls.Add(New LiteralControl("</b>")) End Sub End Class

Visual C#

public class MathBox : System.Web.UI.WebControls.WebControl { TextBox txtMath = new TextBox(); Button butSum = new Button(); Label lblResult = new Label(); private string text; protected override void CreateChildControls() { // Add the sub controls to this composite control. // Set the TextMode property and add textbox. txtMath.TextMode = TextBoxMode.MultiLine; Controls.Add(txtMath); // Start a new line Controls.Add(new LiteralControl("<br>")); // Set the Text property and add the Button control. butSum.Text = "Sum"; Controls.Add(butSum); // Add Label and Literals to display result. Controls.Add(new LiteralControl("&nbsp&nbspResult:&nbsp<b>")); Controls.Add(lblResult); Controls.Add(new LiteralControl("</b>")); } }

The MathBox class shown in the preceding code is used as the basis for the rest of this lesson. If you add it to the composite control project created in the preceding sections, you can add it to the test Web application using the same @Register directive you added for the WebCustomControl1, and you ll create an instance of the control with the following HTML:

<Custom:MathBox  runat="server" />

If you add the MathBox custom control to a Web form at this point, you ll notice it appears as only a small green box at design time. At run time, however, the control will appear as shown in Figure 11-11.

Figure 11-11. The MathBox custom control (at run time)

The MathBox custom control doesn t have a design-time appearance at this point because it does not yet expose any design-time properties. That problem is remedied in the next section.

You don t need to override the Render method when creating a composite custom control. The custom control code template that Visual Studio .NET generates overrides this method. Therefore, if you re using the template, you must delete the generated Render method or change it to delegate back to the base class (making it a null operation), as shown here:

Visual Basic .NET

' Delegate back since not needed in composite control. Protected Overrides Sub Render(ByVal writer As HtmlTextWriter) MyBase.Render(writer) End Sub

Visual C#

// Delegate back since not needed in composite control. protected override void Render(HtmlTextWriter output) { base.Render(output); }

Creating Properties and Methods

The MathBox custom control will add a list of numbers entered in its text box and return the result. From a design standpoint, that requires two properties: Values, which contains an array of numbers; and Result, which contains the sum of those numbers. It also implies a Sum method to perform the calculation.

The following code shows the Values and Result properties and the Sum method used by MathBox. It also includes a Text property for consistency with the ASP.NET server controls and to simplify setting default text from HTML attributes.

Visual Basic .NET

' MathBox Properties and Methods. <DefaultValue("")> Property Text() As String Get ' Make sure child controls exist. EnsureChildControls() ' Return the text in the TextBox control. Return txtMath.Text End Get Set(ByVal Value As String) ' Make sure child controls exist. EnsureChildControls() ' Set the text in the TextBox control. txtMath.Text = Value End Set End Property Property Values() As String() Get EnsureChildControls() ' Return an array of strings from the TextBox. Return txtMath.Text.Split(Chr(13)) End Get Set(ByVal Value() As String) EnsureChildControls() ' Set the text in the TextBox from an array. txtMath.Text = String.Join(Chr(13), Value) End Set End Property ReadOnly Property Result() As String Get EnsureChildcontrols() ' Return the result from the Label. Return lblResult.Text End Get End Property Sub Sum() EnsureChildcontrols() ' If there is text in the TextBox. If txtMath.Text.Length Then ' Break the text into an array, line by line. Dim arrNums As String() arrNums = txtMath.Text.Split(Chr(13)) Dim strCount As String, dblSum As Double ' Add each element in the array together. For Each strCount In arrNums ' Use error handling to ignore non-number entries. Try dblSum += Convert.ToDouble(strCount) Catch End Try Next ' Display the result in the label. lblResult.Text = dblSum.ToString Else lblResult.Text = "0" End If End Sub

Visual C#

// MathBox properties and methods. [DefaultValue("0")] public string Text { get { // Make sure child controls exist. EnsureChildControls(); // Return the text in the TextBox control. return txtMath.Text; } set { // Make sure child controls exist. EnsureChildControls(); // Set the text in the TextBox control. txtMath.Text = value; } } char[] strSep = {'\r'}; public string[] Values { get { EnsureChildControls(); // Return an array of strings from the TextBox. return txtMath.Text.Split(strSep); } set { EnsureChildControls(); // Set the text in the TextBox from an array. txtMath.Text = String.Join(" ", value); } } public string Result { get { EnsureChildControls(); // Return the result from the Label. return lblResult.Text; } } public void Sum() { EnsureChildControls(); // If there is text in the TextBox. if (txtMath.Text.Length != 0) { // Break the text into an array, line by line. string[] arrNums; arrNums = txtMath.Text.Split(strSep); double dblSum = 0; // Add each element in the array together. foreach (string strCount in arrNums) { // Use error handling to // ignore non-number entries. try { dblSum += Convert.ToDouble(strCount); } catch { } } // Display the result in the label. lblResult.Text = dblSum.ToString(); } else lblResult.Text = "0"; } }

The EnsureChildControls statement in the preceding code ensures that the child controls have been instantiated. You use this in a composite control before referring to any contained controls.

After you add properties and methods to the composite control, rebuild the control to update the control s assembly. At that point, the composite control should appear in Design mode as well as at run time, as shown in Figure 11-12.

Figure 11-12. The MathBox custom control (at design time)

In Visual Studio .NET, version 1.0, custom controls may not always appear at design time. If this happens, you can usually cause them to appear by setting one of the custom control s properties, as shown by the following HTML:

<Custom:MathBox  runat="server" Text="0" />

Because composite controls use their base class s Render method, they automatically support absolute positioning with grid layout. In other words, you can drag composite controls to various positions on a Web form, and they will be displayed there at run time.

Handling Events

So far, the MathBox control can accept values, perform calculations, and display a result, but if you click the Sum button, it doesn t do any of that.

To enable the Sum button, follow these steps:

1. Add an event handler for the button s Click event to the CreateChildControls procedure using the AddHandler method.

2. Create a procedure to handle the event. This procedure has to have the same arguments and return type as the button s Click event.

The following code shows the additions to the MathBox control in boldface. Notice that the event procedure simply calls the Sum method created earlier to perform the calculation and display the result.

Visual Basic .NET

Protected Overrides Sub CreateChildControls() ' Add the sub controls to this composite control. ' Set the TextMode property and add textbox. txtMath.TextMode = TextBoxMode.MultiLine Controls.Add(txtMath) ' Start a new line Controls.Add(New LiteralControl("<br>")) ' Set the Text property and add the Button control. butSum.Text = "Sum" Controls.Add(butSum) ' Add Label and Literals to display result. Controls.Add(New LiteralControl("&nbsp&nbspResult:&nbsp<b>")) Controls.Add(lblResult) Controls.Add(New LiteralControl("</b>")) ' Add a handler for the Button's Click event. AddHandler butSum.Click, AddressOf Me.butSumClickedEnd Sub ' Event procedure for Button Click Sub butSumClicked(ByVal source As Object, ByVal e As EventArgs) ' Call the Sum method. Sum() End Sub

Visual C#

protected override void CreateChildControls() { // Add the sub controls to this composite control. // Set the TextMode property and add textbox. txtMath.TextMode = TextBoxMode.MultiLine; Controls.Add(txtMath); // Start a new line Controls.Add(new LiteralControl("<br>")); // Set the Text property and add the Button control. butSum.Text = "Sum"; Controls.Add(butSum); // Add Label and Literals to display result. Controls.Add(new LiteralControl("&nbsp&nbspResult:&nbsp<b>")); Controls.Add(lblResult); Controls.Add(new LiteralControl("</b>")); // Add event handler. butSum.Click += new EventHandler(butSumClicked);} void butSumClicked(object sender, EventArgs e) { // Call the Sum method. Sum(); }

Raising Events

In addition to handling the Sum button s Click event, you might want to raise an event that can be handled from the Web form containing the custom control.

To raise an event from a custom control, follow these steps:

1. Add a public event declaration to the custom control s class.

2. Raise the event from code within the custom control using the control s event method.

The following code shows how to declare and raise an event from within the MathBox control class:

Visual Basic .NET

' Declare an event Event Click(ByVal sender As Object, ByVal e As EventArgs) ' Event procedure for Button Click Sub butSumClicked(ByVal source As Object, ByVal e As EventArgs) ' Call the Sum method. Sum() ' Call method to raise event. OnClick(EventArgs.Empty) End Sub Protected Overridable Sub OnClick(ByVal e As EventArgs) ' Raise the event. RaiseEvent Click(Me, e) End Sub

Visual C#

// Declare the event. public event EventHandler Click; void butSumClicked(object sender, EventArgs e) { // Call the Sum method. Sum(); // Call the event method. OnClick(EventArgs.Empty); } protected virtual void OnClick(EventArgs e) { if (Click != null) // Raise the event. Click(this, e); }

To make the Click event the default event for the control, add a DefaultEvent attribute to the class declaration. A default event is the event that Visual Studio .NET automatically creates when you double-click the control within the Web form. The following code shows the addition in boldface:

Visual Basic .NET

<DefaultEvent("Click")> Public Class MathBox

Visual C#

[DefaultEvent("Click")] public class MathBox : System.Web.UI.WebControls.WebControl

To use the MathBox control s event from a Web form, double-click the control in the test Web form and use the following event procedure:

Visual Basic .NET

Private Sub mathTest_Click(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles mathTest.Click Response.Write(mathTest.Result) End Sub

Visual C#

private void mthTest_Click(object sender, System.EventArgs e) { Response.Write(mthTest.Result.ToString()); }

Handling Control Resizing

Composite controls handle a lot of design-time and run-time display features automatically through their base class s Render method. However, they can t automatically resize their child controls because there is no reasonable way to tell what type of resizing behavior is appropriate.

To handle resizing composite controls, follow these steps:

1. Override the base class s Render method.

2. Add code to resize the child controls as appropriate.

3. Call the base class s Render method to display the control.

The following code resizes a TextBox child control based on the width and height of the MathBox control:

Visual Basic .NET

Protected Overrides Sub Render(ByVal writer As _ System.Web.UI.HtmlTextWriter) EnsureChildcontrols() ' Resize text box to match control width. txtMath.Width = Me.Width ' Resize text box to match control height. txtMath.Height = Unit.Parse(Me.Height.Value butSum.Height.Value) ' Render the control. MyBase.Render(writer) End Sub

Visual C#

protected override void Render(HtmlTextWriter output) { EnsureChildControls(); // Resize text box to match control width. txtMath.Width = this.Width; // Resize text box to match control height. double dHeight = this.Height.Value - butSum.Height.Value; txtMath.Height = Unit.Parse(dHeight.ToString()); // Render the control. base.Render(output); }

Superclassing Server Controls

The preceding sections showed you how to create a composite control from multiple existing controls. You can use the same techniques to create new controls from an existing single control to add properties, methods, or events for that control or to change the behavior of that control.

Because that type of custom control is based on only one control, you can derive directly from that control s class rather than using the more general class of WebControl. Custom controls of this type aren t really composite controls they re sometimes referred to as superclassed controls.

For example, the following SuperText class creates a custom control based on the TextBox server control and adds a method to sort the contents of the text box:

Visual Basic .NET

Public Class SuperText Inherits System.Web.UI.WebControls.TextBox ' New method for the text box. Public Sub Sort() ' Create an array. Dim arrText As String() ' Put the words in the text box into the array. arrText = Me.Text.Split(" ") ' Sort the array. Array.Sort(arrText) ' Join the string and put it back in the text box. Me.Text = String.Join(" ", arrText) End Sub End Class

Visual C#

public class SuperText : System.Web.UI.WebControls.TextBox { public void Sort() { // Create an array. string[] arrText; // Put the words in the text box into the array. char[] strSep = {' '}; arrText = this.Text.Split(strSep); // Sort the array. Array.Sort(arrText); // Join the string and put it back in the text box. this.Text = String.Join(" ", arrText); } }

To use the control from a Web form, register the control s assembly as shown in the preceding examples, and include the following HTML on a Web form:

<Custom:SuperText  runat="server"  /> <asp:Button  Runat="server" Text="Sort"  />

To test the Sort method, add the following code to the Web form s code module:

Visual Basic .NET

Private Sub butSort_Click(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles butSort.Click superTest.Sort() End Sub

Visual C#

private void butSort_Click(object sender, System.EventArgs e) { superTest.Sort(); }

At either run time or design time, the SuperText control behaves just like a normal TextBox, as shown in Figure 11-13.

Figure 11-13. SuperText in action