CatalogZone Class

Within the Web Parts control set, a zone is a region on a Web page that contains Web Parts controls. A Web Parts zone is created by a zone control, which is a type of CompositeControl designed to contain other controls. The primary functions of a zone are to lay out the controls it contains, and to provide a common user interface (UI) for those controls. For general information about zones and how they are used in Web Parts applications, see the base WebZone class, and Web Parts Control Set Overview.

A key feature of Web Parts controls is that they allow end users to modify (or personalize) Web pages according to their preferences, and save their personalized settings for future browser sessions. One aspect of modifying Web Parts pages includes the ability to add WebPart controls or other server controls to a Web Parts page. The CatalogZone control provides a list or catalog of controls that users can add to a page.

The CatalogZone control is one of the fundamental controls in the Web Parts control set. It derives from the CatalogZoneBase class, and most of its behavior is inherited from that class. The CatalogZone class essentially adds to the base class a zone template, which is an implementation of the ITemplate interface. The zone template enables developers to declaratively add CatalogPart controls to a zone in the page persistence format.

Important
A CatalogZone zone can contain only CatalogPart controls, and conversely, CatalogPart controls can reside only in zones that derive from the CatalogZoneBase class, such as CatalogZone.

A CatalogZone control becomes visible only when a user switches a Web page to catalog display mode (CatalogDisplayMode). A catalog can contain several types of CatalogPart controls. Each CatalogPart control is a type of container that contains the server controls users can add to the page. The CatalogPart controls differ according to where the server controls they contain are coming from. The following table summarizes the CatalogPart controls provided with the Web Parts control set and, for each control, what kind of server controls it contains.

Because the CatalogZone class adds only a zone template to the behavior of its base class, it has few members. The CatalogZone constructor is a default constructor; with it, you can initialize a new instance of the CatalogZone class. The ZoneTemplate property gets or sets a reference to the ITemplate object that contains the controls for the zone. The CreateCatalogParts method is critical. It overrides the base method to create the collection of all CatalogPart controls contained within the zone template.

Note
The buttons in the CatalogZone UI require client-side scripting in order to work correctly. If scripting is disabled in the browser, the user will not be able to perform actions through the CatalogZone UI.

Accessibility

You can create custom CatalogZone classes if you want more control over the rendering and behavior of the catalog UI. If you do not need to provide users of your control with the ability to add CatalogPart controls declaratively, then you can inherit directly from the CatalogZoneBase class. If you do want to enable controls to be added declaratively, the simples approach is to inherit from the CatalogZone class, because it provides the essential zone template.

If you inherit from the CatalogZone class, you can override the CreateCatalogParts method and use the method to add custom CatalogPart controls to a CatalogPartCollection, if you want greater programmatic control over adding custom CatalogPart controls to your zone.

The following code example demonstrates declarative and programmatic use of the CatalogZone control. The code example has four parts:

• A user control that enables you to change display modes on the Web page.

• A file with the source code for a custom CatalogZone control, and a custom WebPart control that is imported by the catalog and added to the Web page.

• A Web page that declares the user control, and the custom CatalogZone control.

• An explanation of how to run the example.

The first part of this code example is the user control that enables users to change display modes on a Web page. For details about display modes and a description of the source code in this control, see Walkthrough: Changing Display Modes on a Web Parts Page.

<%@ control language="C#" classname="DisplayModeMenuCS"%>
<script runat="server">

 // Use a field to reference the current WebPartManager.
  WebPartManager _manager;

  void Page_Init(object sender, EventArgs e)
  {
    Page.InitComplete += new EventHandler(InitComplete);
  }  

  void InitComplete(object sender, System.EventArgs e)
  {
    _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, modeName);
        DisplayModeDropdown.Items.Add(item);
      }
    }

    // If shared scope is allowed for this user, display the scope-switching
    // UI and select the appropriate radio button for the current user scope.
    if (_manager.Personalization.CanEnterSharedScope)
    {
      Panel2.Visible = true;
      if (_manager.Personalization.Scope == PersonalizationScope.User)
        RadioButton1.Checked = true;
      else
        RadioButton2.Checked = true;
    }

  }

  // Change the page to the selected display mode.
  void DisplayModeDropdown_SelectedIndexChanged(object sender, EventArgs e)
  {
    String selectedMode = DisplayModeDropdown.SelectedValue;

    WebPartDisplayMode mode = _manager.SupportedDisplayModes[selectedMode];
    if (mode != null)
      _manager.DisplayMode = mode;
  }

  // Set the selected item equal to the current display mode.
  void Page_PreRender(object sender, EventArgs e)
  {
    ListItemCollection items = DisplayModeDropdown.Items;
    int selectedIndex = 
      items.IndexOf(items.FindByText(_manager.DisplayMode.Name));
    DisplayModeDropdown.SelectedIndex = selectedIndex;
  }

  // Reset all of a user's personalization data for the page.
  protected void LinkButton1_Click(object sender, EventArgs e)
  {
    _manager.Personalization.ResetPersonalizationState();
  }

  // If not in User personalization scope, toggle into it.
  protected void RadioButton1_CheckedChanged(object sender, EventArgs e)
  {
    if (_manager.Personalization.Scope == PersonalizationScope.Shared)
      _manager.Personalization.ToggleScope();
  }

  // If not in Shared scope, and if user is allowed, toggle the scope.
  protected void RadioButton2_CheckedChanged(object sender, EventArgs e)
  {
    if (_manager.Personalization.CanEnterSharedScope && 
        _manager.Personalization.Scope == PersonalizationScope.User)
      _manager.Personalization.ToggleScope();
  }
