CatalogZone Class
Assembly: System.Web (in system.web.dll)
Within the Web Parts control set, a zone is a region on a Web page that contains Web Parts controls. A Web Parts zone is created by a zone control, which is a type of CompositeControl designed to contain other controls. The primary functions of a zone are to lay out the controls it contains, and to provide a common user interface (UI) for those controls. For general information about zones and how they are used in Web Parts applications, see the base WebZone class, and Web Parts Control Set Overview.
A key feature of Web Parts controls is that they allow end users to modify (or personalize) Web pages according to their preferences, and save their personalized settings for future browser sessions. One aspect of modifying Web Parts pages includes the ability to add WebPart controls or other server controls to a Web Parts page. The CatalogZone control provides a list or catalog of controls that users can add to a page.
The CatalogZone control is one of the fundamental controls in the Web Parts control set. It derives from the CatalogZoneBase class, and most of its behavior is inherited from that class. The CatalogZone class essentially adds to the base class a zone template, which is an implementation of the ITemplate interface. The zone template enables developers to declaratively add CatalogPart controls to a zone in the page persistence format.
Important: |
|---|
| A CatalogZone zone can contain only CatalogPart controls, and conversely, CatalogPart controls can reside only in zones that derive from the CatalogZoneBase class, such as CatalogZone. |
A CatalogZone control becomes visible only when a user switches a Web page to catalog display mode (CatalogDisplayMode). A catalog can contain several types of CatalogPart controls. Each CatalogPart control is a type of container that contains the server controls users can add to the page. The CatalogPart controls differ according to where the server controls they contain are coming from. The following table summarizes the CatalogPart controls provided with the Web Parts control set and, for each control, what kind of server controls it contains.
| 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 and a specified format that contains state information) for a control to a catalog, so that the control can be added to a Web page. |
Because the CatalogZone class adds only a zone template to the behavior of its base class, it has few members. The CatalogZone constructor is a default constructor; with it, you can initialize a new instance of the CatalogZone class. The ZoneTemplate property gets or sets a reference to the ITemplate object that contains the controls for the zone. The CreateCatalogParts method is critical. It overrides the base method to create the collection of all CatalogPart controls contained within the zone template.
Note |
|---|
| The buttons in the CatalogZone UI require client-side scripting in order to work correctly. If scripting is disabled in the browser, the user will not be able to perform actions through the CatalogZone UI. |
Accessibility
The markup rendered by default for this control might not conform to accessibility standards such as the Web Content Accessibility Guidelines 1.0 (WCAG) priority 1 guidelines. For details about accessibility support for this control, see ASP.NET Controls and Accessibility.
| Topic | Location |
|---|---|
| How to: Enable Users to Import Web Parts Control Settings | Building ASP .NET Web Applications |
| How to: Provide Optional Web Parts Controls | Building ASP .NET Web Applications |
| How to: Export Web Parts Control Settings | Building ASP .NET Web Applications |
| How to: Enable Users to Import Web Parts Control Settings | Building ASP .NET Web Applications |
| How to: Provide Optional Web Parts Controls | Building ASP .NET Web Applications |
| How to: Export Web Parts Control Settings | Building ASP .NET Web Applications |
The following code example demonstrates declarative and programmatic use of the CatalogZone control. The code example has four parts:
-
A user control that enables you to change display modes on the Web page.
-
A file with the source code for a custom CatalogZone control, and a custom WebPart control that is imported by the catalog and added to the Web page.
-
A Web page that declares the user control, and the custom CatalogZone control.
-
An explanation of how to run the example.
The first part of this code example is the user control that enables users to change display modes on a Web 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.
The second part of the code example contains the code for the custom CatalogZone and WebPart controls. The code for the CatalogZone control demonstrates how to inherit from the CatalogZone class and customize its properties by setting some default property values in the constructor. The source code also demonstrates how to create a custom WebPart class named TextDisplayWebPart. This is the control associated with the .WebPart description file that you will import as part of this code example. After you import the description file by using the ImportCatalogPart control on the Web page, you'll be able to add the TextDisplayWebPart control to the page, fully pre-configured as specified in the description file.
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. This code example uses dynamic compilation, so if you want to run the example this way, name the source code file and add it to an App_Code subfolder of your Web application's root directory. For a walkthrough that demonstrates both methods of compiling, see Walkthrough: Developing and Using a Custom Server Control.
The third part of the code example is the Web page that contains the controls. It contains a Register directive for the user control, and another for the source file with the custom controls. Note that in the second directive, it does not name the assembly, because the example does not use an assembly, it uses dynamic compilation with the source code placed in the App_Code subfolder. The Web page declares a WebPartZone control, and within its child <zonetemplate> element, it declares a BulletedList control. While this is a standard ASP.NET control, it will have full Web Parts functionality at run time, because the WebPartManager control wraps any server control placed in a WebPartZone with a GenericWebPart object, so that other server controls can participate in Web Parts applications. Also declared in this zone is the custom WebPart control named TextDisplayWebPart. Notice that this control has an attribute of ExportMode="All" declared on it. This enables you to export a .WebPart description file that contains the property values of the control, which can be imported by other users to add the pre-configured control to other Web pages.
Note |
|---|
| To enable users of a Web Parts application to export a description file for WebPart controls, you must also enable the export feature in the Web application by adding an enableExport="true" attribute to the <webParts> element (which is a child of the <system.web> element) in the Web.config file. Export is disabled by default, so if you not yet enabled export for your application, edit the Web.config file and do it now. |
The Web page also declares the custom CatalogZone control and, within it, a <zonetemplate> element that contains an ImportCatalogPart control. The user will use this control at run time to import the .WebPart description file for the custom WebPart control.
Now run the code example. Load the Web page in a browser. The first step is to export a .WebPart description file for the TextDisplayWebPart control. Click the verbs menu on the custom control (represented by the downward arrow in the title bar), and click Export. Follow the instructions to save a description file for the control. Open the .WebPart description file in an editor, and edit the value of the title property text. Find the <property> element that has the attribute name="Title", and edit the title text that is contained between the opening and closing <property> tags. Now close the Web page, and edit the page source in an editor. Delete the <aspSample:TextDisplayWebPart> control declaration element, then save and close the file.
Load the Web page again in a browser. The TextDisplayWebPart control should not appear, because you removed it. Use the Display Mode drop-down list control and select Catalog to switch the page to catalog mode. Notice that the custom CatalogZone control appears, along with the ImportCatalogPart control. Click the Browse button to locate the .WebPart description file that you exported for the TextDisplayWebPart control. You can click Upload, select the check box next to the imported control, and click Add to add it to the page. Click Close Catalog to return the page to normal browse mode. The imported control should now appear in the page, and the title that appears in the title bar of the control should be the title text you added to the .WebPart description file.
- 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: