Practical ASP.NET

Integrating User Controls with WebParts

In his ongoing campaign to convince ASP.NET developers that User Controls are a simple way to start implementing customizable pages, Peter shows how to improve the integration between User Controls and ASP.NET's WebPart framework.

• By Peter Vogel
• 06/18/2009

In an earlier column -- "Create a Reporting Dashboard with WebPartZones (But Without WebParts)" -- I described how you could create a reporting dashboard that allows users to select reports from a catalog on the page. To do this, I took advantage of the WebPart framework in ASP.NET but, rather than go through the agony of creating an actual WebPart, I used something that ASP.NET developers do understand: User Controls.

But my solution wasn't complete. While a real WebPart displays descriptive information (a title and a subtitle, for instance), a User Control does not. In addition, I didn't address allowing the user to set values on the User Control to personalize the WebPart.

In my customizable reporting dashboard, these features would be very useful. In the catalog of available User Controls, having each user control display a title provides the easiest way to tell the user what each report does. In addition, a true WebPart would allow the user to provide input values to customize the report. For instance, while the default report might display sales for all regions, a user should be able to customize the report to display just the region the user is interested in.

Both of these options are available even when using user controls.

Implementing Descriptions
My first step in using a User Control as a WebPart is to have it implement the IWebPart interface, as in this example:

Partial Class AnnualSalesReportUserControl
    Inherits System.Web.UI.UserControl
    Implements IWebPart

The result of this change is the addition of six properties to my User Control: Title, Subtitle, Description, TitleUrl, CatalogIconImageUrl and TitleIconImageUrl. The first four are the easiest properties to implement as they only require a string value. In many ways, the Title and Subtitle are the most important because they are automatically displayed on the WebForm either on the WebPart itself or when the control is displayed in a catalog.

The user can change the Title property as part of customizing the WebPart but the Subtitle property is fixed. Because of that difference, you should use the Subtitle property to describe the WebPart independently of any personalization that you'll let the user implement (for instance, I'd give my WebPart report the name "Sales Report"). The Title property should default to a value that reflects the default settings for the report. For a sales report that, by default, shows sales for all regions but allows the user to select a specific reason, a good Title would be "Sales Report." Implementing those settings would require code like this:

Private _title As String = "All Regions"

Public ReadOnly Property Subtitle() As String _
    Implements System.Web.UI.WebControls.WebParts.IWebPart.Subtitle
        Get
            Return "Sales Report"
        End Get
End Property

Public Property Title() As String _
   Implements System.Web.UI.WebControls.WebParts.IWebPart.Title
        Get
            Return _title
        End Get
        Set(ByVal value As String)
            _title = value
        End Set
 End Property

Implementing Personalization
The next step is to give the user the ability to customize how the User Control works. For a report, this might mean allowing the user to set the parameters that are passed to the report's selection criteria. The default parameter for the report could be an asterisk (to retrieve all regions) but, through a property, the user could be allowed to supply a specific region.

All that's necessary is to create the property that accepts the region and then add the Personalizable and WebBrowsable attributes to it, as in this example:

Private _region As String = "*"

<Personalizable(True) > _
    <WebBrowsable()> _
    Public Property Region() As String
        Get
            Return _region
        End Get
        Set(ByVal value As String)
            _region = value
	RegenerateReport(_region)
        End Set
    End Property

Adding a personalizable property isn't enough -- you also need to add the controls to the page that let the user set that property. Two controls are required: First you need to add to your page an EditorZone from the WebParts tab of your Toolbox. Then you need to drag a PropertyGridEditorPart into that zone (also from the WebParts tab).

Finally, you need to let the user put the control into Edit mode. To do that, you first need to add a button to the page that adds an Edit choice to the menu control that the WebPart framework adds to your User control. The code for that button looks like this:

Me.WebPartManager1.DisplayMode = WebPartManager.EditDisplayMode

Now, when the user wants to customize the WebPart/User Control, he or she clicks on the button and selects Edit from the menu that appears on the User control. At that point, the PropertyGridEditorPart will appear on the page, populated with a control for every property you've marked as customizable. The user can then enter the values to control the WebPart. ASP.NET's WebPart framework will then save the settings for the next time the user views the page.