</script>
<div>
  <asp:Panel ID="Panel1" runat="server" 
    Borderwidth="1" 
    Width="230" 
    BackColor="lightgray"
    Font-Names="Verdana, Arial, Sans Serif" >
    <asp:Label ID="Label1" runat="server" 
      Text="&nbsp;Display Mode" 
      Font-Bold="true"
      Font-Size="8"
      Width="120" 
      AssociatedControlID="DisplayModeDropdown"/>
    <asp:DropDownList ID="DisplayModeDropdown" runat="server"  
      AutoPostBack="true" 
      Width="120"
      OnSelectedIndexChanged="DisplayModeDropdown_SelectedIndexChanged" />
    <asp:LinkButton ID="LinkButton1" runat="server"
      Text="Reset User State" 
      ToolTip="Reset the current user's personalization data for the page."
      Font-Size="8" 
      OnClick="LinkButton1_Click" />
    <asp:Panel ID="Panel2" runat="server" 
      GroupingText="Personalization Scope"
      Font-Bold="true"
      Font-Size="8" 
      Visible="false" >
      <asp:RadioButton ID="RadioButton1" runat="server" 
        Text="User" 
        AutoPostBack="true"
        GroupName="Scope" OnCheckedChanged="RadioButton1_CheckedChanged" />
      <asp:RadioButton ID="RadioButton2" runat="server" 
        Text="Shared" 
        AutoPostBack="true"
        GroupName="Scope" 
        OnCheckedChanged="RadioButton2_CheckedChanged" />
    </asp:Panel>
  </asp:Panel>
</div>

The second part of the code example contains the code for the custom CatalogZone and WebPart controls. The code for the CatalogZone control demonstrates how to inherit from the CatalogZone class and customize its properties by setting some default property values in the constructor. The source code also demonstrates how to create a custom WebPart class named TextDisplayWebPart. This is the control associated with the .WebPart description file that you will import as part of this code example. After you import the description file by using the ImportCatalogPart control on the Web page, you'll be able to add the TextDisplayWebPart control to the page, fully pre-configured as specified in the description file.

For the code example to run, you must compile this source code. You can compile it explicitly and put the resulting assembly in your Web site's Bin folder or the global assembly cache. Alternatively, you can put the source code in your site's App_Code folder, where it will be dynamically compiled at run time. This code example uses dynamic compilation, so if you want to run the example this way, name the source code file and add it to an App_Code subfolder of your Web application's root directory. For a walkthrough that demonstrates both methods of compiling, see Walkthrough: Developing and Using a Custom Web Server Control.

using System;
using System.Collections;
using System.ComponentModel;
using System.Drawing;
using System.Security.Permissions;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;

namespace Samples.AspNet.CS.Controls
{
  // Create a customized CatalogZone control by setting 
  // some properties in the constructor.
  [AspNetHostingPermission(SecurityAction.Demand,
    Level = AspNetHostingPermissionLevel.Minimal)]
  [AspNetHostingPermission(SecurityAction.InheritanceDemand,
    Level = AspNetHostingPermissionLevel.Minimal)]
  public class MyCatalogZone : CatalogZone
  {
    public MyCatalogZone()
    {
      this.HeaderText = "My Company Catalog";
      this.HeaderCloseVerb.Text = "Close Catalog";
      this.CloseVerb.Text = "Close Catalog";
    }
  }


  // Create a custom WebPart control to add to a WebPartZone.
  [AspNetHostingPermission(SecurityAction.Demand,
    Level = AspNetHostingPermissionLevel.Minimal)]
  [AspNetHostingPermission(SecurityAction.InheritanceDemand,
    Level = AspNetHostingPermissionLevel.Minimal)]
  public class TextDisplayWebPart : WebPart
  {
    private String _contentText = null;
    TextBox input;
    Label DisplayContent;
    Literal lineBreak;

    [Personalizable(), WebBrowsable]
    public String ContentText
    {
      get { return _contentText; }
      set { _contentText = value; }
    }

