Part Class

The Part class defines properties that are common to all part controls and enable them to have a modular and consistent appearance on a Web page. These common properties include a title, a description, and characteristics of the chrome or frame that surrounds a part control.

The Title property specifies a title for the part control. The Description property is used to summarize the part control's purpose, and appears as a ToolTip in the title bar of the control. The ChromeType property dictates what kind of border is rendered around a part control, while the ChromeState property indicates whether a part control is rendered normally, or minimized. The border of a part control is affected by the properties of the zone that contains it; for example, the PartChromeType property affects the frames of all part controls contained in a zone.

One type of part control is the WebPart control, which renders content inside a corresponding zone. Another type is the EditorPart control, which provides user interface (UI) controls used to modify (personalize) individual WebPart controls. A third type of part control is the CatalogPart control, which provides a list of WebPart controls that users can add to or remove from a Web page.

Part controls are contained in zones, all of which derive from the abstract WebZone class. A zone is responsible for organizing the part controls it contains. Each zone also renders UI elements for itself, including a header, a footer, a title bar, and UI elements around each contained part control, such as borders.

Note

While part controls usually reside in zones, it is possible to place a part control outside a zone, if the control is referenced declaratively in the markup of a Web page. If a part control is declared outside a zone on a Web page, the control still works, but loses most of its Web Parts functionality. For example, the control cannot be edited, and cannot be dragged into a zone at run time. It is also helpful to remember that no part control can be dragged from a zone and dropped onto a page outside of a zone at run time.

Some examples of base part types, and their corresponding zone types, are shown in the following table.

The various kinds of part controls that derive from the Part class handle the inherited, UI-oriented properties differently. WebPart controls override several of the inherited UI properties, and mark them with the Personalizable attribute (for details, see the PersonalizableAttribute class documentation), which enables the values of those properties to be saved for future browser sessions, a feature known as personalization. For example, if you programmatically enable a user to update the value of a WebPart control's Title property at run time, that value will be personalized (assuming that personalization is enabled, which is the default). Several UI properties that WebPart controls inherit from the Part class, and from the WebControl class, are handled the same way.

In contrast, other part controls, such as EditorPart and CatalogPart, do not enable the inherited UI properties to be personalized. For this reason, programmatically assigned property values are not saved for future browser sessions. For example, if you programmatically enable a user to update a PropertyGridEditorPart control's Title property at run time, the updated value is lost after the control is closed or the browser session ends.

An easy way to save the values on such inherited UI properties for EditorPart and CatalogPart controls for future browser sessions is to declare the property values in page persistence format. However, this is a static approach and still does not allow users to personalize the property values. As an alternative, if you want to enable programmatic updates to the inherited UI properties so users can personalize them at run time, you can use private, static variables to save the property values. Each time a new instance of an EditorPart or CatalogPart control is created (for example, in the method that handles the control's Init event), you can reassign a static variable's value to a corresponding property. Such an approach gives users the ability to personalize the editing UI and catalog UI of a Web Parts application.

Normally, you should not inherit directly from the Part class to develop custom Web Parts controls. To provide full Web Parts functionality, the Web Parts control set requires the classes derived from the Part class, namely WebPart, EditorPart, and CatalogPart, so you should derive from them to develop custom controls. However, it is still important to understand the behavior of the base Part class, because it provides a common set of properties used by all other part classes.

The following code examples demonstrate declarative use of several properties of the Part class, by using two instances of a custom WebPart control referenced in an ASP.NET Web 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 walkthrough that demonstrates both methods of compiling, see Walkthrough: Developing and Using a Custom Web Server Control.

The first part of the example contains the code for the custom control, named TextDisplayWebPart. Because the control derives from WebPart, it also inherits the common properties that the Part class provides, and illustrates the use of those properties in this code example.

using System;
using System.Security.Permissions;
using System.Web;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;

namespace Samples.AspNet.CS.Controls
{
  [AspNetHostingPermission(SecurityAction.Demand, 
    Level=AspNetHostingPermissionLevel.Minimal)]
  [AspNetHostingPermission(SecurityAction.InheritanceDemand, 
    Level=AspNetHostingPermissionLevel.Minimal)]
  public class TextDisplayWebPart : WebPart
  {
    private String _contentText = null;
    TextBox input;
    Label DisplayContent;
    const string _subTitle = "Contoso, Ltd";

    public TextDisplayWebPart()
    {
      this.AllowClose = false;
    }

    [
      Personalizable(PersonalizationScope.User, true),
      WebBrowsable()
    ]
    public String ContentText
    {
      get { return _contentText; }
      set { _contentText = value; }
    }

    protected override void CreateChildControls()
    {
      Controls.Clear();
      DisplayContent = new Label();
      DisplayContent.BackColor = 
        System.Drawing.Color.LightBlue;
      DisplayContent.Text = this.ContentText;
      this.Controls.Add(DisplayContent);
      input = new TextBox();
      this.Controls.Add(input);
      Button update = new Button();
      update.Text = "Set Label Content";
      update.Click += new EventHandler(this.submit_Click);
      this.Controls.Add(update);
      ChildControlsCreated = true;
    }

    private void submit_Click(object sender, EventArgs e)
    {
      // Update the label string.
      if (input.Text != String.Empty)
      {
        this.ContentText = Page.Server.HtmlEncode(input.Text) + @"<br />";
        // Clear the input textbox.
        input.Text = String.Empty;
        DisplayContent.Text = this.ContentText;
      }
    }
  }
}

The second part of the example shows how to reference the custom part controls in an ASP.NET Web page. Notice that the various Part properties are assigned declaratively to the custom control instances. Compare the declarative code that references the two instances on the page, and then load the page in a browser. Note how the various properties affect the appearance of the controls. For example, after you load the page in a browser, the second instance of the TextDisplayWebPart control appears minimized, because its ChromeState property value is set to Minimized.

<%@ page language="C#" %>
<%@ register tagprefix="aspSample" 
             Namespace="Samples.AspNet.CS.Controls" 
             Assembly="TextDisplayWebPartCS" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
    <title>ASP.NET Example</title>
</head>
<body>
  <form id="Form1" runat="server">
    <asp:webpartmanager id="WebPartManager1" runat="server" />
    <asp:webpartzone
      id="WebPartZone1"
      runat="server"
      backcolor="#99cccc">
        <parttitlestyle font-bold="true" forecolor="#ffffff" />
        <partstyle
          borderwidth="1px" 
          borderstyle="Solid" 
          bordercolor="#81AAF2" />
        <zonetemplate>
          <aspSample:TextDisplayWebPart 
            runat="server"   
            id="textwebpart" 
            title = "Text Content WebPart" 
            Description="A text content WebPart control."
            ChromeType="TitleAndBorder"
            width="350px" />
        </zonetemplate>
    </asp:webpartzone>
    <asp:webpartzone
      id="WebPartZone2"
      runat="server"
      backcolor="#99cccc">
        <parttitlestyle font-bold="true" forecolor="#ffffff" />
        <partstyle
          borderwidth="1px" 
          borderstyle="Solid" 
          bordercolor="#81AAF2" />
        <zonetemplate>
          <aspSample:TextDisplayWebPart 
            runat="server"   
            id="textwebpart2" 
            title = "Text Content WebPart 2" 
            Description="A text content WebPart control."
            ChromeType="TitleOnly"
            ChromeState="Minimized"
            width="350px" />
        </zonetemplate>
    </asp:webpartzone>
  </form>
</body>
</html>

.NET Framework

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

Reference

Other Resources