Problem You want to create a custom control that combines two or more HTML controls. Solution Use the .NET language of your choice to: Create a class that inherits from the WebControl class in the System.Web.UI.WebControls namespace. Override the Render method to have it output the HTML controls you wish to include. (Optional) Use the HtmlTextWriter class to enhance your chances of writing well-formed HTML.
To use the custom control in an ASP.NET page: Register the assembly containing the control. Insert the tag for the custom control anywhere in the page.
Figure 6-1 shows the output of a custom control that combines a label and text box. Examples 6-1 and 6-2 show the VB and C# class files for the custom control. Example 6-3 shows how to use the custom control in an ASP.NET page. Figure 6-1. Basic custom control output 
Discussion To create a custom control that combines the functionality of two or more HTML controls, you first create a class that inherits from the WebControl class in System.Web.UI.WebControls. The only method of WebControl required to output HTML is the Render method. Render is responsible for writing the HTML that will be rendered by the browser. To enhance your ability to write well-formed HTML, you can use other methods of the HtmlTextWriter class along with the HtmlTextWriterAttribute and HtmlTextWriterTag enumerations. We'll talk more about this in a minute, but for now we'll stick with writing our own unvarnished HTML. The custom control we have implemented in our example contains a label and an input control. The label and input control are output in the Render method with the following code: 
writer.Write("Enter Age: ") writer.Write("<input type='text' size='3' />") 
writer.Write("Enter Age: "); writer.Write("<input type='text' size='3' />");
To use the custom control, the assembly containing the control must be registered in the target .aspx file. The TagPrefix attribute defines an alias to use for the namespace in the page. The Namespace attribute must be set to the fully qualified namespace of the control. Here is how you register the assembly in our example: <%@ Register TagPrefix="ASPCookbook" Namespace="ASPNetCookbook.VBExamples"; %>
 | If you place the source code for your custom controls in the App_Code folder of your project, ASP.NET 2.0 will dynamically compile the code into an assembly. If you do not include the Assembly attribute in the @ Register directive, the assembly created by compiling the code in the App_Code folder will be inferred. If you precompile your source code into an explicit assembly, the Assembly attribute of the @ Register directive must be included to inform ASP.NET where to locate the custom control. |
