ASP.NET - CatalogZone Web 服务器控件概述

 

      Web 部件控件（例如 CatalogZone 控件）的一项主要功能是可以让最终用户个性化网页并保存其个性化设置。CatalogZone 控件允许最终用户在运行时向 Web 部件页添加 WebPart 控件或其他服务器控件。CatalogZone 控件用作 Web 部件控件集内的主控件，用于在网页中承载 CatalogPart 控件。

 

启用 CatalogZone Web 服务器控件

仅当用户将网页切换至目录显示模式 (CatalogDisplayMode) 时，CatalogZone 控件才变为可见。有关演示如何使用 CatalogZone 控件的代码示例，请参见 CatalogZone Web 服务器控件声明性语法和 System.Web.UI.WebControls.WebParts.CatalogZone 中的示例。

 

CatalogZone Web 服务器控件附带的 CatalogPart 控件

由 CatalogZone 控件创建的区域可以包含多种 CatalogPart 控件。每个 CatalogPart 控件都是一种容器，其中包含用户可添加至页面的服务器控件。CatalogPart 控件因其包含的服务器控件的来源而不同。

 

一、CatalogZone 类

      在 Web 部件控件集中，区域是指网页上包含 Web 部件控件的某个区域。Web 部件区域由区域控件创建，区域控件是一种设计用来包含其他控件的 CompositeControl。区域的主要功能是对其所含的控件进行布局，并为这些控件提供公共的用户界面 (UI)。

Web 部件控件的一项主要功能是使最终用户根据个人的喜好来修改（或个性化）网页，并保存个性化设置以供将来的浏览器会话使用。修改 Web 部件页的一个方面是将 WebPart 控件或其他服务器控件添加至 Web 部件页。CatalogZone 控件提供用户可以添加到页的控件的列表或目录。

CatalogZone 控件是 Web 部件控件集中的一个基本控件。该控件从 CatalogZoneBase 类派生，且它的大多数行为也都是从该类继承的。CatalogZone 类实质上将一个区域模板添加至基类，该模板是 ITemplate 接口的实现。区域模板使开发人员能以声明方式将 CatalogPart 控件添加至页持久性格式的区域。

重要说明： CatalogZone 区域只能包含 CatalogPart 控件，反之，CatalogPart 控件只能驻留在从 CatalogZoneBase 类派生的区域（如 CatalogZone）中。

CatalogZone 控件仅当用户将网页切换至目录显示模式 (CatalogDisplayMode) 时才变为可见。目录可以包含若干类型的 CatalogPart 控件。每个 CatalogPart 控件是一类容器，包含用户可添加至页面的服务器控件。CatalogPart 控件因其包含的服务器控件的来源而不同。下面的表汇总了与 Web 部件控件集一起提供的 CatalogPart 控件，以及这些控件中的每个控件包含的服务器控件种类。

控件

说明

PageCatalogPart

维护对页上已关闭的控件的引用。这些控件可由用户重新打开（添加回页面）。

DeclarativeCatalogPart

包含对在网页标记中的 Web 部件目录中声明的控件的引用。这些控件可由用户添加至网页。

ImportCatalogPart

提供用户界面，以供用户向目录上载某个控件的定义文件（具有 .WebPart 扩展名及指定格式的 XML 文件，其中包含状态信息），从而可将该控件添加到网页中。

      因为 CatalogZone 类仅向其基类的行为中添加一个区域模板，该类的成员不多。CatalogZone 构造函数为默认构造函数；可以使用该构造函数初始化 CatalogZone 类的新实例。ZoneTemplate 属性获取或设置对包含区域控件的 ITemplate 的引用。CreateCatalogParts 方法非常重要。它重写基方法以创建区域模板中包含的所有 CatalogPart 控件的集合。

说明： CatalogZone 用户界面中的按钮要求撰写客户端脚本才能正确工作。如果在浏览器中禁用脚本撰写，则用户不能通过 CatalogZone 用户界面执行操作。

 

对继承者的说明：

如果需要对目录用户界面的呈现和行为拥有更多控制，可以创建自定义 CatalogZone 类。如果不需要向控件的用户提供以声明方式添加 CatalogPart 控件的能力，则可直接从 CatalogZoneBase 类继承。如果想要能够以声明方式添加控件，则比较简单的方法是从 CatalogZone 类继承，因为该类提供了基本区域模板。

如果从 CatalogZone 类继承，则可以重写 CreateCatalogParts 方法并使用该方法将自定义 CatalogPart 控件添加到 CatalogPartCollection（如果想要以编程方式更好地控制如何将自定义 CatalogPart 控件添加到区域）。

 

1.1、示例

