email article printer friendly get the code more resources

Roll Your Own Control Designers
It's not enough to build a great custom control to help your end users—you must also help other developers use your control.
by Peter Vogel

July 17, 2006

Technology Toolbox: Visual Basic, ASP.NET, XML

Your custom Web control has two audiences: the end user who interacts with the page that the control appears on, and the developer who uses your control to create that page.

Great custom controls support both audiences, making end users and developers more productive. Your first priority should always be to help end users accomplish their goals, but your second priority should always be to help the developer who is using your control do so more easily and with less effort. This means you should create a control designer that simplifies the development activities for your control after you provide the methods, properties, and events that make your control useful to that developer.

One way to support the developer using your custom control in Visual Studio 2005 is to give your control a SmartTag. A SmartTag supports developers in two ways. It provides quick access to frequently used properties, and it creates single-click solutions for common scenarios. I'll walk you through how to accomplish both of these tasks. The good news? Adding a SmartTag to your custom control isn't difficult. The key to creating a great SmartTag is to understand how developers will use your custom control (see Figure 1).

You must first create a control designer to add a SmartTag to your custom control. The easiest way to add the control designer to your project is to add a Web Custom Control, and then have the control inherit from the System.Web.UI.Design.ControlDesigner class in System.Design DLL. The System.Design DLL isn't one of the default references added to a project by the Visual Studio 2005 templates, so you need to add a reference to this DLL to your project.

You should remove the default code in the class module after you've changed the Inherits line because you won't need it. Creating the start point for your designer is easy:

Public Class ADesigner
Inherits System.Web.UI. _
Design.ControlDesigner
End Class

Once you create the control designer, you add a SmartTag to the class by overriding the designer's ActionLists property. A SmartTag consists of a list of items that you assemble in the ActionLists property from one or more DesignerActionList classes. Each DesignerActionList provides one or more items for the SmartTag. This architecture lets you create multiple DesignerActionList classes independent of any control, and then combine them as needed for any particular control. In the article's sample, you create a DesignerActionList that lets developers set a control's Text property (TextActionList) that you use with a variety of custom controls. You also create a second DesignerActionList that you tailor to work with a single custom control (FormatActionList) to simplify setting groups of formatting-related properties.

Create the ActionListCollection
Visual Studio might call the ActionLists property multiple times, so you don't want to recreate the ActionListCollection each time. Instead, declare the collection at the top of your class and, in the ActionLists property, create the collection only if it isn't already present (see Listing 1).

Next, define the two DesignerActionLists used in the ActionLists property. It's easier to start with the TextActionList, which allows the developer to set a commonly used property (the Text property) without resorting to using the Property window.

You must also define the DesignerActionList constructor that accepts the reference to the custom control; it's passed in the ActionLists property when the DesignerActionList is created. In the ActionLists property, the DesignerActionList is created, then passed a reference to the control being designed. So, the DesignerActionList constructor must accept that reference. You should also set a class-level variable to the reference so that other routines in the DesignerActionList will have access to the control being designed.