    protected override void CreateChildControls()
    {
      Controls.Clear();
      DisplayContent = new Label();
      DisplayContent.BackColor = Color.LightBlue;
      DisplayContent.Text = this.ContentText;
      this.Controls.Add(DisplayContent);

      lineBreak = new Literal();
      lineBreak.Text = @"<br />";
      Controls.Add(lineBreak);

      input = new TextBox();
      this.Controls.Add(input);
      Button update = new Button();
      update.Text = "Set Label Content";
      update.Click += new EventHandler(this.submit_Click);
      this.Controls.Add(update);

    }

    private void submit_Click(object sender, EventArgs e)
    {
      // Update the label string.
      if (input.Text != String.Empty)
      {
        _contentText = input.Text + @"<br />";
        input.Text = String.Empty;
        DisplayContent.Text = this.ContentText;
      }
    }
  }

}

The third part of the code example is the Web page that contains the controls. It contains a Register directive for the user control, and another for the source file with the custom controls. Note that in the second directive, it does not name the assembly, because the example does not use an assembly, it uses dynamic compilation with the source code placed in the App_Code subfolder. The Web page declares a WebPartZone control, and within its child <zonetemplate> element, it declares a BulletedList control. While this is a standard ASP.NET control, it will have full Web Parts functionality at run time, because the WebPartManager control wraps any server control placed in a WebPartZone with a GenericWebPart object, so that other server controls can participate in Web Parts applications. Also declared in this zone is the custom WebPart control named TextDisplayWebPart. Notice that this control has an attribute of ExportMode="All" declared on it. This enables you to export a .WebPart description file that contains the property values of the control, which can be imported by other users to add the pre-configured control to other Web pages.

Note

To enable users of a Web Parts application to export a description file for WebPart controls, you must also enable the export feature in the Web application by adding an enableExport="true" attribute to the <webParts> element (which is a child of the <system.web> element) in the Web.config file. Export is disabled by default, so if you not yet enabled export for your application, edit the Web.config file and do it now.

The Web page also declares the custom CatalogZone control and, within it, a <zonetemplate> element that contains an ImportCatalogPart control. The user will use this control at run time to import the .WebPart description file for the custom WebPart control.

<%@ Page Language="C#" %>
<%@ register TagPrefix="uc1" 
  TagName="DisplayModeMenuCS" 
  Src="DisplayModeMenuCS.ascx" %>
<%@ Register TagPrefix="aspSample"
  Namespace="Samples.AspNet.CS.Controls" %> 

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Untitled Page</title>
</head>
<body>
  <form id="form1" runat="server">
    <asp:WebPartManager ID="WebPartManager1" runat="server" />
    <uc1:DisplayModeMenuCS ID="DisplayModeMenu1" runat="server" />
    <asp:WebPartZone ID="WebPartZone1" runat="server">
      <ZoneTemplate>
        <asp:BulletedList 
          ID="BulletedList1" 
          Runat="server"
          DisplayMode="HyperLink" 
          Title="Favorite Links" >
          <asp:ListItem Value="http://msdn.microsoft.com">
            MSDN
          </asp:ListItem>
          <asp:ListItem Value="http://www.asp.net">
            ASP.NET
          </asp:ListItem>
          <asp:ListItem Value="http://www.msn.com">
            MSN
          </asp:ListItem>
        </asp:BulletedList>
        <aspsample:textdisplaywebpart id="wp1" runat="server" 
           Title="My Text Display WebPart" />
      </ZoneTemplate>
    </asp:WebPartZone>
    <aspSample:MyCatalogZone ID="CatalogZone1" runat="server">
      <ZoneTemplate>
        <asp:ImportCatalogPart id="ImportCatalogPart1" 
          runat="server" />
      </ZoneTemplate>
    </aspSample:MyCatalogZone>
  </form>
</body>
</html>

Now run the code example. Load the Web page in a browser. The first step is to export a .WebPart description file for the TextDisplayWebPart control. Click the verbs menu on the custom control (represented by the downward arrow in the title bar), and click Export. Follow the instructions to save a description file for the control. Open the .WebPart description file in an editor, and edit the value of the title property text. Find the <property> element that has the attribute name="Title", and edit the title text that is contained between the opening and closing <property> tags. Now close the Web page, and edit the page source in an editor. Delete the <aspSample:TextDisplayWebPart> control declaration element, then save and close the file.

Load the Web page again in a browser. The TextDisplayWebPart control should not appear, because you removed it. Use the Display Mode drop-down list control and select Catalog to switch the page to catalog mode. Notice that the custom CatalogZone control appears, along with the ImportCatalogPart control. Click the Browse button to locate the .WebPart description file that you exported for the TextDisplayWebPart control. You can click Upload, select the check box next to the imported control, and click Add to add it to the page. Click Close Catalog to return the page to normal browse mode. The imported control should now appear in the page, and the title that appears in the title bar of the control should be the title text you added to the .WebPart description file.

.NET Framework

• AspNetHostingPermission  

  for operating in a hosted environment. Demand value: LinkDemand; Permission value: Minimal.

• AspNetHostingPermission  

  for operating in a hosted environment. Demand value: InheritanceDemand; Permission value: Minimal.

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

Reference

Other Resources