WebPartManager.CloseWebPart(WebPart) Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Closes a WebPart control in such a way that it is not rendered on a Web page, but can be reopened.
public:
void CloseWebPart(System::Web::UI::WebControls::WebParts::WebPart ^ webPart);public void CloseWebPart (System.Web.UI.WebControls.WebParts.WebPart webPart);member this.CloseWebPart : System.Web.UI.WebControls.WebParts.WebPart -> unitPublic Sub CloseWebPart (webPart As WebPart)Parameters
- webPart
- WebPart
A WebPart or server control that is being closed in a WebPartZoneBase.
Exceptions
webPart is null.
webPart is not in the Controls collection.
-or-
webPart is a shared control and has already been closed by another user.
Examples
The following code example demonstrates how to use the CloseWebPart method.
The code example has four parts:
A user control that enables you to change page display modes.
A custom WebPart control.
A Web page.
An explanation of how the example works in a browser.
The first part of the code example is the user control for changing display modes. You can obtain the source code for the user control from the Example section of the WebPartManager class overview. For more information about display modes and how the user control works, see Walkthrough: Changing Display Modes on a Web Parts Page.
The second part of the code example is the custom WebPart control. 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 example uses the dynamic compilation approach; thus there is no Assembly attribute in the Register directive for this control at the top of the Web page. For a walkthrough that demonstrates how to compile, see Walkthrough: Developing and Using a Custom Web Server Control.
using System;
using System.Collections;
using System.ComponentModel;
using System.Drawing;
using System.Security.Permissions;
using System.Web;
using System.Web.UI;
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;
Literal lineBreak;
[Personalizable(), WebBrowsable]
public String ContentText
{
get { return _contentText; }
set { _contentText = value; }
}
protected override void CreateChildControls()
{
Controls.Clear();
DisplayContent = new Label();
DisplayContent.BackColor = Color.LightBlue;
DisplayContent.Text = this.ContentText;
this.Controls.Add(DisplayContent);
lineBreak = new Literal();
lineBreak.Text = @"<br />";
Controls.Add(lineBreak);
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);
}
private void submit_Click(object sender, EventArgs e)
{
// Update the label string.
if (!string.IsNullOrEmpty(input.Text))
{
_contentText = input.Text + @"<br />";
input.Text = String.Empty;
DisplayContent.Text = this.ContentText;
}
}
}
}
Imports System.Collections
Imports System.ComponentModel
Imports System.Drawing
Imports System.Security.Permissions
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls
Imports System.Web.UI.WebControls.WebParts
Namespace Samples.AspNet.VB.Controls
<AspNetHostingPermission(SecurityAction.Demand, _
Level:=AspNetHostingPermissionLevel.Minimal)> _
<AspNetHostingPermission(SecurityAction.InheritanceDemand, _
Level:=AspNetHostingPermissionLevel.Minimal)> _
Public Class TextDisplayWebPart
Inherits WebPart
Private _contentText As String = Nothing
Private _fontStyle As String = Nothing
Private input As TextBox
Private DisplayContent As Label
Private lineBreak As Literal
<Personalizable(), WebBrowsable()> _
Public Property ContentText() As String
Get
Return _contentText
End Get
Set(ByVal value As String)
_contentText = value
End Set
End Property
Protected Overrides Sub CreateChildControls()
Controls.Clear()
DisplayContent = New Label()
DisplayContent.BackColor = Color.LightBlue
DisplayContent.Text = Me.ContentText
Me.Controls.Add(DisplayContent)
lineBreak = New Literal()
lineBreak.Text = "<br />"
Controls.Add(lineBreak)
input = New TextBox()
Me.Controls.Add(input)
Dim update As New Button()
update.Text = "Set Label Content"
AddHandler update.Click, AddressOf Me.submit_Click
Me.Controls.Add(update)
End Sub
Private Sub submit_Click(ByVal sender As Object, _
ByVal e As EventArgs)
' Update the label string.
If input.Text <> String.Empty Then
_contentText = input.Text + "<br />"
input.Text = String.Empty
DisplayContent.Text = Me.ContentText
End If
End Sub
End Class
End Namespace
The third part of the code example is the Web page. The page contains a CatalogZone zone, with an <asp:pagecatalogpart> element declared within it. This is what will contain the closed WebPart control and enable users to add it back to the page. The Button1_Click method directly calls the CloseWebPart method to close the custom WebPart control, although a user can also close the control through the verbs menu.
<%@ Page Language="C#" %>
<%@ Register TagPrefix="uc1"
TagName="DisplayModeMenuCS"
Src="~/DisplayModeMenuCS.ascx" %>
<%@ Register TagPrefix="aspSample"
Namespace="Samples.AspNet.CS.Controls"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">
protected void Button1_Click(object sender, EventArgs e)
{
mgr1.CloseWebPart(text1);
}
</script>
<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
<title>Untitled Page</title>
</head>
<body>
<form id="form1" runat="server">
<asp:WebPartManager ID="mgr1" runat="server" />
<uc1:DisplayModeMenuCS ID="menu1" runat="server" />
<asp:WebPartZone ID="WebPartZone1" runat="server">
<ZoneTemplate>
<aspSample:TextDisplayWebPart ID="text1"
runat="server"
Title="My Text WebPart" />
</ZoneTemplate>
</asp:WebPartZone>
<asp:CatalogZone ID="CatalogZone1" runat="server">
<ZoneTemplate>
<asp:PageCatalogPart ID="PageCatalogPart1" runat="server" />
</ZoneTemplate>
</asp:CatalogZone>
<asp:Button ID="Button1" runat="server"
Text="Close WebPart"
OnClick="Button1_Click" />
</form>
</body>
</html>
<%@ Page Language="vb" %>
<%@ Register TagPrefix="uc1"
TagName="DisplayModeMenuVB"
Src="~/DisplayModeMenuVB.ascx" %>
<%@ Register TagPrefix="aspSample"
Namespace="Samples.AspNet.VB.Controls"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">
Protected Sub Button1_Click(ByVal sender As Object, _
ByVal e As System.EventArgs)
mgr1.CloseWebPart(text1)
End Sub
</script>
<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
<title>Untitled Page</title>
</head>
<body>
<form id="form1" runat="server">
<asp:WebPartManager ID="mgr1" runat="server" />
<uc1:DisplayModeMenuVB ID="menu1" runat="server" />
<asp:WebPartZone ID="WebPartZone1" runat="server">
<ZoneTemplate>
<aspSample:TextDisplayWebPart ID="text1"
runat="server"
Title="My Text WebPart" />
</ZoneTemplate>
</asp:WebPartZone>
<asp:CatalogZone ID="CatalogZone1" runat="server">
<ZoneTemplate>
<asp:PageCatalogPart ID="PageCatalogPart1" runat="server" />
</ZoneTemplate>
</asp:CatalogZone>
<asp:Button ID="Button1" runat="server"
Text="Close WebPart"
OnClick="Button1_Click" />
</form>
</body>
</html>
After you load the page in a browser, close the custom WebPart control by clicking the verbs menu (the arrow symbol) in the header of the control, and clicking Close. Now change the page to catalog mode by selecting Catalog in the Display Mode drop-down list control. The page catalog appears with the closed control. Select the check box next to the closed control, click Add to add it to the page, and then click Close to return the page to browse mode. The control is restored to the page. Now close it again, this time by clicking the Close WebPart button.
Remarks
The CloseWebPart method removes a WebPart or other server control so that it is not rendered on the Web page that originally contained it. The closed control is added to a PageCatalogPart object, which maintains a reference to the closed control and makes it possible for the control to be restored to the page. A closed WebPart control still appears in the collection referenced by the WebParts property.
Closing a control is different from deleting it. Closed controls are still available to be restored to a page, but a deleted control instance is permanently removed and can never be restored. Regardless of whether a WebPart or server control is static (declared in the markup of a page) or dynamic (added to the page programmatically or by a user from a Web Parts catalog), it can be closed and reopened on a page.
Typically, users can close a WebPart control by clicking its verbs menu and selecting the close verb. A control can also be closed by directly calling the CloseWebPart method and passing it a reference to webPart.
On a page where WebPart controls have been closed, if a developer declares an <asp:catalogzone> element, and within it adds an <asp:pagecatalogpart> element, it provides a simple user interface (UI) for users to restore closed controls to the page at run time. Users can switch the page into catalog display mode, and the closed controls will appear within the page catalog. Users can select closed controls and add them back to the page at whatever position they desire, and then the selected controls are restored to the page and rendered as normal.
When the CloseWebPart method is called, it raises several events: WebPartClosing, SelectedWebPartChanging (if there are multiple controls), and WebPartsDisconnecting (if there are connected controls). Normally developers can cancel these events, but in certain cases it is not possible to cancel them. For details, see the documentation for the WebPartClosing, SelectedWebPartChanging, and WebPartsDisconnecting events.
