DeclarativeCatalogPart 控件使您能够将 WebPart 的目录或其他服务器控件添加到网页。这可让用户在运行时更改页面上可用的控件集和功能。目录是 WebPart 或其他服务器控件的列表,当页面处于目录显示模式时,该列表是可见的。在设计时,您可以将控件添加到 DeclarativeCatalogPart 控件中;在运行时,用户可以选择要在页面中查看的控件,方法是从目录列表中进行选择。
当用户在运行时从控件目录中选择控件时,DeclarativeCatalogPart 控件会将控件的新实例添加到网页中。用户可以将目录中同一控件的多个实例添加到网页中。
启用 DeclarativeCatalogPart Web 服务器控件
必须将 DeclarativeCatalogPart 控件放在 CatalogZoneBase 区域(如 CatalogZone 区域)中。仅当网页处于目录显示模式时 DeclarativeCatalogPart 控件才变为可见。
创建控件的应用程序范围的目录
DeclarativeCatalogPart 控件使您能够设置站点中可用的控件目录。您可以将 WebPartsListUserControlPath 属性设置为用户控件(包含目录中的服务器控件列表)的路径,而不是在 DeclarativeCatalogPart 控件中声明单个服务器控件。在运行时,用户控件中引用的服务器控件会加载到目录中。此策略使多个页面或站点能够引用相同的用户控件来创建目录。当更新用户控件中的服务器控件列表时,基于该用户控件的所有目录将被更新。
一、DeclarativeCatalogPart 类
使开发人员能够将 WebPart 或其他服务器控件的目录以声明性、页持久性格式添加到网页上。无法继承此类。
正如 Web 部件控件集中有面向工具的区域一样,其中也有面向工具的 Part 控件,并且这些控件中的每一个都必须位于某种类型的工具区域中。Web 部件控件集中面向工具的部件控件具有两个显著特征:
·它们是帮助器控件,最终用户可用来个性化 Web 部件页上的控件。
·它们只在某些显示模式下可见。
DeclarativeCatalogPart 是必须位于 CatalogZoneBase 类型的区域(如随 Web 部件控件集提供的 CatalogZone 区域)中的部件控件。仅当网页处于目录显示模式时 DeclarativeCatalogPart 控件才变为可见。
DeclarativeCatalogPart 控件为开发人员提供了一种以声明方式向网页上的目录添加一组服务器控件的方法。Web 部件控件集中的目录只是在页面处于目录显示模式时可见的 WebPart 或其他服务器控件的一个列表。用户可以从列表中选择控件并将它们添加到网页中,这有效地为用户提供了改变页面上的控件集和功能的能力。
说明: 用户可以向网页的目录中添加同一控件的多个实例。
使用 DeclarativeCatalogPart 控件创建服务器控件的目录的一个优点是它不需要任何编码。网页开发人员可以完全以声明性(或页持久性)格式使用该控件,因此也可以这样使用该控件的名称。
DeclarativeCatalogPart 控件具有一个有用的属性,它允许开发人员建立可在整个站点中使用的控件目录。开发人员可以将 WebPartsListUserControlPath 属性值设置为用户控件(包含应在目录中的服务器控件列表)的路径,而不是在 DeclarativeCatalogPart 控件中声明单独的服务器控件。在运行时,用户控件中引用的服务器控件在目录中加载。这样,多个页面或站点可以引用相同的用户控件来创建目录。当该用户控件的服务器控件列表更新时,将更新基于该用户控件的所有目录。
DeclarativeCatalogPart 类具有许多重写继承属性的公共属性。这些属性 (Property) 中的大多数实际上并不用于呈现该控件;重写它们仅仅是为了可以对它们设置特殊的代码属性 (Attribute) 以在设计工具(如 Microsoft Visual Studio 2005)中隐藏它们。不应使用这些隐藏的属性,因为它们对呈现不起任何作用。在 Visual Studio 的 IntelliSense 和“属性”窗格中隐藏这些属性,可帮助开发人员避免错误使用它们。所有这些隐藏的属性在其各自的“帮助”主题中都进行了此类说明。
DeclarativeCatalogPart 类还具有几个方法。GetAvailableWebPartDescriptions 方法检索目录中每个 WebPart 控件的 WebPartDescription 对象,这使得 DeclarativeCatalogPart 控件无需创建每个服务器控件的实例即可显示其有关信息。另一个方法是 GetWebPart 方法。此方法根据传入的说明,获取特定 WebPart 控件的实例。
说明: 为改进可访问性,在 <fieldset> 元素中呈现了 DeclarativeCatalogPart 控件。<fieldset> 元素在 DeclarativeCatalogPart 控件中对一组用于编辑的相关控件进行分组,还为在那些兼用于可视化用户代理(如普通 Web 浏览器)和面向语音的用户代理(如屏幕阅读软件)的控件之间进行选项卡式导航提供便利。
1.1、示例
下面的代码示例演示如何在网页上以声明方式使用 DeclarativeCatalogPart 控件。此示例包含四部分:
·一个用户控件,可用于更改 Web 部件页上的显示模式。
·一个网页,包含一个 CatalogZone 控件和一个 DeclarativeCatalogPart 控件。
·一个包含两个自定义 WebPart 控件的源代码文件。
·对您在浏览器中加载页面时示例的运行方式的说明。
此代码示例的第一部分是用户控件,可用于更改页的显示模式。
<%@ 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=" 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>
该代码示例的第二部分为网页。在页顶部有两条 Register 指令,一条针对用户控件,一条针对包含两个自定义 WebPart 控件的已编译组件。注意,该页有一个对 DeclarativeCatalogPart 控件的声明性引用,该控件嵌套在声明性元素的适当层次结构内,如本主题“备注”部分所述。<asp:declarativecatalogpart> 元素包含一个 <webpartstemplate> 元素,后者又包含对一个标准 ASP.NET Calendar 控件和两个自定义 WebPart 控件的引用;这些是用户可从目录中选择的控件。由于该页面上声明了一个 PropertyGridEditorPart 控件,该页面还包含编辑功能。此控件使用户能够在向该页面添加自定义 WebPart 控件和用户将该页面切换到编辑模式之后编辑这些自定义控件的特定属性。
<%@ page language="c#" %>
<%@ register TagPrefix="uc1"
TagName="DisplayModeMenuCS"
Src="DisplayModeMenuCS.ascx" %>
<%@ register tagprefix="aspSample"
Namespace="Samples.AspNet.CS.Controls"
Assembly="UserInfoWebPartCS" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html >
<head id="Head1" runat="server">
<title>
DeclarativeCatalogPart Control
</title>
</head>
<body>
<form id="form1" runat="server">
<asp:webpartmanager id="WebPartManager1" runat="server" />
<uc1:DisplayModeMenuCS ID="DisplayModeMenu1" runat="server" />
<asp:webpartzone id="zone1" runat="server" >
<PartTitleStyle BorderWidth="1"
Font-Names="Verdana, Arial"
Font-Size="110%"
BackColor="LightBlue" />
<zonetemplate>
<asp:BulletedList ID="BulletedList1"
Runat="server"
DisplayMode="HyperLink"
Title="Favorites">
<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">
<ZoneTemplate>
<asp:DeclarativeCatalogPart ID="DeclarativeCatalogPart1"
runat="server"
Title="Web Parts Catalog"
ChromeType="TitleOnly"
Description="Contains a user control with Web Parts and
an ASP.NET Calendar control.">
<WebPartsTemplate>
<asp:Calendar ID="Calendar1" runat="server"
Title="My Calendar"
Description="ASP.NET Calendar control used as a personal calendar." />
<aspSample:UserInfoWebPart
runat="server"
id="userinfo1"
title = "User Information WebPart"
Description ="Contains custom, editable user information
for display on a page." />
<aspSample:TextDisplayWebPart
runat="server"
id="TextDisplayWebPart1"
title = "Text Display WebPart"
Description="Contains a label that users can dynamically update." />
</WebPartsTemplate>
</asp:DeclarativeCatalogPart>
</ZoneTemplate>
</asp:CatalogZone>
<asp:EditorZone ID="EditorZone1" runat="server">
<ZoneTemplate>
<asp:PropertyGridEditorPart ID="PropertyGridEditorPart1" runat="server" />
</ZoneTemplate>