Declarative Persistence of Simple Properties

The ASP.NET parser supports a declarative model for setting properties on controls as attributes on the control's tag. This declarative model works with custom controls just as it does with standard ASP.NET controls and greatly simplifies the customization of controls by a page developer. As with standard controls, property values in a custom control can also be set programmatically (in code) in the containing page.

The following example recapitulates the declarative syntax for setting a property as an attribute on the control's tag:

 <asp:TextBoxid="textBox1" Text="Enteryourname" ForeColor="Black"  runat="server" /> 

The page parser converts the property value to and from its textual format by using an instance of a type converter class. A type converter class derives from System.ComponentModel.TypeConverter and is capable of converting from a string representation to the given type as well as from the given type to a string representation. Commonly used types such as Int32 , Boolean , and enumeration types have corresponding type converters implemented in the .NET Framework ( System.ComponentModel.Int32Converter , System.ComponentModel.BooleanConverter , and System.ComponentModel.EnumConverter , respectively). Therefore, when you define a property whose type corresponds to a common built-in type, you do not have to do anything special to enable declarative syntax for that property. Note that type conversion is performed on the page for declarative syntax only. When the property is set in code, the assigned value must match the type of the property, as shown in the following code fragment:

 TextBox1.ForeColor=Color.Black; 

To enable declarative persistence when you define a property of a custom type, you must implement a custom type converter that provides the logic to convert the property from its textual representation to its declared type. For example, ASP.NET defines a type converter ( System.Web.UI.WebControls.WebColorConverter ) that performs string-to-value conversions for the System.Drawing.Color type properties of WebControl , such as ForeColor and BackColor . In the previous example, the ForeColor property on a TextBox instance is assigned declaratively by using a color name ( ForeColor="Black") . The page parser uses the WebColorConverter to convert the text string that specifies the color (as a name or as #RRGGBB notation) into a Color object and assigns it to the ForeColor or BackColor property. In Chapter 10, we'll look at an example of implementing a type converter and associating it with a property.

At the end of this chapter, we'll implement simple properties of several different types ( Int32 , String , and enumeration) in the PageTracker sample control.

Declarative Syntax for Enumeration Properties

In declarative syntax, you set an enumerated property by specifying the enumeration value without using the type name of the enumeration. In the following example, we set the TextMode property of a System.Web.UI.WebCon ­trols.TextBox control to a value from the System.Web.UI.WebControls.TextBoxMode enumeration:

 <asp:TextBoxid="textBox1" TextMode="MultiLine" runat="server" /> 

The page parser resolves MultiLine as TextBoxMode.MultiLine by inferring the enumeration type from the property type. However, when you set an enumerated property in code, you must use the standard enumeration syntax, as shown in the following code fragment:

 textBox1.TextMode=TextBoxMode.MultiLine; 

When you expose enumeration properties from your control, you do not have to do any additional work in terms of parsing or persisting to enable the declarative enumeration syntax. The System.ComponentModel.EnumConverter type converter that the .NET Framework automatically associates with all enumeration types provides this functionality. In addition, the EnumConverter provides special editing support in the designer, which enables the property browser to display the enumeration values as choices in a drop-down list.