You want to create a custom control
with HTML-style attributes that can
be used to customize the appearance of the control in the
.aspx
file.
Create the basic custom control (as described in Recipe 5.1), add properties to the class, and then use the values of the properties when rendering the control’s HTML output.
Use the .NET language of your choice to:
Create a class that inherits from the Control
class in the System.Web.UI
namespace.
Implement support for the HTML-style attributes by adding properties to the class.
Override the Render
method to have it render the
HTML output of the control using the values of the properties.
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 and set the attributes appropriately.
To illustrate this solution, we started with the sample custom control we built for Recipe 5.1 and then added support for HTML-style attributes, such as an attribute that defines the color used to display label text. Figure 5-2 shows some output using default and modified attributes for the control; in the case of the latter, the Enter Age: label text actually appears in red when rendered on the screen. Example 5-4 and Example 5-5 show the VB and C# class files for our custom control. Example 5-6 shows how to use the custom control in an ASP.NET page to produce these results.
Recipe 5.1 describes how to create a basic custom control, so we’ll skip that discussion here. Instead we’ll focus on implementing HTML-style attributes for a custom control.
Custom control properties provide the ability to programmatically
change aspects of the control using HTML-style attributes, which can
be set in the .aspx
file or code-behind.
Attributes are a common feature of ASP.NET server controls. For
example, the image button control provides an
ImageURL
attribute that you can set to define the
image that is to be displayed when the control is rendered:
<asp:ImageButton ID="btnSubmit" Runat="server" ImageUrl="button_submit.gif" />
Attributes are implemented in a custom control by adding properties to the class. The properties are no different than properties in a class implemented as a business or data service. The names of the properties define the names of the attributes that can be used with the custom control.
To illustrate this approach, we’ve provided the code
in Example 5-4 (VB) and Example 5-5
(C#) that defines a custom
control named
CustomControlAttributesVB
or
CustomControlAttributesCS
with the properties
shown in Table 5-1.
Table 5-1. Custom control properties
Property |
Data type |
Description |
---|---|---|
|
|
Defines the text for the label |
|
|
Defines the color used to display the label text |
|
|
Defines the width of the text box |
When you define custom control properties, you should always
initialize each property by assigning it a default value. For
example, in Example 5-4 and Example 5-5, we’ve assigned the private
variable used to store the labelText
property an
initial value of "Label:
“, the private variable
used to store the textColor
property value has
been given an initial value of Color.Black
, and
the private variable used to store the
textboxWidth
property value has been given an
initial value of 3
. Initializing properties in
this manner allows your control to handle the condition when the
programmer does not include a value for the attribute that
corresponds to a particular property.
To use a custom control, it must first be registered in the target
.aspx
file, as described in Recipe 5.1. For instance, here’s
how to register the VB version of the custom control in our example:
<%@ Register TagPrefix="ASPCookbook" Namespace="ASPNetCookbook.VBExamples" Assembly="ASPNetCookbookVB" %>
You can use the control as is if the default label text, text color, and text box width are acceptable.
<ASPCookbook:CH05CustomControlAttributesVB id="ccAttributes1" runat="server" />
Or, you can set the attributes to customize the look of the control for a particular page.
<ASPCookbook:CH05CustomControlAttributesVB id="ccAttributes2" runat="server"labelText = "Enter Age: "
textColor="#FF0000"
textboxWidth="10" />
Before a custom control’s attributes can be set in
the code-behind, the control must first be declared, just like any
other server control. For example, here’s how you
declare the custom control in the code-behind of our sample
application and then set the control’s
textColor
attribute to green:
Protected ccAttributes1 As CustomControlAttributesVB .. ccAttributes1.textColor = Color.Green protected CustomControlAttributesCS ccAttributes1; .. ccAttributes1.textColor = Color.Green;
One thing to consider when implementing the properties of a custom
control is that ASP.NET will match the names of the attributes in the
custom control tag (.aspx
file) with the names
of the properties in the class that implements the custom control.
What’s more, because all attribute values in the
.aspx
file are effectively strings, ASP.NET
provides the type conversion necessary to match the type required for
the property.
If ASP.NET cannot convert the attribute value to the type required
for the property, a parse exception will be thrown when the page is
displayed. For example, if a property is an integer type and the
value "abc
" is set as the attribute value, a parse
exception will be thrown. If you set the attributes in the
.aspx
file, there really is no way to prevent
this other than to make sure you test the code thoroughly.
Alternately, you can set the values in the code-behind, which will
generally catch errors of this type during compilation instead of at
runtime.
Example 5-4. Custom control with attributes (.vb)
Option Explicit On Option Strict On '----------------------------------------------------------------------------- ' ' Module Name: CH05CustomControlAttributesVB.vb ' ' Description: This class provides a custom control with attributes to ' provide the ability to alter the control programmically. ' '***************************************************************************** Imports System Imports System.drawing Imports System.Web Imports System.Web.UI Namespace ASPNetCookbook.VBExamples Public Class CH05CustomControlAttributesVB Inherits Control'private copies of attribute data
Private mLabelText As String = "Label: "
Private mTextColor As Color = Color.Black
Private mTextboxWidth As Integer = 3
'************************************************************************* ' ' ROUTINE: labelText ' ' DESCRIPTION: This property provides the ability to set the text of ' of the label in the control '-------------------------------------------------------------------------Public Property labelText( ) As String
Get
Return (mLabelText)
End Get
Set(ByVal Value As String)
mLabelText = Value
End Set
End Property 'labelText
'************************************************************************* ' ' ROUTINE: textColor ' ' DESCRIPTION: This property provides the ability to set the color ' of the text in the control '-------------------------------------------------------------------------Public Property textColor( ) As Color
Get
Return (mTextColor)
End Get
Set(ByVal Value As Color)
mTextColor = Value
End Set
End Property 'textColor
'************************************************************************* ' ' ROUTINE: textboxWidth ' ' DESCRIPTION: This property provides the ability to set the width ' of the textbox in the control '-------------------------------------------------------------------------Public Property textboxWidth( ) As Integer
Get
Return (mTextboxWidth)
End Get
Set(ByVal Value As Integer)
mTextboxWidth = Value
End Set
End Property 'textboxWidth
'************************************************************************* ' ' ROUTINE: Render ' ' DESCRIPTION: This routine renders the HTML output of the control '------------------------------------------------------------------------- Protected Overrides Sub Render(ByVal writer As HtmlTextWriter) 'output label within a font tagwriter.AddAttribute("color", _
ColorTranslator.ToHtml(textColor))
writer.RenderBeginTag(HtmlTextWriterTag.Font)writer.Write(labelText)
writer.RenderEndTag( ) 'output input control writer.AddAttribute(HtmlTextWriterAttribute.Type, _ "text")writer.AddAttribute(HtmlTextWriterAttribute.Size, _
textboxWidth.ToString( ))
writer.RenderBeginTag(HtmlTextWriterTag.Input) writer.RenderEndTag( ) End Sub 'Render End Class 'CH05CustomControlAttributesVB End Namespace
Example 5-5. Custom control with attributes (.cs)
//---------------------------------------------------------------------------- // // Module Name: CH05CustomControlAttributesCS // // Description: This class provides a custom control with attributes to // provide the ability to alter the control programmically. // //**************************************************************************** using System; using System.Drawing; using System.Web; using System.Web.UI; namespace ASPNetCookbook.CSExamples { public class CH05CustomControlAttributesCS : Control {// private copies of attribute data
private String mLabelText = "Label: ";
private Color mTextColor = Color.Black;
private int mTextboxWidth = 3;
//************************************************************************ // // ROUTINE: labelText // // DESCRIPTION: This property provides the ability to set the text // of the label in the control //------------------------------------------------------------------------public String labelText
{
get
{
return(mLabelText);
}
set
{
mLabelText = value;
}
} // labelText
//************************************************************************ // // ROUTINE: textColor // // DESCRIPTION: This property provides the ability to set the color // of the text in the control //------------------------------------------------------------------------public Color textColor
{
get
{
return(mTextColor);
}
set
{
mTextColor = value;
}
} // textColor
//************************************************************************ // // ROUTINE: textboxWidth // // DESCRIPTION: This property provides the ability to set the width // of the textbox in the control //------------------------------------------------------------------------public int textboxWidth
{
get
{
return(mTextboxWidth);
}
set
{
mTextboxWidth = value;
}
} // textboxWidth
//************************************************************************ // // ROUTINE: Render // // DESCRIPTION: This routine renders the HTML output of the control //------------------------------------------------------------------------ protected override void Render(HtmlTextWriter writer) { //output labelwriter.AddAttribute("color",
ColorTranslator.ToHtml(textColor));
writer.RenderBeginTag(HtmlTextWriterTag.Font);writer.Write(labelText);
writer.RenderEndTag( ); //output input control writer.AddAttribute(HtmlTextWriterAttribute.Type, "text");writer.AddAttribute(HtmlTextWriterAttribute.Size,
textboxWidth.ToString( ));
writer.RenderBeginTag(HtmlTextWriterTag.Input); writer.RenderEndTag( ); } // Render } // CH05CustomControlAttributesCS }
Example 5-6. Using the custom control with attributes (.aspx)
<%@ Page Language="vb" AutoEventWireup="false" Codebehind="CH05DisplayControlWithAttributesVB.aspx.vb" Inherits="ASPNetCookbook.VBExamples.CH05DisplayControlWithAttributesVB" %><%@ Register TagPrefix="ASPCookbook" Namespace="ASPNetCookbook.VBExamples"
Assembly="ASPNetCookbookVB" %>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html> <head> <title>Display Custom Control With Attributes</title> <link rel="stylesheet" href="css/ASPNetCookbook.css"> </head> <body leftmargin="0" marginheight="0" marginwidth="0" topmargin="0"> <form id="frmCustomControl" method="post" runat="server"> <table width="100%" cellpadding="0" cellspacing="0" border="0"> <tr> <td align="center"> <img src="images/ASPNETCookbookHeading_blue.gif"> </td> </tr> <tr> <td class="dividerLine"> <img src="images/spacer.gif" height="6" border="0"></td> </tr> </table> <table width="90%" align="center" border="0"> <tr> <td><img src="images/spacer.gif" height="10" border="0"></td> </tr> <tr> <td align="center" class="PageHeading"> Custom Control With Attributes (VB) </td> </tr> <tr> <td><img src="images/spacer.gif" height="10" border="0"></td> </tr> <tr> <td>With Default Attributes:</td> </tr> <tr bgcolor="#ffffcc"> <td align="center"><ASPCookbook:CH05CustomControlAttributesVB
id="ccAttributes1" runat="server" />
</td> </tr> <tr> <td><br />With Modified Attributes:</td> </tr> <tr bgcolor="#ffffcc"> <td align="center"><ASPCookbook:CH05CustomControlAttributesVB
id="ccAttributes2" runat="server"
labelText = "Enter Age: "
textColor="#FF0000"
textboxWidth="10" />
</td> </tr> <tr> <td align="center"> <br> <asp:ImageButton ID="btnSubmit" Runat="server" ImageUrl="images/buttons/button_submit.gif" /> </td> </tr> </table> </form> </body> </html>