An important feature of the WebPart class is that it implements interfaces that allow it to describe its properties and behaviors to other members of the portal framework as described in table 2.1.

Table 2.1 The WebPart class implements three interfaces

Because the WebPart class implements these three interfaces, each of the different members of the portal framework can interact with all web parts. For example, when a page is first displayed, each web part is handed to the web part manager. The manager then uses these interfaces to determine what capabilities a web part has. Therefore, when the manager was handed our weather web part, it didn't have to know anything about what properties we had given it, but by virtue of the fact that the weather web part is a web part, the web part manager knew that the control would have certain distinguishing features such as a Title and Verbs, etc.

In the sections that follow we'll spend time going over each of those three interfaces described in table 2.1 to gain a better understanding of how they are used by the portal framework, and also how we can use them to extend and customize the behavior of web parts that we create.

2.4.1 IWebPart

The IWebPart interface defines the properties that are common to all web parts. The following is a list of each of the properties that are exposed by the IWebPart interface.

• CatalogIconImageUrl—the URL of an image that is displayed for a web part when that part is displayed in a catalog of web parts.
• Description—Descriptive text about a web part that is displayed for a web part when that part is displayed in a catalog of web parts. This property is also used to display tooltip information about a web part.
• Subtitle—Combines with the Title property to form the complete title for a web part control.
• Title—the title of a web part control.
• TitleIconImageUrl—the URL of an image that is displayed in the web part's title bar.
• TitleUrl—a URL to a link containing additional information that is related to the web part.

Implementing the common web part properties

When you create a custom web part by inheriting directly from the WebPart class you will have access to each of the properties listed above in your code because the IWebPart interface is already implemented for you. However, when using user controls as web parts you will need to implement the interface for yourself to be able to code against these properties from within your control. The reason for this is that the user control does not inherit from the WebPart class, and therefore it does not have these properties associated with it. The code shown in listing 2.7 creates a user control that implements the IWebPart interface and provides a custom implementation for each property of that interface.

Listing 2.7 Implementing the IWebPart interface from within a user control

public partial class SampleWebPart : UserControl, IWebPart {

   string CatalogIconImageUrl {
      get { return "~/images/CatalogImage.png"; }
      set { return; }
   }

   string Description {
      get { return "This is the description."; }
      set { return; }
   }

   string Subtitle {
      get { return "Sub-Title."; }
   }

   string Title {
      get { return "Web Part Title"; }
      set { return; }
   }

   string TitleIconImageUrl {
      get { return "~/images/Globe.gif"; }
      set { return; }
   }

   string TitleUrl {
      get { return "~/Default.aspx"; }
      set { return; }
   }
}

Figure 2.8 shows how those properties would appear when rendered in a browser. Notice that the text in the title bar is represented as a clickable link that would take the user back to the Default.aspx page. This is due to the fact that we specified a value for the TitleUrl property. Notice as well, that when the mouse is placed over the title text or the image that is displayed alongside it in the title bar, the description is displayed as a tooltip. Each of the elements you see in the figure 2.8 web part is a direct result of the values we assigned to the interface properties in listing 2.7.

Figure 2.8 IWebPart members displayed on a web part.

We've just seen the IWebPart interface in action. The IWebPart interface is the first of the three interfaces that are implemented by web parts. Throughout this section we've learned about the members of this interface and how they affect the look and feel of a web part at runtime. Now we'll look at the next interface that is implemented by all web parts—the IWebActionable interface—and see how it is used to add verbs to custom web part controls.

2.4.2 IWebActionable

Earlier in this chapter we saw that each web part has a menu, containing menu items. These menu items are referred as "verbs," and they allow users to perform operations such as closing or minimizing the web part. Every web part has a default set of verbs assigned to it by the zone in which it appears. These verbs are known as zone verbs and are common to all web parts—they are Close, Minimize, Restore, Delete, Edit, and Export. Which zone verbs are visible at any given time depends on the current display mode of the web page, the current user, and also the current state of the web part itself. For example, it would not make sense to display the Close verb when the web part is already closed or Restore when it is open.

Displaying custom verbs

In addition to the standard set of zone verbs that each web part is assigned, additional verbs can also be added to the web part's menu. These additional verbs would generally be for the purpose of allowing users to perform custom actions associated with the web part. This can be achieved by using the WebPartVerb class to create a verb, and adding that verb to the existing collection of verbs for the part. For example, we could add a verb named Copy Text to a web part that would enable users to copy text from within a web part to another control elsewhere on the page. Verbs are the perfect choice for adding these kinds of discrete operations to web parts because they are conveniently hidden away from the main user interface section of the web part, yet readily accessible to the user.

The IWebActionable interface is used to define a property named Verbs that appears on every web part. The Verbs property is responsible for returning all the verbs that belong to a web part, and it is here that we have the opportunity to add custom verbs to the existing collection. Let's demonstrate this by extending the SampleWebPart we just created, so that it implements the IWebActionable interface. This will allow us to add in our own custom verbs for that web part. The following snippet of code shows how to implement the interface on our SampleWebPart class.

public partial class SampleWebPart : UserControl, IWebPart,
                                     IWebActionable
{

   protected WebPartVerbCollection IWebActionable.Verbs {
      get { }

   }
}

NOTE If you are using custom controls for your web parts you will not have to directly implement these interfaces because they are already implemented on the base WebPart class. In that case, your code will differ because you will be overriding an existing implementation of the IWebPart and IWebActionable members, as opposed to implementing one from scratch.

Next we will add code to the Verbs property to create two custom verbs for our class. The first verb will allow the user to click on it to display the current time in a label. A second verb will allow the user to clear the text of the label. The verbs that we add are also associated with corresponding server-side event handlers named DisplayTime and ClearTime. These handlers are the methods that will be called when a user clicks on the verb. The full code for our custom Verbs implementation can be seen in listing 2.8, while figure 2.9 shows the two verbs being displayed in a browser at runtime.

Listing 2.8 The Verbs property is used to associate custom verbs with a web part.