Introduction
When developing controls for a designer environment like Visual Studio or WebMatrix, the complexities of persisting control properties as serialized HTML can come into play. In many cases, the built-in serialization of control properties as attributes or nested child tags is sufficient. There are also several code attributes available to a control developer to apply a degree of customization for this process. In some cases however, a developer requires a greater degree of control over how control properties are persisted as HTML.
In this article, I present a custom ASP.NET server control for displaying color choices in a dropdown list. Following a description of the control, I will focus on the problem of persisting a custom collection of items in the context of the Visual Studio Web Form designer, and offer a solution using custom ControlDesigner
and ControlBuilder
objects.
HtmlColorDropDown Control
The HtmlColorDropDown
web control encapsulates an HTML dropdown list (i.e., <select>
tag) with colors for items (<option>
tags). The control can render the items themselves as foreground or background colors within the <option>
tags. The choice of colors offered is determined by the value of the Palette
property, which can be one of the following:
AllNamedColors
|
All named colors (not including System colors) available in the System.Drawing.KnownColor enumeration. |
Simple
|
A small subset of common named colors. |
WebSafe
|
The 216 colors considered "web-safe"; these use only hex values #FF, #CC, #99, #66, #33, and #00 for each of the red, green, and blue components. |
UserDefined
|
Colors identified by the control user through the UserDefinedColors property. |
The UserDefinedColors
property is a ColorCollection
object. ColorCollection
is a strongly-typed collection class inheriting from CollectionBase
, using standard System.Drawing.Color
objects for items.
The DisplayColorMode
property governs how colors will be displayed in each item, if at all:
ColorAsBackground
|
Display each item using its color for the background; foreground text is displayed in either black or white, depending on which offers a better contrast. |
ColorAsForeground
|
Display each item using its color for the foreground text. |
Plain
|
Do not display colors in the items. |
The selected item is available as a Color
object through the SelectedColor
property. The properties SelectedColorName
and SelectedColorHexString
return the name of the selected color (for named colors) and the HTML hex value (e.g., "#FFC309") as strings respectively. These are all read/write properties; the setting of one affects the value of all three. If an attempt is made to set the SelectedColor
to a color that doesn't exist in the current Palette
, a value of Color.Empty
is assigned instead. Likewise, if the Palette
is changed, SelectedColor
may be set to Color.Empty
if its existing value isn't among the new list of choices.
Note that the proper display of foreground or background colors rendered in <option>
tags is dependent on the browser. Most modern browsers interpret item colors identified as CSS properties through a style
attribute, without problems. Interestingly however, not all render the colors of the selected item when the dropdown is collapsed. To work around this, the AutoColorChangeSupport
property is provided. When true
(its default value), a small JavaScript onChange
handler is rendered with the control, causing the colors of the selected item to be assigned to the parent <select>
tag. The property may be set to false
to prevent this behavior.
The default event for the control is ColorChanged
. This event fires whenever the selection in the dropdown list has changed between postbacks to the server. The following is an example of an .aspx page where the ColorChanged
event is handled:
<%@ Page language="c#" %>
<%@ Register TagPrefix="cc1" Namespace="UNLV.IAP.WebControls"
Assembly="UNLV.IAP.WebControls.HtmlColorDropDown" %>
<script runat="server">
private void HtmlColorDropDown1_ColorChanged(object sender,
System.EventArgs e)
{
Label1.Text = HtmlColorDropDown1.SelectedColorName;
}
</script>
<html>
<head>
<title>Example</title>
</head>
<body>
<form runat="server">
<cc1:HtmlColorDropDown id="HtmlColorDropDown1" runat="server"
DisplaySelectColorItemText="--Select a Color--"
DisplaySelectColorItem="True"
AutoPostBack="True"
OnColorChanged="HtmlColorDropDown1_ColorChanged">
</cc1:HtmlColorDropDown>
<P>The selected color is: <asp:Label id="Label1" runat="server"/></P>
</form>
</body>
</html>
See the downloadable control documentation for a complete description of all HtmlColorDropDown
properties and events.
The Issue: Persisting the Collection of UserDefinedColors
This control was designed with both visual designer (e.g., Visual Studio) and text editor (e.g., Notepad) environments in mind. For designer environments, we inherit much functionality without any extra code. Because we're using regular System.Drawing.Color
objects for the SelectedColor
property for example, the standard ColorBuilder
becomes available within the Visual Studio web form designer.
Likewise, as we have standard Color
objects within the UserDefinedColors
collection, the Visual Studio collection builder is available at no charge:
A problem occurs however when it comes time to serialize this color collection into the server tag HTML. Typically, we would set the PersistenceMode
and DesignerSerializationVisibility
attributes on the collection property to have the collection items persisted as nested tags, like so:
[
PersistenceMode(PersistenceMode.InnerDefaultProperty)
,DesignerSerializationVisibility(
DesignerSerializationVisibility.Content)
]
public ColorCollection UserDefinedColors
{
get {...}
set {...}
}
With these attributes set, we can get the UserDefinedColors
collection persisted. The markup, however, appears as verbose <System.Drawing.Color>
tags, like the following:
<cc1:htmlcolordropdown id="HtmlColorDropDown1" runat="server"
Palette="UserDefined">
<System.Drawing.Color IsEmpty="False" A="255" B="0" IsNamedColor="True"
IsKnownColor="True" Name="Red" G="0" R="255" IsSystemColor="False">
</System.Drawing.Color>
<System.Drawing.Color IsEmpty="False" A="255" B="0" IsNamedColor="True"
IsKnownColor="True" Name="Green" G="128" R="0" IsSystemColor="False">
</System.Drawing.Color>
<System.Drawing.Color IsEmpty="False" A="255" B="255" IsNamedColor="True"
IsKnownColor="True" Name="Blue" G="0" R="0" IsSystemColor="False">
</System.Drawing.Color>
</cc1:htmlcolordropdown>
The problem isn't only in the fact that there is much more information about the colors persisted than we need or want. As the attributes represent read-only properties of the Color
object, an exception will be thrown upon parsing. It would be preferable to persist these inner items differently, with minimal information necessary, like the following:
<cc1:htmlcolordropdown id="HtmlColorDropDown1" runat="server"
Palette="UserDefined">
<Color value="Red"/>
<Color value="Green"/>
<Color value="Blue"/>
</cc1:htmlcolordropdown>
This also makes the control easier to work with for those using plain text editors. A custom ControlDesigner
can help us here in persisting the inner markup in this simplified manner, while a custom ControlBuilder
will help deserialize the <Color value="xxx"/>
tags upon parsing.
Custom Persistence through a ControlDesigner
In order to persist the UserDefinedColors
collection, we'll define a custom subclass of System.Web.UI.Design.ControlDesigner
. A ControlDesigner
's purpose is to provide design-time support for a web control, and it can do so in a number of ways. For example, a ControlDesigner
can be used to customize the HTML that is used to represent a control in a visual designer like Visual Studio. A ControlDesigner
may also be used to add support for the visual editing of control templates.
For the HtmlColorDropDown
control, we need the ability to customize the inner HTML that is serialized when a visual designer persists the object's properties to a web page. For this, we can subclass ControlDesigner
and override the GetPersistInnerHtml
method. The complete code for the subclassed HtmlColorDropDownDesigner
is as follows:
public class HtmlColorDropDownDesigner : ControlDesigner
{
public override string GetPersistInnerHtml()
{
StringWriter sw = new StringWriter();
HtmlTextWriter html = new HtmlTextWriter(sw);
HtmlColorDropDown dd
= this.Component as HtmlColorDropDown;
if (dd != null)
{
foreach(Color c in dd.UserDefinedColors)
{
string s =
(c.IsKnownColor ? c.Name
: ColorUtility.ColorToHexString(c) );
html.WriteBeginTag("Color");
html.WriteAttribute("value", s);
html.WriteLine(HtmlTextWriter.SelfClosingTagEnd);
}
}
return sw.ToString();
}
}
In the overridden GetPersistInnerHtml
method, we iterate through each System.Drawing.Color
item in the UserDefinedColors
property. For each color, we output a child tag in the form:
<Color value="xxx">
where xxx is either the name of the color (for known color items such as "Red") or its HTML hex string (e.g., "#FF0000"). Through this custom persistence, we can represent the full UserDefinedColors
collection without the problems and verbosity of serializing full Color
objects.
It is worthwhile to note that other methods are available for customizing how a control's properties are to be persisted. A TypeConverter
, for example, may be defined for custom types, which can then play a role in serialization. For that matter, a custom CodeDomSerializer
object can persist object properties as programming code rather than HTML. In the case of the HtmlColorDropDown
control, I chose a custom ControlDesigner
overriding GetPersistInnerHtml
as it offered a simple and direct solution for persisting the contents of the ColorCollection
.
The custom designer is associated with the main HtmlColorDropDown
control through the Designer
attribute. Other attributes are also important in this context. The PersistChildren(false)
attribute is applied to the control to ensure that properties are not otherwise persisted as nested server control tags. The PersistenceMode
and DesignerSerializationVisibility
attributes are still applied to the UserDefinedColors
property to ensure that our designer's GetPersistInnerHtml
method in fact has a reason to be called.
[
//...(other attributes)...//
,PersistChildren(false)
,Designer(typeof(HtmlColorDropDownDesigner))
]
public class HtmlColorDropDown : Control, IPostBackDataHandler
, IPostBackEventHandler, IAttributeAccessor
{
...
[
,PersistenceMode(PersistenceMode.InnerDefaultProperty)
,DesignerSerializationVisibility(
DesignerSerializationVisibility.Content)
]
public ColorCollection UserDefinedColors
{
get {...}
set {...}
}
...
}
Custom Parsing through a ControlBuilder
The custom HtmlColorDropDownDesigner
takes care of persisting the UserDefinedColors
collection as inner HTML content of the server tag. When the page is parsed, three separate classes work together to deserialize this inner content back into the UserDefinedColors
collection: a custom ControlBuilder
, a helper class representing a <Color value='xxx'/>
tag, and the main HtmlColorDropDown
control itself.
The first of the three is a subclass of System.Web.UI.ControlBuilder
. A ControlBuilder
object assists the page parser when building a server control from markup text. The HtmlColorDropDownBuilder
is defined as follows with only one overridden method:
public class HtmlColorDropDownBuilder : ControlBuilder
{
public override Type GetChildControlType(string tagName,
IDictionary attribs)
{
if (string.Compare(tagName,"color", true) == 0)
{
return typeof(ColorItemHelper);
}
return base.GetChildControlType (tagName, attribs);
}
}
The custom builder's GetChildControlType
method returns the type ColorItemHelper
for each <Color value='xxx'>
child tag nested within the server control markup. The ColorItemHelper
class is defined very simply:
public class ColorItemHelper
{
private string _value;
public string Value
{
get {return _value;}
set {_value = value;}
}
}
The custom builder is assigned to the HtmlColorDropDown
control through the ControlBuilder
attribute. The main HtmlColorDropDown
control then uses the ColorItemHelper
object passed to it from the parser to add the color to its UserDefinedColors
collection. This is done by overriding the AddParsedSubObject
method of the Control
class:
[
//...(other attributes)...//
, ParseChildren(false)
, ControlBuilder(typeof(HtmlColorDropDownBuilder))
]
public class HtmlColorDropDown : Control, IPostBackDataHandler
, IPostBackEventHandler, IAttributeAccessor
{
...
protected override void AddParsedSubObject(object obj)
{
if (obj is ColorItemHelper)
{
ColorItemHelper h = obj as ColorItemHelper;
this.UserDefinedColors.Add(h.Value);
}
else
base.AddParsedSubObject (obj);
}
...
}
Note that the ParseChildren(false)
attribute is applied to the main HtmlColorDropDown
class. This ensures that the nested inner HTML is not parsed as properties of the control, allowing our custom parsing to function.
Summary
The HtmlColorDropDown
web control renders a standard HTML <select>
tag with <option>
items representing color choices. The colors themselves may be rendered as the background or foreground color of each item. Three built-in palettes are offered; a fourth, UserDefined
, allows a control user to specify which colors to provide as choices in the list. To support the persistence of user defined colors within a visual designer, I used a custom ControlDesigner
, overriding the GetPersistInnerHtml
method to render colors as simple <Color value='xxx'/>
child tags. I also used a custom ControlBuilder
to assist in parsing the nested tags for the deserialization of the UserDefinedColors
collection. While techniques for custom property persistence and parsing may be tricky, such techniques offer important benefits for control authors and are worth consideration.
With a background in education, music, application development, institutional research, data governance, and business intelligence, I work for the University of Nevada, Las Vegas helping to derive useful information from institutional data. It's an old picture, but one of my favorites.