Export (0) Print
Expand All

IWebPart Interface

Defines common user interface (UI) properties used by ASP.NET WebPart controls.

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

public interface IWebPart

The IWebPart type exposes the following members.

  NameDescription
Public propertyCatalogIconImageUrlGets or sets the URL to an image that represents a WebPart control in a catalog of controls.
Public propertyDescriptionGets or sets a brief phrase that summarizes what a control does, for use in ToolTips and catalogs of WebPart controls.
Public propertySubtitleGets a string that is concatenated with the Title property value to form a complete title for a WebPart control.
Public propertyTitleGets or sets the title of a WebPart control.
Public propertyTitleIconImageUrlGets or sets the URL to an image used to represent a Web Parts control in the control's own title bar.
Public propertyTitleUrlGets or sets a URL to supplemental information about a WebPart control.
Top

The IWebPart interface provides several UI-oriented properties that enhance the user experience of working with WebPart controls. When you create controls that derive from the base WebPart class, you get an implementation of all the properties in the IWebPart interface, because the WebPart base class implements this interface.

You can use existing user controls, ASP.NET controls, or custom server controls that do not inherit from the WebPart class as part of a Web Parts application, and they can also use these UI-oriented properties declared by the IWebPart interface. If you place existing server controls in a WebPartZoneBase zone, at run time they are wrapped with a GenericWebPart object. Because the GenericWebPart class inherits from the WebPart base class, it enables existing server controls to act as true WebPart controls and it adds to them the properties of the IWebPart interface.

If you place server controls that are not WebPart controls in zones, they can use the IWebPart properties at run time, and you can also declare values for those properties on server controls in the markup of the page (in page persistence format). However, because these properties are only available to the server controls at run time, design-time coding features such as IntelliSense do not recognize IWebPart properties that are declared on server controls. Declared properties on these controls still work when you load the page, but Microsoft Visual Studio does not recognize the properties as valid at design time. If you want to add the IWebPart properties to existing server and user controls to enhance the design-time user experience, you can implement the IWebPart interface in a server control.

Perhaps the main reason to implement the IWebPart interface is for controls that do not support the use of expando (custom) properties. Expando properties are strings that can be added to a class dynamically as a property, by means of the IAttributeAccessor interface. Controls that implement this interface, including the WebControl class and its children, can use expando properties. Therefore, all ASP.NET server controls, custom controls that derive from them, Web user controls, and WebPart controls support the use of expando properties. But custom controls that inherit directly from the base Control class do not support expando properties. Thus, if you declare these controls within a WebPartZone, you will not be able to declare the common IWebPart properties on the controls, properties such as Title and Description. If you want to use these properties with such controls, you must implement the IWebPart interface.

Notes to Implementers

Normally you do not need to implement the IWebPart interface, either on custom WebPart controls or server controls, because the base WebPart class already implements the interface. Custom WebPart controls, and other server controls that are placed in WebPartZoneBase zones, can use all the IWebPart properties.

The main reason to implement the IWebPart interface yourself, whether in a custom WebPart control or another server control, is if you want to change the default implementation. For example, you might want to provide default values for some of the properties. Another reason to implement the interface in a user or server control is so that the design-time experience of working with these properties on the control will be enhanced.

The following code example demonstrates how to implement the IWebPart interface in a user control. This is a simple implementation that shows minimally how to implement the properties.

The first part of the code example shows the user control. The user control implements all the properties of the IWebPart interface, plus two additional public properties tied to controls in the user interface. The two custom properties each use the Personalizable attribute, which enables the values in those properties to be saved across browser sessions. Note that in the base WebPart class implementation, all the properties of the IWebPart interface are implemented as personalizable as well, though they are not in this code example.

<%@ control language="C#" classname="AccountUserControlCS"%>
<%@ implements interface="System.Web.UI.WebControls.WebParts.IWebPart" %>