|
The custom control can be placed anywhere on the page by inserting a tag. The control to insert is identified by naming the tag with the TagPrefix followed by the class name. The tag must include the id and runat="server" attributes for the control to be rendered on the page. This is the tag used in our example: <ASPCookbook:CH06QuickAndDirtyCustomControlVB1 runat="server" />
In our example, raw HTML is written to the web page in the Render method. For simple HTML, this works well. As the complexity of the HTML you write increases, however, the likelihood that you'll introduce errors increases. Fortunately, HtmlTextWriter includes methods that simplify the generation of complex HTML. These methods can help you with the nuances of adding HTML attributes (and values) to an HTMLTextWriter output stream, writing beginning and ending tags, flushing buffers so all buffered data is written to the text stream, etc. To create the input box in our example, you could use the HtmlTextWriter like this:
Protected Overrides Sub Render(ByVal writer As HtmlTextWriter) 'output label writer.Write("Enter Age: ") 'output input control writer.AddAttribute(HtmlTextWriterAttribute.Type, _ "text") writer.AddAttribute(HtmlTextWriterAttribute.Size, _ "3") writer.RenderBeginTag(HtmlTextWriterTag.Input) writer.RenderEndTag() End Sub 'Render
protected override void Render(HtmlTextWriter writer) { //output label writer.Write("Enter Age: "); //output input control writer.AddAttribute(HtmlTextWriterAttribute.Type, "text"); writer.AddAttribute(HtmlTextWriterAttribute.Size, "3");
writer.RenderBeginTag(HtmlTextWriterTag.Input); writer.RenderEndTag(); } // Render
One advantage of implementing the Render method in this way is that you can use the RenderBeginTag and RenderEndTag methods to output HTML and sidestep having to insert the <, /, and > characters yourself. In addition, using the HtmlTextWriterTag and HtmlTextWriterAttribute enumerations ensures all tags and attributes are correctly spelled. Another advantage is that you can avoid the hassle of ensuring the single and double quotes are handled correctly. Notice in the first example that the values for the attributes of the input tag were output with single quotes, since double quotes mark the beginning and end of strings. Outputting double quotes around the values would have required more complex code with string concatenations. Using the AddAttribute method avoids this problem completely. | You must call the AddAttribute method immediately before you call the RenderBeginTag method, which writes the opening tag of the associated HTML element. This is required because the HtmlTextWriter builds a collection of attributes to output in the opening tag of the HTML element. When the RenderBeginTag method is called, the attributes are output in the opening tag and then the collection is cleared. |
|
A useful enhancement to this approach would be to add HTML-style attributes to the control to make the control more adaptable and reusable throughout your applications. See Recipe 6.2 for how to do this. | If you are going to use your custom controls on multiple pages in your application and would like to avoid having to place the @ Register directive in each page, register the controls in the web.config file. To register the custom control for this recipe, for example, the following would be added to the web.config file: <system.web> <!-- Register controls that are to be used on multiple pages to eliminate the need to add an @Register directive to each page. --> <pages> <controls> <add tagPrefix="ASPCookbookControls" namespace="ASPNetCookbook.VBExamples" /> </controls> </pages> </system.web>
|
|
See Also Recipe 6.2; for additional details on Control, Render, HtmlTextWriterTag, HtmlText-WriterAttribute, and especially HtmlTextWriter, search the MSDN Library Example 6-1. Quick-and-dirty custom control (.vb) Option Explicit On Option Strict On Namespace ASPNetCookbook.VBExamples ''' <summary> ''' This class provides the quick and dirty custom control example which ''' includes a label and a text box. The Control is rendered by writing ''' raw HTML to the output stream. ''' </summary> Public Class CH06QuickAndDirtyCustomControlVB1 Inherits WebControl '''*********************************************************************** ''' <summary> ''' This routine renders the HTML output of the control ''' </summary> ''' ''' <param name="writer">Set to the HtmlTextWriter to use to output the ''' rendered HTML for the control ''' </param> Protected Overrides Sub Render(ByVal writer As HtmlTextWriter) 'output label writer.Write("Enter Age: ") 'output input control writer.Write("<input type='text' size='3' />") End Sub 'Render End Class 'CH06QuickAndDirtyCustomControlVB1 End Namespace
|
Example 6-2. Quick-and-dirty custom control (.cs) using System.Web.UI; using System.Web.UI.WebControls; namespace ASPNetCookbook.CSExamples { /// <summary> /// This class provides the quick and dirty custom control example which /// includes a label and a text box. The Control is rendered by writing /// raw HTML to the output stream. /// </summary> public class CH06QuickAndDirtyCustomControlCS1 : WebControl { ///*********************************************************************** /// <summary> /// This routine renders the HTML output of the control /// </summary> /// /// <param name="writer">Set to the HtmlTextWriter to use to output the /// rendered HTML for the control /// </param> protected override void Render(HtmlTextWriter writer) { // output label writer.Write("Enter Age: "); // output input control writer.Write("<input type='text' size='3' />"); } // Render } // CH06QuickAndDirtyCustomControlCS1 }
|
Example 6-3. Using the quick-and-dirty custom control <%@ Page Language="VB" MasterPageFile="~/ASPNetCookbookVB.master" AutoEventWireup="false" CodeFile="CH06DisplayQuickAndDirtyControlVB1.aspx.vb" Inherits="ASPNetCookbook.VBExamples.CH06DisplayQuickAndDirtyControlVB1" Title="Quick And Dirty Custom Control" %> <%@ Register TagPrefix="ASPCookbook" Namespace="ASPNetCookbook.VBExamples" %> <asp:Content Runat="server" ContentPlaceHolder> <div align="center" > Quick & Dirty Custom Control - Raw HTML Output (VB) </div> <table width="90%" align="center" border="0"> <tr bgcolor="#ffffcc"> <td align="center"> <ASPCookbook:CH06QuickAndDirtyCustomControlVB1 runat="server' /> </td> </tr> <tr> <td align="center"> <br/> <asp:Button runat="server" Text="Submit" /> </td> </tr> </table> </asp:Content>
|
| 