Export (0) Print
Expand All

CatalogZoneBase Class

Note: This class is new in the .NET Framework version 2.0.

Serves as the base class for all zone controls that act as catalogs to contain lists of WebPart controls that can be added to a Web page.

Namespace: System.Web.UI.WebControls.WebParts
Assembly: System.Web (in system.web.dll)

public abstract class CatalogZoneBase : ToolZone, IPostBackDataHandler
public abstract class CatalogZoneBase extends ToolZone implements IPostBackDataHandler
public abstract class CatalogZoneBase extends ToolZone implements IPostBackDataHandler

The CatalogZoneBase class is a base class that inherits from the ToolZone class, and provides a base set of behaviors for derived zones that provide lists or catalogs of controls that users can add to a Web page.

The CatalogZoneBase class provides a unique user interface (UI) that enables end users to add WebPart controls and other server controls (such as ASP.NET server controls, user controls, and custom server controls) to Web pages. Controls that derive from the CatalogZoneBase class, such as CatalogZone, are the controls actually placed on Web pages, and they act as containers for other controls, known as CatalogPart controls, that create lists of server controls for users to add to a page. Zones that derive from the CatalogZoneBase class can appear only when the page is in the catalog display mode.

NoteImportant:

A CatalogZoneBase zone can contain only CatalogPart controls, and conversely, CatalogPart controls can reside only in CatalogZoneBase zones.

The mechanism for adding server controls to a catalog is a set of three controls that derive from the base CatalogPart class. The three CatalogPart controls are listed in the following table.

Control

Description

PageCatalogPart

Maintains references to controls that have been closed on a page. These controls can be reopened (added back to the page) by users.

DeclarativeCatalogPart

Contains references to controls that are declared in a Web Parts catalog in the markup of a Web page. These controls can be added to a Web page by users.

ImportCatalogPart

Provides the UI for a user to upload a definition file (an XML file with a .WebPart extension that imports settings for a control) to a catalog, so that the control can be added to a Web page. The control must be present on the server before the definition file can be imported.

The CatalogZoneBase class has a number of properties that are useful for displaying catalogs of WebPart controls. The AddVerb property references the verb that adds a selected control from the catalog to the page, while the CloseVerb property references a verb that closes the catalog and returns the page's display mode to browse mode. The CatalogParts property references the collection of all CatalogPart controls in the zone. Several text-oriented properties, such as EmptyZoneText, HeaderText, and InstructionText, override base properties to provide default text appropriate for catalogs. The SelectTargetZoneText property contains the text alongside the drop-down list control that allows users to choose which zone a control will be added to.

Several other properties are included in the CatalogZoneBase class. The SelectedCatalogPartID property is a unique string identifier for the currently selected CatalogPart control. The ShowCatalogIcons property indicates whether to show the icons that can be associated with controls by setting the CatalogIconImageUrl property on a WebPart control.

The PartLinkStyle property contains style attributes for the links to the CatalogPart controls that are not currently selected in the zone. In contrast, the SelectedPartLinkStyle property contains style attributes for a link to the CatalogPart control that the user has currently selected in the zone.

In addition to the properties, there are also some methods in the CatalogZoneBase class, in addition to the standard event-handling and rendering methods inherited from other base controls, which are uniquely designed for the purpose of handling catalogs of controls. The CreateCatalogPartChrome method creates the chrome (peripheral UI elements such as a border, verbs, icons, and a title) that surrounds each CatalogPart control in the zone, and also handles the rendering for the controls. The CreateCatalogParts method is an abstract method; derived classes override it to create instances of all the CatalogPart controls contained in the zone. The InvalidateCatalogParts method can be called by a derived class if the collection of CatalogPart controls in the zone changes for some programmatic reason, and the derived class needs to recreate the collection. The LoadPostData method loads the previously existing state for the check boxes next to the WebPart controls in the catalog, whenever the page is posted back to the server; conversely, the SaveControlState method saves the state of the check boxes. Finally, the RenderCatalogPartLinks method provides all the rendering for the links to each CatalogPart control contained in the zone.