<script runat="server">

  private string m_Description;
  private string m_Title;
  private string m_TitleIconImageUrl;
  private string m_TitleUrl;
  private string m_CatalogIconImageUrl;

  [Personalizable]
  public string UserName
  {
    get
    {
      if(String.IsNullOrEmpty(Textbox1.Text))
        return String.Empty;
      else
        return Textbox1.Text;
    }

    set
    {
      Textbox1.Text = value;
    }
  }

  [Personalizable]
  public string Phone
  {
    get
    {
      if(String.IsNullOrEmpty(Textbox2.Text))
        return String.Empty;
      else
        return Textbox2.Text;
    }

    set
    {
      Textbox2.Text = value;
    }
  }

  public string Description
  {
    get
    {
      object objTitle = ViewState["Description"];
      if (objTitle == null)
        return String.Empty;

      return (string)objTitle;
    }
    set
    {
      ViewState["Description"] = value;
    }
  }

  public string Title
  {
    get
    {
      object objTitle = ViewState["Title"];
      if (objTitle == null)
        return String.Empty;

      return (string)objTitle;
    }
    set
    {
      ViewState["Title"] = value;
    }
  }

  public string Subtitle
  {
    get
    {
      object objSubTitle = ViewState["Subtitle"];
      if (objSubTitle == null)
        return "My Subtitle";

      return (string)objSubTitle;
    }

  }

  public string TitleIconImageUrl
  {
    get
    {
      object objTitle = ViewState["TitleIconImageUrl"];
      if (objTitle == null)
        return String.Empty;

      return (string)objTitle;
    }
    set
    {
      ViewState["TitleIconImageUrl"] = value;
    }
  }

  public string TitleUrl
  {
    get
    {
      object objTitle = ViewState["TitleUrl"];
      if (objTitle == null)
        return String.Empty;

      return (string)objTitle;
    }
    set
    {
      ViewState["TitleUrl"] = value;
    }
  }

  public string CatalogIconImageUrl
  {
    get
    {
      object objTitle = ViewState["CatalogIconImageUrl"];
      if (objTitle == null)
        return String.Empty;

      return (string)objTitle;
    }
    set
    {
      ViewState["CatalogIconImageUrl"] = value;
    }
  }

  // Update the selected IWebPart property value.
  void Button1_Click(object sender, EventArgs e)
  {
    String propertyValue = Server.HtmlEncode(TextBox3.Text);
    TextBox3.Text = String.Empty;

    switch (RadioButtonList1.SelectedValue)
    {
      case "title":
        this.Title = propertyValue;
        break;
      case "description":
        this.Description = propertyValue;
        break;
      case "catalogiconimageurl":
        this.CatalogIconImageUrl = propertyValue;
        break;
      case "titleiconimageurl":
        this.TitleIconImageUrl = propertyValue;
        break;
      case "titleurl":
        this.TitleUrl = propertyValue;
        break;
      default:
        break;
    }
  }

</script>
<div>
<asp:label id="Label1" runat="server" AssociatedControlID="Textbox1">
  Name</asp:label>
<asp:textbox id="Textbox1" runat="server" />
</div>
<div>
<asp:label id="Label2" runat="server" AssociatedControlID="Textbox2">
  Phone</asp:label>
<asp:textbox id="Textbox2" runat="server"></asp:textbox>
</div>
<div>
<asp:button id="Button2" runat="server" text="Save Form Values" />
</div>
<hr />
<asp:Label ID="Label3" Runat="server" Text="Label" 
  AssociatedControlID="RadioButtonList1">
  <h3>Update selected IWebPart property values.</h3>
</asp:Label>
<asp:RadioButtonList ID="RadioButtonList1" Runat="server">
  <asp:ListItem Value="title">Title</asp:ListItem>
  <asp:ListItem Value="description">Description</asp:ListItem>
  <asp:ListItem Value="catalogiconimageurl">CatalogIconImageUrl</asp:ListItem>
  <asp:ListItem Value="titleiconimageurl">TitleIconImageUrl</asp:ListItem>
  <asp:ListItem Value="titleurl">TitleUrl</asp:ListItem>
</asp:RadioButtonList>
<br />
<asp:Label ID="Label4" runat="server" Text="Label"
  AssociatedControlID="TextBox3">
Property Value:  
</asp:Label>
<asp:TextBox ID="TextBox3" runat="server">
</asp:TextBox>  
<br />  
<asp:Button ID="Button1" runat="server" 
  Text="Update Property" 
  OnClick="Button1_Click">
</asp:Button>

The second part of the code example shows the Web page that hosts the user control. The page has a WebPartZone control, within which the user control is referenced. Notice that several of the IWebPart interface's property values are set declaratively in the markup for the user control, which enables it to both behave and appear similar to a WebPart control at design time and run time. If you load the page in a browser, you can use the UI on the page to demonstrate the ability to programmatically change the values of the implemented IWebPart properties at run time. When you change some of the property values, the changes are not evident on the page, but are visible in the page source (the TitleIconImageUrl property), or are stored in the application's state data (the CatalogIconImageUrl property).

Security noteSecurity Note

This example has a text box that accepts user input, which is a potential security threat. By default, ASP.NET Web pages validate that user input does not include script or HTML elements. For more information, see Script Exploits Overview.

<%@ page language="c#" %>
<%@ register tagprefix="uc1" 
    tagname="AccountUserControlCS" 
    src="AccountUserControlcs.ascx"%>
<!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 runat="server">
    <title>
      Personalizable User Control with IWebPart Properties
    </title>
  </head>
  <body>
    <form id="form1" runat="server">
      <asp:webpartmanager id="WebPartManager1" runat="server" />
      <asp:webpartzone 
        id="zone1" 
        runat="server" 
        headertext="Main" 
        CloseVerb-Enabled="false">
        <zonetemplate>
          <uc1:AccountUserControlCS 
            runat="server" 
            id="accountwebpart" 
            title="Account Form"
            Description="Account Form with default values."
            CatalogIconImageUrl="MyCatalogIcon.gif"
            TitleIconImageUrl="MyTitleIcon.gif"
            TitleUrl="MyUrl.html"/>
        </zonetemplate>
      </asp:webpartzone>    
    </form>
  </body>
</html>

.NET Framework

Supported in: 4.6, 4.5, 4, 3.5, 3.0, 2.0

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

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

Show:
© 2014 Microsoft