ASP.NET 2.0 WebPartChrome

WEBINAR:On-Demand

In ASP.NET 2.0, a WebPartZoneBase zone defines a region on a Web Parts page that contains WebPart controls. This is the base class for all Web Parts zones that contain WebPart controls. A WebPartZoneBase zone uses a WebPartChrome object to render the WebPart controls that the zone contains. This article discusses the WebPartChrome class and develops a custom WebPartChrome chrome to show you how to develop your own custom WebPartChromes to customize the rendering of WebPart controls contained in a zone.

The best way to understand the WebPartChrome class and its extensible methods is to take a look under the hood of the RenderBody method of the WebPartZoneBase class. The following code listing contains the code for the RenderBody method. As the name implies, this method renders the body of the zone. As this code listing shows, this method iterates through the WebPart controls that the zone contains and calls the RenderWebPart method of the WebPartChrome object to render each enumerated WebPart control:

In other words, WebPartZoneBase delegates the responsibility of rendering its WebPart controls to WebPartChrome. This section first takes you under the hood to help you gain a solid understanding of the methods and properties of the WebPartChrome class. Listing 1 shows these methods and properties. The following sections discuss some of these methods and properties in detail.

RenderWebPart

Listing 2 contains the implementation of the main parts of the RenderWebPart method of the WebPartChrome class. The boldface portions of this code listing shows some of the extensible methods of WebPartChrome class that you can extend to implement your own custom WebPartChrome, as you'll see later in this article.

As mentioned, the main responsibility of the RenderWebPart method is to render the WebPart control that WebPartZoneBase passes into it. A WebPart control consists of the following two parts:

Chrome: The chrome of a WebPart control is a graphical frame on the control that consists of two parts:

Title bar: The title bar includes a title text, a title icon, and a verbs menu

Border: The border is the portion of the chrome that frames the WebPart control

Content: The content of a WebPart control constitutes its body, that is, the part that the chrome frames

The Web Parts Framework uses the PartChromeType enumeration to specify the type of chrome that the RenderWebPart method must render for the specified WebPart control. The following are the possible values of this enumeration:

PartChromeType.Default: The WebPart control inherits the chrome type from the zone that contains the control. The WebZone base class exposes a property of type PartChromeType named PartChromeType that specifies the chrome type for all the WebPart controls that the zone contains.

PartChromeType.BorderOnly: RenderWebPart will not render the title bar of the specified WebPart control. It will only render the border.

PartChromeType.TitleOnly: RenderWebPart will not render the border that frames the WebPart control. It will only render the title bar.

PartChromeType.TitleAndBorder: RenderWebPart will render both the title bar and border of the specified WebPart control.

PartChromeType.None: RenderWebPart will render neither the border nor the title bar of the specified WebPart control.

As Listing 2 shows, the RenderWebPart method renders a table that contains two rows where each row contains a single cell. As you'll see shortly, the method renders the title bar within the first row and content or body of the WebPart control within the second row.

Therefore, the first order of business for the RenderWebPart method is to render the table that contains the title bar and body of the specified WebPart control. To render this table, RenderWebPart must render the HTML attributes of the associated <table> HTML element. These HTML attributes mainly consists of the "id" and CSS style attributes. RenderWebPart calls the GetWebPartChromeClientID method of the WebPartChrome to return the client ID value of the specified WebPart control and assigns this value to the id attribute of the <table> HTML element that contains the chrome and body of the WebPart control:

What does this mean to you as a control developer? You can call the GetWebPartChromeClientID method to access the value of the id attribute of the containing or main <table> HTML element and use this value in your client-side code to take advantage of the DHTML capabilities of the requesting browser.

RenderWebPart also calls the CreateWebPartChromeStyle method of the WebPartChrome to return the Style object that contains the CSS style attributes of the <table> HTML element that contains the chrome and body of the specified WebPart control.

The default implementation of CreateWebPartChromeStyle builds a Style object based on the chrome type of the specified WebPart control. RenderWebPart calls the GetEffectiveChromeType method of its associated zone to return the chrome type of the WebPart control and passes the chrome type to the CreateWebPartChromeStyle method to return the Style object:

This means two things to you as a developer. First, you can override the CreateWebPartChromeStyle method in your custom WebPartChrome to customize the CSS style attributes of the containing <table> HTML element. Second, you can override the GetEffectiveChromeType method of the WebZone zone to customize the chrome type that is passed into the CreateWebPartChromeType.

Finally, RenderWebPart must render the <table> HTML element itself:

writer.RenderBeginTag(HtmlTextWriterTag.Table);

ASP.NET 2.0 WebPartChrome

WEBINAR:On-Demand

Rendering the Title Bar