Notes to Inheritors If you want to develop a custom zone for hosting CatalogPart controls, you must determine whether you want to provide zone template support. A zone template is created by types that implement the ITemplate interface, and is necessary if you want to enable page developers using your custom zone to reference CatalogPart controls within your zone in the declarative markup of a Web page. If you need zone template support, you should inherit from the CatalogZone class. In contrast, if your custom zone and its CatalogPart controls are going to be self-contained, and they will be created programmatically without any options for page developers to specify controls declaratively in a zone template, then you can inherit directly from the CatalogZoneBase class. If you inherit from the CatalogZoneBase class, you must override the CreateCatalogParts method, and add the WebPart or other server controls you want in your catalog to a CatalogPartCollection object.

The following code example demonstrates several declarative and programmatic uses of the CatalogZoneBase class. Because the class is abstract, the code examples use the derived CatalogZone class that ships with the Web Parts control set, demonstrating the properties and methods that it inherits from the CatalogZoneBase class.

The code example has four parts:

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

  • A Web page that contains a reference to a CatalogZone control, and some code that demonstrates usage of some key CatalogZoneBase class members.

  • A custom WebPart control that is added to the custom CatalogZone control.

  • A description of how the example works in a browser.

The first part of this code example is the user control that enables you to change display modes on the 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" />
    <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 is a Web page that contains a declarative reference to a CatalogZone control. Near the top of the page are two Register directives--one for the user control, and one for the custom WebPart control. Notice that below the <asp:WebPartZone> element is an <asp: CatalogZone> element that contains declarative references to the custom WebPart control, and to an ASP.NET Calendar control. The zone also has a variety of tags and properties set to determine its appearance and behavior. Between the <script> tags in the page is a variety of event-handling code, most of which demonstrates the various programmatic uses of the CatalogZoneBase members.

<%@ page language="c#" %>
<%@ register TagPrefix="uc1" 
  TagName="DisplayModeMenuCS" 
  Src="DisplayModeMenucs.ascx" %>
<%@ register tagprefix="aspSample" 
  Namespace="Samples.AspNet.CS.Controls" 
  Assembly="TextDisplayWebPartCS" %>
  
<script runat="server">

  WebPartManager manager;

  protected void WebPartManager1_DisplayModeChanged(object sender,
    WebPartDisplayModeEventArgs e)
  {
    if (e.OldDisplayMode.Name != "Catalog")
      Panel1.Visible = true;
    else
      Panel1.Visible = false;
  }
  
  protected void Button1_Click(object sender, EventArgs e)
  {
    if (CatalogZone1.AddVerb.Enabled)
    {
      CatalogZone1.AddVerb.Enabled = false;
      CatalogZone1.CloseVerb.Enabled = false;
    }
    else
    {
      CatalogZone1.AddVerb.Enabled = true;
      CatalogZone1.CloseVerb.Enabled = true;
    }
  }

  protected void Button2_Click(object sender, EventArgs e)
  {
    Label1.Text = "<h3>CatalogPart List</h3>";
    foreach(CatalogPart part in CatalogZone1.CatalogParts)
    {
      Label1.Text += part.ID + "<br />";
    }
  }

  protected void Button3_Click(object sender, EventArgs e)
  {
    CatalogZone1.SelectTargetZoneText = "Add to zone";
    CatalogZone1.EmptyZoneText = "Zone is empty";
    CatalogZone1.HeaderText = "My Updated Header";
    CatalogZone1.InstructionText = "My Updated Instructions";
  }

  protected void Button4_Click(object sender, EventArgs e)
  {
    Label1.Text = CatalogZone1.SelectedCatalogPartID;
  }

  protected void Button5_Click(object sender, EventArgs e)
  {
    CatalogZone1.PartLinkStyle.ForeColor = System.Drawing.Color.Red;
    CatalogZone1.SelectedPartLinkStyle.ForeColor = 
      System.Drawing.Color.Blue;
  }

</script>

