Practical ASP.NET

Customize Sites With Web Parts

Users know their needs and preferences better than anyone. Give them the power to create the site they want to use with ASP.NET's Web Parts.

• By Peter Vogel
• 06/01/2005

Technology Toolbox: VB.NET, C#, ASP.NET, ASP.NET 2.0

Your users probably understand their needs better than you do. So why not give them the power to customize your application's interface according to their needs? ASP.NET 2.0 includes a new feature that lets you do precisely that. Build your WebForm page using Web Parts, and your users can customize your Web application's user interface.

Imagine a user is visiting a Web site you built that sells books. As your user looks at the page, she realizes that she doesn't like your design for the book-search facility. Rather than complain to you, she clicks on a button labeled "Customize," clicks on the block displaying the detailed book information, and drags the block to the left-hand side of the page. She also notices that, after clicking on the Customize button, she has a choice of a "more detailed" version of book information. She closes the current book information block, then selects the detailed version.

Let's also assume this user is interested only in fantasy books and wants to search only for newly released books. She can further customize the page by setting the textbox that searches on genre to "Fantasy," and setting the drop-down list that controls the sort order to "Most recent first." She'll return to the same configuration every time she visits your site. It isn't your user interface anymore, but something better: the user interface your user wants.

Turning on support for this kind of customization in ASP.NET 2.0 is as simple as dragging a single control onto your page: WebPartManager. You can use this control to designate zones on your page where users can add, change, or remove controls. Users can even connect controls to each other, so they pass data between themselves. And all it takes to give your users this functionality is a few lines of code.

The Visual Studio 2005 Toolbox features a tab called WebParts, which includes a dozen Web Part infrastructure controls that make up the Web Part framework. In addition to WebPartManager, these framework controls include Zones, which define the sections of a page users can customize; Editors, which let users set properties on a control; Catalogs, which list controls that you can add to the page; and ConnectionsZone, which allows two Web Parts to send data to each other.

Adding WebPartManager to a page not only enables support for customization, but also activates the necessary personalization support for your ASP.NET application. This support includes adding a SQL Server database to your Web site to hold your application's personalization information. Visual Studio places the MDF file in the Data subdirectory in your Web site's home directory (you can switch to using other databases to hold personalization information). You can set up zones on the page where you will allow customization after you place WebPartManager on your page.

Define the Customization Area
Drag WebPartZone to an area of your page to define where the user can perform customization. Any WebForm controls that you drag into the lower part of the zone will be available for customization by your users (see Figure 1).

The ASP.NET Button and TextBox controls are standard ASP.NET controls rather than Web Parts, so Visual Studio wraps these controls inside of a GenericWebPart object at run time. This wrapper is what gives a standard ASP.NET control Web Part customization abilities. Some of these characteristics show up in the way that Visual Studio displays the control in its Design view. Specifically, Visual Studio displays the controls enclosed in a box, with a title bar that includes a small down arrow. Clicking on the arrow at run time displays the control's Verb menu with two customization choices: Minimize and Close (the individual actions on the menu are referred to as verbs). If a user clicks on the Minimize button, Visual Studio reduces the control to only its title bar (the Verb menu is still available and now includes a Restore command that brings the control back). Clicking on the Close button stops the control (including the title bar) from being displayed on the page.

You can access individual controls inside a zone through code by using a zone's WebParts collection. A WebPart object is returned when you access a control through the WebParts collection. You can use this object to set properties relevant to a Web Part. This VB.NET code sets the Title property of the control inside the Web Part to "Genre":

Dim wp As WebPart

wp = Me.znSearch.WebParts("TextBox1")
wp.Title = "Genre"

The same code in C# looks like this:

WebPart wp;

wp = this.znSearch.WebParts["TextBox1"];
wp.Title = "Genre";

Create a Customizable Page
At this point, you're ready to create a simple customizable page. Begin by creating a WebForm page in an ASP.NET 2.0 project, then drag WebPartManager and WebPartZone controls onto the page. Next, drag a WebForm textbox into the WebPartZone. Browse the page in Internet Explorer to customize the page. Simply select the Minimize action from the textbox's menu (click on the small down arrow to display the menu). This makes the textbox disappear and replaces Minimize in the Verb menu with Restore. You have now customized your page. Shut down your browser and fire it up again to view the page. Your textbox is still minimized; ASP.NET 2.0 has tracked your customization.

In its default mode, a control's Verb menu contains only the Minimize and Close verbs. You must put WebPartManager on the page into one of five standard modes to let users take advantage of more advanced customizations: BrowseDisplayMode, EditDisplayMode, CatalogDisplayMode, ConnectDisplayMode, and DesignDisplayMode.

BrowseDisplayMode is the default mode for a page and displays the contents of the page. Users can perform only the Close and Minimize actions in this mode. EditDisplayMode displays any special controls for changing properties on Web Parts, and CatalogDisplayMode lets users add controls to the page. ConnectDisplayMode lets users join two controls together so they can exchange data, while DesignDisplayMode enables users to drag controls between zones (or rearrange controls inside a zone).