So far, you've learned how the RenderWebPart method renders the <table> HTML element and its associated HTML attributes. As mentioned, this table contains two rows where each row contains a single cell. RenderWebPart renders the title bar within the first row and the body of the WebPart control within the second row. Listing 3 presents the code that renders the title bar.

Notice that the method calls the GetWebPartTitleClientID method of the WebPartChrome to return the client ID of the cell that contains the title text. This means you can call the GetWebPartTitleClientID method to access the client ID of this cell and use it in your client-side code to add support for the desired DHTML capabilities. You'll see an example of this later in this article.

To render the verbs menu, the RenderTitleBar method calls the GetWebPartVerbs method of the WebPartChrome to return the verbs for the specified WebPart control. You can override this method in your custom WebPartChrome to filter the verbs that you don't want the current user to see.

Then it calls the FilterWebPartVerbs method of the WebPartChrome to filter the unwanted verbs. It may seem that FilterWebPartVerbs does exactly what GetWebPartVerbs does. Why have two different methods doing the same thing? The answer lies in the fact that there are two types of filtering. Sometimes you filter verbs based on some application-specific logic. For example, as you'll see later, you can filter verbs based on the role the current user is in. To accomplish this kind of filtering you should override the FilterWebPartVerbs method. There are times when you know in advance what verbs shouldn't be rendered. For example, you may decide your users shouldn't be able to close the WebPart controls in your application. To accomplish this kind of filtering you should override the GetWebPartVerbs method.

So far you've learned how the RenderWebPart method renders the title bar within the first row. Now you'll see how this method renders the body of the WebPart control within the second row. As shown in Listing 2, the method delegates the responsibility of rendering the body or content of the WebPart to the RenderPartContents method. Listing 4 presents the code for this method.

RenderPartContents first ensures that there're no connection error messages and then calls the RenderControl method of the WebPart control. Chapter 33 "WebPartManager, Web Parts Connections, and Data-Bound WebPart Controls" of the book Professional ASP.NET 2.0 Server Control and Component Development (Wrox, August 2006, ISBN: 0-471-79350-7) covers Web Parts connections in detail. You can override RenderPartContents in your custom WebPartChrome to take control over how the WebPart content is rendered.

PerformPreRender

As shown in Listing 1, the WebPartChrome class doesn't directly or indirectly derive from the Control base class, which means that WebPartChrome isn't a server control. Recall that every server control exposes methods such as OnPreRender, OnLoad, and others that are automatically called when the page enters the associated phases of its life cycle. Because WebPartChrome isn't a server control, none of its methods or properties is automatically called. WebPartChrome relies on its associated WebPartZoneBase, which is a server control, to call its methods when the page enters the associated phases of its life cycle.

The prerender phase plays a significant role when it comes to adding support for DHTML capabilities because the client-side scripts must be registered for rendering in this phase. You can't add these scripts to the RenderWebPart method because this method is called in the rendering phase, not the prerendering phase.

To address this problem, WebPartChrome exposes a method named PerformPreRender. However, because WebPartChrome isn't a server control, its PerformPreRender method will not be automatically called when the page enters its prerender phase. That's why the OnPreRender method of the associated WebPartZoneBase calls the PerformPreRender method of the WebPartChrome as shown in Listing 5.

Besides the methods discussed so far, the WebPartChrome also exposes two properties named Zone and WebPartManager, which respectively refer to the WebPartZoneBase and WebPartManager associated with the WebPartChrome object.

The next section builds on what you've learned about WebPartChrome to show you how to develop your own custom WebPartChrome to take control over the rendering of the WebPart controls that the associated zone contains.

ASP.NET 2.0 WebPartChrome

WEBINAR:On-Demand

Developing a Custom WebPartChrome

This section develops a custom WebPartChrome named CustomWebPartChrome that derives from the WebPartChrome base class and extends its functionality to add support for the following features:

Automatic rendering of a logo in the title bar of every WebPart control that the associated zone contains

Using the DHTML feature known as transition to provide an animated effect when the user moves the mouse pointer over the logo

CustomWebPartChrome exposes two new properties named MouseOverImageUrl and MouseOutImageUrl that the page developer must set to the URLs of the images that the CustomWebPartChrome control will render when the user moves the mouse pointer over and out of the control, respectively. In other words, CustomWebPartChrome switches from one image to another when the user moves the mouse pointer over or out of the control.

The revealTrans function is a standard IE function that provides an animated effect when CustomWebPartChrome switches from one image to another. This function takes two arguments. The first argument specifies the duration of the transition or animation. The second argument determines the type of transition or animation.

CustomWebPartChrome exposes an enumeration property of type Transition named Transition. The following code listing shows the possible values of this property. Each value introduces a different animation flavor.

Interested readers are referred to the MSDN Web site for the complete information about the possible values of the transition parameter of the revealTrans method.