下面的代码示例演示如何以声明方式和编程方式使用 CatalogZone 控件。该代码示例包含以下四部分：

·一个用户控件，用于更改网页上的显示模式。

·包含自定义 CatalogZone 控件的源代码的文件，以及由目录导入并添加到网页上的自定义 WebPart 控件。

·用于声明用户控件和自定义 CatalogZone 控件的网页。

·关于如何运行该示例的说明。

 

此代码示例的第一部分是用户控件，用户可以使用该控件更改网页的显示模式。

<%@ 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>

 

      此代码示例的第二部分包含自定义的 CatalogZone 和 WebPart 控件的源代码。CatalogZone 控件的代码演示如何从 CatalogZone 类继承，以及如何通过在构造函数中设置一些默认属性值来自定义其属性。此源代码也演示如何创建名为 TextDisplayWebPart 的自定义 WebPart 控件。此控件与将作为此代码示例的一部分导入的 .WebPart 说明文件关联。通过使用网页上的 ImportCatalogPart 控件导入该说明文件后，您就能够将按照说明文件中的指定完全预配置好的 TextDisplayWebPart 控件添加到页中。

必须编译此源代码，代码示例才能运行。可以显式编译源代码，并将结果程序集放在网站的 Bin 文件夹或全局程序集缓存中。另外，也可将源代码放入站点的 App_Code 文件夹中，源代码将在运行时在此文件夹中进行动态编译。此代码示例使用动态编译，因此，如果想要以这种方式运行示例，请为源代码文件命名并将它添加到 Web 应用程序根目录的 App_Code 子文件夹。

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;

      }

    }

  }

 

}

 

      代码示例的第三部分是包含这些控件的网页。网页包含一条用于用户控件的 Register 指令和另一条用于具有自定义控件的源文件的指令。请注意，在第二条指令中没有涉及程序集，因为示例使用的不是程序集，而是使用源代码位于 App_Code 子文件夹中的动态编译。网页声明一个 WebPartZone 控件，并在该控件的子 <zonetemplate> 元素中，声明一个 BulletedList 控件。虽然这是标准的 ASP.NET 控件，但它在运行时将具备完整的 Web 部件功能，因为 WebPartManager 控件使用 GenericWebPart 对象包装位于 WebPartZone 中的任何服务器控件，以便其他服务器控件可以参与 Web 部件应用程序。在此区域中还声明了一个名为 TextDisplayWebPart 的自定义 WebPart 控件。请注意，此控件在其上声明了 ExportMode="All" 属性。这使您能够导出包含控件的属性值的 .WebPart 说明文件，其他用户可以导入该文件以将预编译的控件添加到其他网页。

说明： 若要使 Web 部件应用程序的用户能够导出 WebPart 控件的说明文件，还必须启用 Web 应用程序中的导出功能，方法是将 enableExport="true" 属性添加到 Web.config 文件中的 <webParts> 元素（<system.web> 元素的子元素）。默认情况下禁用导出，因此如果还没有为应用程序启用导出，请编辑 Web.config 文件并立即启用导出。

网页还声明自定义 CatalogZone 控件，并在该控件中声明一个包含 ImportCatalogPart 控件的 <zonetemplate> 元素。用户将在运行时使用此控件来导入自定义 WebPart 控件的 .WebPart 说明文件。

<%@ 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  >

<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>

立即运行代码示例。请在浏览器中加载该网页。第一步是导出 TextDisplayWebPart 控件的 .WebPart 说明文件。单击自定义控件上的谓词菜单（由标题栏中的向下箭头表示），然后单击“导出”。按照说明保存该控件的说明文件。在编辑器中打开 .WebPart 说明文件，然后编辑标题属性文本的值。查找具有 name="Title" 属性的 <property> 元素，然后编辑起始与结束 <property> 标记之间包含的标题文本。现在关闭网页，然后在编辑器中编辑网页源代码。删除 <aspSample:TextDisplayWebPart> 控件声明元素，然后保存并关闭该文件。

在浏览器中再次加载该网页。不应出现 TextDisplayWebPart 控件，因为您已经将它移除。使用“显示模式”下拉列表控件并选择“目录”以将页切换到目录模式。请注意，自定义 CatalogZone 控件会与 ImportCatalogPart 控件一起出现。单击“浏览”按钮以找到为 TextDisplayWebPart 控件导出的 .WebPart 说明文件。可以单击“上载”，选中导入的控件旁的复选框，然后单击“添加”将该控件添加到页中。单击“关闭目录”可使页返回到正常浏览模式。导入的控件现在应该出现在页中，并且在控件标题栏中出现的标题应该是您添加到 .WebPart 说明文件的标题文本。