WebPart Class

When you create controls with Web Parts functionality, you have two basic options. You can create custom controls that derive from the WebPart class, or you can create or use other server controls. Existing ASP.NET controls, custom server controls, and user controls can all be given full Web Parts functionality by declaring them within (or adding them programmatically to) a WebPartZone zone control, with the result that they will be wrapped with GenericWebPart objects at run time and treated as true WebPart controls. For details, see the documentation for the GenericWebPart class. For speed of development and maximum reuse of code, using existing server controls can be a good option. For maximum programmatic control over the behavior and Web Parts functionality of controls, creating a custom control that inherits from the WebPart class is often the best option.

The abstract WebPart class inherits from the base Part control and provides the basic elements for all WebPart controls. The class includes a common set of properties that affect the appearance of the UI. The AllowClose, AllowConnect, AllowEdit, AllowHide, AllowMinimize, and AllowZoneChange properties each specify whether the user of a Web application is permitted to interact with the part control in the way indicated by the given property name. The CatalogIconImageUrl, ChromeState, ChromeType, Description, Height, HelpUrl, Hidden, Title, TitleIconImageUrl, TitleUrl, and Width properties determine the size, visibility, appearance, and supporting content (such as a title and a description) for a WebPart control.

The relationship of a WebPart control to its context within the Web Parts control set is determined by properties such as WebPartManager, which holds a reference to the control's associated WebPartManager object, and Zone, which references the WebZone that contains the control. There can be only one WebPartManager control per page, and each instance of a WebPart control can reside within only one WebZone at a time.

Note
A WebPart control can be placed outside of a zone on a Web page, but in this case it functions as a normal server control and loses nearly all Web Parts functionality.

Several other important properties affect unique features of WebPart controls. The AuthorizationFilter property allows developers to set an arbitrary string that can be used as a filter at run time to determine whether a control is added to the page. Used together with a feature such as role management, the AuthorizationFilter property provides a useful mechanism for creating views based on defined user roles. The ExportMode property indicates whether, during an export, all the available property data on a control is exported, or only the non-sensitive data. This allows developers to distinguish between data that is sensitive and data that is not, for security purposes. The WebBrowsableObject property returns a reference to an instance of a WebPart control, so that an EditorPart control can edit it when the page is in edit mode. Finally, there are several properties that indicate the status of the control relative to the rest of the page. The IsClosed property indicates whether a control is closed (and thus added to a PageCatalogPart object), or if it is open and available on the page. The IsShared property indicates whether a control is a shared control (versus a user-specific control), meaning that it is visible to all users of a Web page. The IsStandalone property indicates whether a control is currently contained in a WebPartZoneBase-derived zone (such as WebPartZone). A value of false indicates the control is inside a zone and thus has full Web Parts functionality. The IsStatic property indicates whether a control is static or dynamic. A static control is declared in the markup of a Web page, whereas a dynamic control is added programmatically.

The WebPart class also provides several methods that determine what happens at various points in the control's life cycle. For example, the OnConnectModeChanged and OnEditModeChanged methods can both be overridden in a derived class to provide programmatic control over the rendering of a control's contents during the event that corresponds to each method's name.

Classes that derive from WebPart can add WebPartVerb objects to the Verbs collection. The verbs are rendered in a verbs menu, which appears in the title bar of a WebPart control. WebPartVerb objects provide simple UI elements for common user actions such as hiding or minimizing the control or displaying Help.

The CreateEditorParts method creates a collection of any custom EditorPart controls that are associated with a WebPart control. Developers can override this method so that it creates custom controls designed specifically to edit their WebPart control. The method is called when a user clicks the edit verb on a WebPart control.

The following code example demonstrates how to create a WebPart control and reference it in a Web page.

The first part of the example contains the code for a custom WebPart control named TextDisplayWebPart. This control demonstrates how to create a simple custom WebPart control that gives you access to the features of the Web Parts control set. 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 assumes that you compile the source code into an assembly, place it in a Bin subfolder of your Web application, and reference the assembly with a Register directive in your Web page. For a walkthrough that demonstrates both methods of compiling, see Walkthrough: Developing and Using a Custom Web Server Control.

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;

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

    [Personalizable(), 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)
      {
        _contentText = input.Text + @"<br />";
        input.Text = String.Empty;
        DisplayContent.Text = this.ContentText;
      }
    }
  }
}

The second part of the example shows how to reference the TextDisplayWebPart control in an ASP.NET Web page. Notice that many of the various WebPart properties can be assigned declaratively to the custom control.

<%@ 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"
      title="Zone 1"
      PartChromeType="TitleAndBorder">
        <parttitlestyle font-bold="true" ForeColor="#3300cc" />
        <partstyle
          borderwidth="1px"   
          borderstyle="Solid"  
          bordercolor="#81AAF2" />
        <zonetemplate>
          <aspSample:TextDisplayWebPart 
            runat="server"   
            id="textwebpart" 
            title = "Text Content WebPart" />
        </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