As Listing 6 shows, CustomWebPartChrome overrides the PerformPreRender method of its base class to render the client script that supports the DHTML transition feature. This method first iterates through the WebPart controls that the associated zone contains to dynamically generate the client script that supports the transition effect. As Listing 3 shows, the RenderWebPart method of the WebPartChrome assigns the return value of the GetWebPartTitleClientID method to the id HTML attribute of the table cell that contains the title text for the WebPart control. PerformPreRender passes the return value of this method to the getElementById method of the document object to return a reference to the table cell that contains the title text:

It then generates the script that returns a reference to the first child element of the table cell:

js += "titleBarFirstChild = titleBar.childNodes[0];\n";

Next, the method generates the script that creates an <img> HTML element and inserts this element as the first child element of the table cell. This ensures the logo will always appear on the top-left corner of the WebPart control:

Next, the method generates the script that stores the values of the MouseOutImageUrl and MouseOverImageUrl properties. As you'll see later, the MouseOverCallback and MouseOutCallback JavaScript function uses these values to switch between the two versions of the logo:

Then it generates the script that assigns the revealTrans filter to the filter property of the style object and uses the values of the Duration and Transition properties to set the duration and transition parameters of the filter:

Once the script is created, PerformPreRender calls the RegisterStartupScript method to register the script with the containing page. As discussed in Chapter 26 "Developing Ajax-Enabled Controls and Components: Client-Side Functionality" of the book Professional ASP.NET 2.0 Server Control and Component Development (Wrox, August 2006, ISBN: 0-471-79350-7), the containing page renders all the registered scripts when it enters its rendering phase.

The img JavaScript object references the <img> HTML element. This object exposes a collection property named filters that contains all the filters defined in the style attribute of the <img> element. In this case, this collection contains a single item, the transition filter. The filter JavaScript object exposes three important methods, apply, play, and stop.

As Listing 7 shows, the MouseOverCallback calls the apply method of the filter object to take a snapshot of the current image that the <img> element displays:

img.filters[0].apply();

It switches to the new image:

img.src = mouseOverImageUrl;

It then calls the play method of the filter object to start the animation:

img.filters[0].play();

As Listing 7 shows, the MouseOutCallback method calls the stop method of the filter object to stop the animation:

img.filters[0].stop();

It then switches to the new image

img.src = mouseOutImageUrl;

When you develop a custom WebPartChrome, you must also develop a custom WebPartZoneBase that uses your custom WebPartChrome to render its WebPart controls. However, before getting into the implementation of the custom WebPartZoneBase that uses CustomWebPartChrome, you'll need to override one more method of the WebPartChrome base class, RenderWebPart, to ensure that the CustomWebPartChrome is used by your custom WebPartZoneBase.

Listing 8 illustrates the implementation of the RenderWebPart method of the CustomWebPartChrome. As this listing shows, the method ensures the associated zone is of type CustomWebPartZone before it calls the RenderWebPart method of its base class to render the specified WebPart control.

CustomWebPartZone

As discussed, RenderBody delegates the responsibility of rendering all the WebPart controls that it contains to a single instance of WebPartChrome. WebPartZoneBase exposes a protected virtual method named CreateWebPartChrome whose default implementation returns an instance of the WebPartChrome class as shown in the following code listing:

CustomWebPartZone is a custom zone that uses CustomWebPartChrome to render its WebPart controls. The CustomWebPartZone custom zone exposes the same four properties that CustomWebPartChrome does: MouseOverImageUrl, MouseOutImageUrl, Duration, and Transition. This custom zone overrides the CreateWebPartChrome method of its base class to instantiate and to return an instance of the CustomWebPartChrome as shown in Listing 9.

CreateWebPartChrome creates a CustomWebPartChrome and assigns the values of the MouseOverImageUrl, MouseOutImageUrl, Duration, and Transition properties of the CustomWebPartZone control to the respective properties of the newly created CustomWebPartChrome object.

Using the CustomWebPartChrome Control

Listing 10 contains a Web page that uses the CustomWebPartZone control and CustomWebPartChrome chrome. Notice that the page sets the values of the MouseOutImageUrl, MouseOverImageUrl, Duration, and Transition properties of the CustomWebPartZone control. Figure 1 shows what the users see on their browsers. Notice that every control added to the CustomWebPartZone automatically contains the logo image in its title bar. When the user moves the mouse pointer over the logo, the WebPart control provides an animated effect.

Advertiser Disclosure:
Some of the products that appear on this site are from companies from which QuinStreet receives compensation. This compensation may impact how and where products appear on this site including, for example, the order in which they appear. QuinStreet does not include all companies or all types of products available in the marketplace.

Thanks for your registration, follow us on our social networks to keep up-to-date