The WebPart Manager

The WebPartManager object is the operation controller for all WebParts on a page, and any page that has WebParts must have a WebPartManager. You place a single instance on the page, and the manager will maintain a list of WebParts and zones, manage the page state and personalization, and manage the communication between WebParts. At it's simplest you just have to add the control to the page:

<asp:WebPartManager  runat="server" />

The WebPartManager displays no UI, and you don't need to set any properties; it manages the WebParts behind the scenes for you. All of the content shown in Figure 13.1 is managed by user controls or server controls (either standard server controls or custom ones), and placed within "zones" on the page. Other content can be placed on the page, but within zones you must have user controls or server controls (in fact, other content such as text is allowed, but ignored).

The one place where you need code is in controlling the current state of the page. The default state is just to browse a page, where you see the content as is, but to allow customization there are other states:

• Design, where you can move WebParts between zones, and minimize or even hide WebParts.

• Edit, where you can modify characteristics of the WebParts, such as borders, titles, and so on.

• Connect, where you can connect WebParts together, allowing information from one to flow to another.

• Catalog, where you can see hidden WebParts, or WebParts that are available but that aren't displayed on the page.

You change the current state of the page by setting the DisplayMode property of the WebPartManager to a set value, and the easiest way to do this is with a list, as shown in Listing 13.1.

Listing 13.1. A WebPart Page Customization Menu

<asp:DropDownList  runat="server"   AutoPostBack="true" OnSelectedIndexChanged="MenuChanged">   <asp:ListItem value="EditDisplayMode"     Text="Personalize the page" />   <asp:ListItem value="BrowseDisplayMode"     Text="Browse the page" Selected="true" />   <asp:ListItem value="CatalogDisplayMode"     Text="Show Catalog" />   <asp:ListItem Value="ConnectDisplayMode"     Text="Connect WebParts" />   <asp:ListItem Value="DesignDisplayMode"     Text="Design the page" /> </asp:DropDownList>

Within the postback event, you set the DisplayMode property, as seen in Listing 13.2.

Listing 13.2. Setting the DisplayMode of the Page

protected void MenuChanged(object sender, EventArgs e) {   switch (WebPartMenu.SelectedValue)   {   case "DesignDisplayMode":     WebPartManager1.DisplayMode = WebPartManager.DesignDisplayMode;     break;   case "EditDisplayMode":     WebPartManager1.DisplayMode = WebPartManager.EditDisplayMode;     break;   case "BrowseDisplayMode":     WebPartManager1.DisplayMode = WebPartManager.BrowseDisplayMode;     break;   case "CatalogDisplayMode":     WebPartManager1.DisplayMode = WebPartManager.CatalogDisplayMode;     break;   case "ConnectDisplayMode":     WebPartManager1.DisplayMode = WebPartManager.ConnectDisplayMode;     break;   } }

What is interesting about this is that the DisplayMode isn't an enumeration; instead the values you use are public static fields of the WebPartManager, of type WebPartDisplayMode. This allows the mode to set different properties depending upon its needs.

You may wish to add intelligence into a menuing system, so that not all options are shown all of the time, or perhaps only certain options are available to certain users. This is important, since personalization is only allowed for authenticated users, so you could easily combine the menu with a LoginView control, or even construct the menu in code, using more advanced features of the WebParts to indicate which modes are allowed. For example, consider Listing 13.3, which constructs a menu dynamically.

The GetCurrentWebPartManager static method is used to get a reference to the WebPartManager on the page. While you can access the WebPartManager directly, this method proves useful if using a custom server control or a User Control for the menu. The WebPartManager has a property called SupportedDisplayModes that contains a collection of modes currently supported, and this takes into account whether the user is authenticated (and if not, then only browse mode is supported). The Name property of each supported mode is then used to construct a ListItem for the menu.

Listing 13.3. Constructing a WebPart Menu Dynamically

_manager = WebPartManager.GetCurrentWebPartManager(Page); String browseModeName = WebPartManager.BrowseDisplayMode.Name; // Fill the dropdown with the names of supported display modes. foreach (WebPartDisplayMode mode in _manager.SupportedDisplayModes) {   String modeName = mode.Name;   // Make sure a mode is enabled before adding it.   if (mode.IsEnabled(_manager))   {    ListItem item = new ListItem(modeName + " Mode", modeName);    DisplayModeDropdown.Items.Add(item);   } }

Listing 13.4 shows how the WebPartDisplayMode property can be used to simplify the setting of the DisplayMode, removing the switch statement.

Listing 13.4. Changing the DisplayMode from the Dynamic Menu

protected void DisplayModeDropdown_SelectedIndexChanged(   object sender, EventArgs e) {   String selectedMode = DisplayModeDropdown.SelectedValue;   WebPartDisplayMode mode =     _manager.SupportedDisplayModes[selectedMode];   if (mode != null)     _manager.DisplayMode = mode; }

The approach shown in Listings 13.3 and 13.4 not only simplifies your code, but also abstracts the menu handling into a neat package.