Let's assume you want to create a customizable book-selling site, as described in the opening of this article. Place this code behind the Customize button to change a page's Edit mode:

Me.WebPartManager1.DisplayMode = _
   WebPartManager.EditDisplayMode

Performing some customizations is as simple as choosing the right mode. For example, putting the page into Design mode enables users to drag controls between zones. However, some customization modes require specific framework controls to be present. It won't be possible to put the page into some modes if it doesn't contain the proper controls.

You must place the framework controls that support customizations inside zones as well. Note that zones and controls are matched sets. You enable users to add new controls to a page by putting a CatalogZone control on the page and adding a catalog control to the CatalogZone. A catalog control displays a list of available controls you can add to the page. For instance, if users select the Close verb on a Web Part while the Web Part is no longer visible on the page, the control is still part of the page. PageCatalogPart lists all the closed controls on the page and lets users add the control back to the page (see Figure 2).

At this point, your users can check the control(s) that they want to add, select a WebPartZone from the dropdown list at the bottom of catalog, and click on the Add button to add the selected control(s) to the specified WebPartZone.

Build Dedicated Web Parts
You can create your own Web Parts that take more complete advantage of the Web Parts framework than a standard ASP.NET control can. Creating a Web Part is similar to creating a custom control. If you're familiar with that process, you know most of what you need to do to create a Web Part. The major difference between Web Parts and custom controls is that a Web Part inherits from the WebParts.WebPart object, whereas a custom control inherits from the ASP.NET WebControl.

Web Parts support all the features of a custom control—and a few additional features. The most important feature of a Web Part is that it lets you add new verbs to the Web Part's Verb menu. You do this by overriding the default Verbs property provided in the WebPart object. This is a read-only property, so you need to provide only a Get part for the property.

ASP.NET reads the Verbs property when necessary and expects the property to return a WebPartVerbCollection. A WebPartVerbCollection is created from an array of WebPartVerb objects. Each item in the WebPartVerb array represents an entry in the Verb menu for the Web Part.

The first step in customizing the Verb menu is to override the Verbs property and open the Get section:

Public Overrides ReadOnly Property _
   Verbs() As _
   WebControls.WebParts.WebPartVerbCollection

   Get

Next, begin creating the WebPartVerb objects; you need one WebPartVerb for each item you want to add to the Web Part's Verb menu. You want some routine to execute when a user selects your verb from the Web Part's Verb menu. The easiest way to assign a routine to a verb is to pass the address of a routine to WebPartVerb when you create it:

Dim vrbEnglish As New _
   WebControls.WebParts.WebPartVerb( _
   AddressOf Me.SetEnglish)
Dim vrbFrench As New _
   WebControls.WebParts.WebPartVerb( _
   AddressOf Me.SetFrench)

You also want to set WebPartVerb's Text property, which controls what is displayed for each verb in the Web Part's Verb menu. For example, assume you want to set the two verbs just created to say "English" and "French":

vrbEnglish.Text = "English"
vrbFrench.Text = "French"

You can add the verbs to an array of WebPartVerbs once you configure them. This code defines an array with two positions and puts the verbs in the first and second positions:

Dim vrbsLanguage(1) As _
   WebControls.WebParts.WebPartVerb
vrbsLanguage(0) = vrbFrench
vrbsLanguage(1) = vrbEnglish

Finally, create the WebPartVerbCollection object from the array and return it from the Get section of the property:

Dim vrbs As _
   WebControls.WebParts.WebPartVerbCollection
vrbs = New _
   WebControls.WebParts.WebPartVerbCollection( _
   vrbsLanguage)

Return vrbs

   End Get

End Property

A routine associated with a verb follows the typical pattern for an event routine by having two parameters. The first parameter is declared as an Object. This parameter is passed a reference to the object that fired the event (in this case, WebPartVerb). The second parameter is a WebPartEventArgs object. The WebPart property of this object provides a reference to the WebPart object that holds the verb.

The code checks to see which Web Part called it before determining what action to take. This code could be associated with a verb:

Private Sub SetLanguage(ByVal sender _
   As Object, ByVal e As _
   System.Web.UI.WebControls. _
   WebParts.WebPartEventArgs)
   Select Case e.WebPart.ID 
      Case "wpBookSearchFull" 
         ...processing...
      Case "wpBookSearchSummary" 
         ...processing...
   End Select

End Sub

At this point, you know everything necessary to create WebForms that your users can customize to meet their needs. If you're familiar with creating custom controls, you're also ready to extend your custom controls to manage your Web Part's Verb menu. Possible next steps to try out might include using the properties of a Web Part to configure its appearance, converting an existing custom control to a Web Part by having it inherit from the WebParts object, or creating two Web Parts that share information by defining a common interface for them.