CatalogZoneBase Class
Assembly: System.Web (in system.web.dll)
'Declaration Public MustInherit Class CatalogZoneBase Inherits ToolZone Implements IPostBackDataHandler 'Usage Dim instance As CatalogZoneBase
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.
Important: |
|---|
| 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 |
|---|---|
| Maintains references to controls that have been closed on a page. These controls can be reopened (added back to the page) by users. | |
| 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. | |
| 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="vb" classname="DisplayModeMenuVB"%> <script runat="server"> ' Use a field to reference the current WebPartManager. Dim _manager As WebPartManager Sub Page_Init(ByVal sender As Object, ByVal e As EventArgs) AddHandler Page.InitComplete, AddressOf InitComplete End Sub Sub InitComplete(ByVal sender As Object, ByVal e As System.EventArgs) _manager = WebPartManager.GetCurrentWebPartManager(Page) Dim browseModeName As String = WebPartManager.BrowseDisplayMode.Name ' Fill the dropdown with the names of supported display modes. Dim mode As WebPartDisplayMode For Each mode In _manager.SupportedDisplayModes Dim modeName As String = mode.Name ' Make sure a mode is enabled before adding it. If mode.IsEnabled(_manager) Then Dim item As New ListItem(modeName, modeName) DisplayModeDropdown.Items.Add(item) End If Next mode ' 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 Then Panel2.Visible = True If _manager.Personalization.Scope = PersonalizationScope.User Then RadioButton1.Checked = True Else RadioButton2.Checked = True End If End If End Sub ' Change the page to the selected display mode. Sub DisplayModeDropdown_SelectedIndexChanged(ByVal sender As Object, _ ByVal e As EventArgs) Dim selectedMode As String = DisplayModeDropdown.SelectedValue Dim mode As WebPartDisplayMode = _ _manager.SupportedDisplayModes(selectedMode) If Not (mode Is Nothing) Then _manager.DisplayMode = mode End If End Sub ' Set the selected item equal to the current display mode. Sub Page_PreRender(ByVal sender As Object, ByVal e As EventArgs) Dim items As ListItemCollection = DisplayModeDropdown.Items Dim selectedIndex As Integer = _ items.IndexOf(items.FindByText(_manager.DisplayMode.Name)) DisplayModeDropdown.SelectedIndex = selectedIndex End Sub ' Reset all of a user's personalization data for the page. Protected Sub LinkButton1_Click(ByVal sender As Object, _ ByVal e As EventArgs) _manager.Personalization.ResetPersonalizationState() End Sub ' If not in User personalization scope, toggle into it. Protected Sub RadioButton1_CheckedChanged(ByVal sender As Object, _ ByVal e As EventArgs) If _manager.Personalization.Scope = PersonalizationScope.Shared Then _manager.Personalization.ToggleScope() End If End Sub ' If not in Shared scope, and if user is allowed, toggle the scope. Protected Sub RadioButton2_CheckedChanged(ByVal sender As Object, _ ByVal e As EventArgs) If _manager.Personalization.CanEnterSharedScope AndAlso _ _manager.Personalization.Scope = PersonalizationScope.User Then _manager.Personalization.ToggleScope() End If End Sub </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" /> <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="vb" %> <%@ register TagPrefix="uc1" TagName="DisplayModeMenuVB" Src="DisplayModeMenuvb.ascx" %> <%@ register tagprefix="aspSample" Namespace="Samples.AspNet.VB.Controls" Assembly="TextDisplayWebPartVB" %> <script runat="server"> Dim manager As WebPartManager Protected Sub WebPartManager1_DisplayModeChanged(ByVal sender _ As Object, ByVal e As WebPartDisplayModeEventArgs) If e.OldDisplayMode.Name <> "Catalog" Then Panel1.Visible = True Else Panel1.Visible = False End If End Sub Protected Sub Button1_Click(ByVal sender As Object, _ ByVal e As EventArgs) If CatalogZone1.AddVerb.Enabled Then CatalogZone1.AddVerb.Enabled = False CatalogZone1.CloseVerb.Enabled = False Else CatalogZone1.AddVerb.Enabled = True CatalogZone1.CloseVerb.Enabled = True End If End Sub Protected Sub Button2_Click(ByVal sender As Object, _ ByVal e As EventArgs) Label1.Text = "<h3>CatalogPart List</h3>" Dim part As CatalogPart For Each part In CatalogZone1.CatalogParts Label1.Text += part.ID + "<br />" Next part End Sub Protected Sub Button3_Click(ByVal sender As Object, _ ByVal e As EventArgs) CatalogZone1.SelectTargetZoneText = "Add to zone" CatalogZone1.EmptyZoneText = "Zone is empty" CatalogZone1.HeaderText = "My Updated Header" CatalogZone1.InstructionText = "My Updated Instructions" End Sub Protected Sub Button4_Click(ByVal sender As Object, _ ByVal e As EventArgs) Label1.Text = CatalogZone1.SelectedCatalogPartID End Sub Protected Sub Button5_Click(ByVal sender As Object, _ ByVal e As EventArgs) CatalogZone1.PartLinkStyle.ForeColor = _ System.Drawing.Color.Red CatalogZone1.SelectedPartLinkStyle.ForeColor = _ System.Drawing.Color.Blue End Sub </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:DisplayModeMenuVB 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.
Imports System Imports System.Collections Imports System.ComponentModel Imports System.Drawing Imports System.Security.Permissions Imports System.Web Imports System.Web.UI Imports System.Web.UI.WebControls Imports System.Web.UI.WebControls.WebParts Namespace Samples.AspNet.VB.Controls <AspNetHostingPermission(SecurityAction.Demand, _ Level:=AspNetHostingPermissionLevel.Minimal)> _ <AspNetHostingPermission(SecurityAction.InheritanceDemand, _ Level:=AspNetHostingPermissionLevel.Minimal)> _ Public Class TextDisplayWebPart Inherits WebPart Private _contentText As String = Nothing Private _fontStyle As String = Nothing Private input As TextBox Private DisplayContent As Label Private lineBreak As Literal <Personalizable(), WebBrowsable()> _ Public Property ContentText() As String Get Return _contentText End Get Set(ByVal value As String) _contentText = value End Set End Property Protected Overrides Sub CreateChildControls() Controls.Clear() DisplayContent = New Label() DisplayContent.BackColor = Color.LightBlue DisplayContent.Text = Me.ContentText Me.Controls.Add(DisplayContent) lineBreak = New Literal() lineBreak.Text = "<br />" Controls.Add(lineBreak) input = New TextBox() Me.Controls.Add(input) Dim update As New Button() update.Text = "Set Label Content" AddHandler update.Click, AddressOf Me.submit_Click Me.Controls.Add(update) End Sub Private Sub submit_Click(ByVal sender As Object, _ ByVal e As EventArgs) ' Update the label string. If input.Text <> String.Empty Then _contentText = input.Text + "<br />" input.Text = String.Empty DisplayContent.Text = Me.ContentText End If End Sub End Class End Namespace
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.
- 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.
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
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.
Important: