This documentation is archived and is not being maintained.

DeclarativeCatalogPart Class

Enables developers to add a catalog of WebPart or other server controls to a Web page in the declarative, page persistence format. This class cannot be inherited.

Namespace:  System.Web.UI.WebControls.WebParts
Assembly:  System.Web (in System.Web.dll)

[AspNetHostingPermissionAttribute(SecurityAction::InheritanceDemand, Level = AspNetHostingPermissionLevel::Minimal)]
[AspNetHostingPermissionAttribute(SecurityAction::LinkDemand, Level = AspNetHostingPermissionLevel::Minimal)]
public ref class DeclarativeCatalogPart sealed : public CatalogPart
<asp:DeclarativeCatalogPart />

Just as there are tool-oriented zones in the Web Parts control set (for details, see the ToolZone class overview), there are tool-oriented Part controls, and each of these controls must reside in a certain type of tool zone. Tool-oriented part controls in the Web Parts control set have two distinguishing characteristics:

  • They are helper controls that enable end users to personalize controls on a Web Parts page.

  • They are visible only in certain display modes.

DeclarativeCatalogPart is a part control that must reside in a CatalogZoneBase type of zone, such as the CatalogZone zone provided with the Web Parts control set. The DeclarativeCatalogPart control becomes visible only when a Web page is in catalog display mode.

The DeclarativeCatalogPart control provides a way for developers to add a set of server controls declaratively to a catalog on a Web page. A catalog, in the Web Parts control set, is simply a list of WebPart or other server controls that is visible when a page is in catalog display mode. A user can select controls from the list and add them to the Web page, which effectively gives users the ability to change the set of controls and the functionality on a page.

NoteNote:

Users can add multiple instances of the same control in a catalog to a Web page.

An advantage of using a DeclarativeCatalogPart control to create a catalog of server controls is that it does not require any coding. Page developers can work with the control entirely in the declarative (or page persistence) format, hence the name of the control.

The DeclarativeCatalogPart control has a useful property that allows developers to set up a catalog of controls that can be used throughout an entire site. Rather than declare individual server controls within a DeclarativeCatalogPart control, a developer can set the WebPartsListUserControlPath property value to the path of a user control that contains the list of server controls that should be in the catalog. At run time, the server controls referenced in the user control are loaded in the catalog. In this way, multiple pages or sites could reference the same user control to create a catalog. When the user control's list of server controls is updated, it would update all catalogs based on the user control.

The DeclarativeCatalogPart class has a number of public properties that override the inherited properties. Most of these properties are not actually used for rendering the control; they are overridden only so that special code attributes can be set on them to hide them from design tools like Microsoft Visual Studio 2005. You should not use these hidden properties, as they have no effect on rendering. The fact that they are hidden from IntelliSense and the Properties pane in Visual Studio helps developers avoid using them by mistake. All these hidden properties are noted as such in their respective Help topics.

The DeclarativeCatalogPart class also has several methods. The GetAvailableWebPartDescriptions method retrieves a WebPartDescription object for each WebPart control in the catalog, which enables a DeclarativeCatalogPart control to display information about each server control without having to create an instance of it. Another method is the GetWebPart method. This method gets an instance of a particular WebPart control, based on the description passed to the method.

NoteNote:

To improve accessibility, the DeclarativeCatalogPart control is rendered within a <fieldset> element. The <fieldset> element groups the related set of controls used for editing in the DeclarativeCatalogPart control, and it facilitates tabbed navigation among those controls for both visual user agents (such as ordinary Web browsers) and speech-oriented user agents (such as screen-reading software).

TopicLocation
How to: Enable Users to Import Web Parts Control SettingsBuilding ASP .NET Web Applications
How to: Set the Display Mode of a Web Parts PageBuilding ASP .NET Web Applications
How to: Provide Optional Web Parts ControlsBuilding ASP .NET Web Applications
How to: Enable Users to Import Web Parts Control SettingsBuilding ASP .NET Web Applications
How to: Set the Display Mode of a Web Parts PageBuilding ASP .NET Web Applications
How to: Provide Optional Web Parts ControlsBuilding ASP .NET Web Applications

The following code example demonstrates how to use the DeclarativeCatalogPart control declaratively on a Web page. The example has four parts:

  • A user control that enables you to change display modes on a Web Parts page.

  • A Web page that contains a CatalogZone control and a DeclarativeCatalogPart control.

  • A source code file that contains two custom WebPart controls.

  • An explanation of how the example works when you load the page 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.

No code example is currently available or this language may not be supported.

The second part of the code example is the Web page. At the top of the page are two Register directives, one for the user control and one for the compiled component that contains the two custom WebPart controls. Notice that the page has a declarative reference to the DeclarativeCatalogPart control, nested within the proper hierarchy of declarative elements as described in the Remarks section of this topic. The <asp:declarativecatalogpart> element contains a <webpartstemplate> element, which in turn contains references for a standard ASP.NET Calendar control and the two custom WebPart controls; these are the controls that users can select from the catalog. The page also contains editing capability, with a PropertyGridEditorPart control declared on the page. This control enables users to edit certain properties on the custom WebPart controls after they have been added to the page, and after the user has switched the page to edit mode.

No code example is currently available or this language may not be supported.

The third part of the code example is the source code for the two WebPart controls. Notice that some properties on these controls are marked with the WebBrowsable attribute. This enables the PropertyGridEditorPart control to dynamically generate the user interface (UI) for a user to edit those properties when the controls are in edit mode. The properties are also marked with a WebDisplayName attribute, to specify the text of the label that appears next to each control in the editing UI.

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 walkthrough that demonstrates both methods of compiling, see Walkthrough: Developing and Using a Custom Web Server Control.

No code example is currently available or this language may not be supported.

When you load the page in a browser, select Catalog Mode in the Display Mode drop-down list control to switch to catalog mode. In catalog mode, you can see the controls that are available to be added to the page. Add all three controls, and then use the Display Mode drop-down list to return the page to browse mode. The three controls appear on the page. If you use the Display Mode drop-down list and switch the page to edit mode, you can click the verbs menu (the downward arrow) in the title bar of the User Information WebPart control, and click Edit to edit the control. When the editing UI is visible, you can see the PropertyGridEditorPart control. Notice that a control is rendered for each of the properties of the UserInfoWebPart class that was marked with the WebBrowsable attribute. If you make some changes in the editing UI and click the Apply button, you can use the Display Mode drop-down list to return the page to browse mode and see the full effect of the editing changes.

System::Object
  System.Web.UI::Control
    System.Web.UI.WebControls::WebControl
      System.Web.UI.WebControls::Panel
        System.Web.UI.WebControls.WebParts::Part
          System.Web.UI.WebControls.WebParts::CatalogPart
            System.Web.UI.WebControls.WebParts::DeclarativeCatalogPart

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0
Show: