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