<html>
  <head id="Head1" runat="server">
    <title>
      CatalogZoneBase Example
    </title>
  </head>
  <body>
    <form id="form1" runat="server">
      <asp:webpartmanager id="WebPartManager1" runat="server" 
        OnDisplayModeChanged="WebPartManager1_DisplayModeChanged" />
      <uc1:DisplayModeMenuCS ID="DisplayModeMenu1" runat="server" />
      <asp:webpartzone id="zone1" 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>
        </ZoneTemplate>        
      </asp:webpartzone>
      <asp:CatalogZone ID="CatalogZone1" runat="server"
        EmptyZoneText="No controls are in the zone."
        HeaderText="My Web Parts Catalog"
        InstructionText="Add Web Parts controls to the zone."
        PartLinkStyle-Font-Italic="true"
        SelectedPartLinkStyle-Font-Bold="true"
        SelectTargetZoneText="Select zone"
        AddVerb-Text="Add Control"
        CloseVerb-Description="Close and return to browse mode." 
        SelectedCatalogPartID="Currently Selected CatalogPart ID.">
        <ZoneTemplate>
          <asp:DeclarativeCatalogPart ID="DeclarativeCatalogPart1" 
            runat="server">
            <WebPartsTemplate>
              <aspSample:TextDisplayWebPart 
                runat="server"   
                id="textwebpart" 
                title = "Text Content WebPart" 
                ExportMode="All"/>  
              <asp:Calendar id="calendar1" runat="server" 
                title="My Calendar" />               
            </WebPartsTemplate>
          </asp:DeclarativeCatalogPart> 
          <asp:PageCatalogPart ID="PageCatalogPart1" runat="server" />
          <asp:ImportCatalogPart ID="ImportCatalogPart1" runat="server" /> 
        </ZoneTemplate>
      </asp:CatalogZone>
      <hr />
      <asp:CatalogZone ID="CatalogZone2" runat="server"
        BorderWidth="2"
        HeaderText="My Empty CatalogZone"
        EmptyZoneText="No controls are in the zone." />
      <hr />
      <asp:Panel ID="Panel1" runat="server" Visible="false">
        <asp:Button ID="Button1" runat="server" Width="200" 
          Text="Enable or Disable Verbs" 
          OnClick="Button1_Click" />
        <br />
        <asp:Button ID="Button2" runat="server" Width="200" 
          Text="List CatalogParts" OnClick="Button2_Click" />  
        <br />
        <asp:Button ID="Button3" runat="server" Width="200" 
          Text="Set Zone Text Properties" OnClick="Button3_Click" />  
        <br />   
        <asp:Button ID="Button4" runat="server" Width="200" 
          Text="Show Selected CatalogPart ID" OnClick="Button4_Click"  />  
        <br /> 
        <asp:Button ID="Button5" runat="server" Width="200" 
          Text="Change Part Link Styles" OnClick="Button5_Click"  />  
        <br />     
        <asp:Label ID="Label1" runat="server" Text="" /></asp:Panel>
    </form>
  </body>
</html>

The third part of the code example is the custom WebPart control named TextDisplayWebPart. It is declared within the zone, and an end user can add it from the catalog to the page. 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. For a demonstration of both methods of compiling, see Walkthrough: Developing and Using a Custom 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
{
  [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;
      }
    }

  }
}

Note that for the code example to work, there is a setting you must add in the Web.config file to enable exporting Web Parts description files. Ensure that you have a Web.config file in the same directory as the Web page for this code example. Within the <system.web> section, make sure there is a <webParts> element with an enableExport attribute set to true, as in the following markup.

<webParts enableExport="true">

...

</webParts>

When you load the page in a browser, you can select Catalog from the drop-down list box to switch to catalog display mode. When the catalog is visible, you can see the two server controls that can be added from the catalog to the page, and you can also note in the UI the effects of the declarative and programmatic uses of the CatalogZoneBase class members.

System.Object
   System.Web.UI.Control
     System.Web.UI.WebControls.WebControl
       System.Web.UI.WebControls.CompositeControl
         System.Web.UI.WebControls.WebParts.WebZone
           System.Web.UI.WebControls.WebParts.ToolZone
            System.Web.UI.WebControls.WebParts.CatalogZoneBase
               System.Web.UI.WebControls.WebParts.CatalogZone

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 98, Windows 2000 SP4, Windows Millennium Edition, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

.NET Framework

Supported in: 2.0

Community Additions

ADD
Show:
© 2014 Microsoft