Working with Web Parts in Code

The controls used to generate portal pages are all ASP.NET server controls and become part of the control tree for the page when it is compiled and executed. So they can be accessed and manipulated using server-side code, and in some cases client-side code as well.

The three main classes described here are the WebPartManager , Web PartZone , and WebPart . Other classes are used to implement things like event handlers and the verbs that define the actions for each of the buttons on the title bar of a Web Part.

The WebPartManager Class

The WebPartManager is responsible for managing all the zones and Web Parts on the page. It exposes an interface that allows you to change the display mode, access and specify the behavior of zones and Web Parts, and react to events that occur within the page. The WebPartManager class is located in the System.Web.UI.WebControls namespace (as are the majority of classes used with Web Parts), and it is descended directly from Control .

The WebPartManager Constructor

There is a single constructor for the WebPartManager , which returns a new instance ready to add to the Controls collection of the Page (see Table 8.1).

The Properties of the WebPartManager Class

The WebPartManager class exposes all the interface members of the Control class. In addition, there are several properties that are specific to working with Web Parts. The ones you'll generally use are shown in Table 8.2 on the next page.

Table 8.1. The Constructor for the WebPartManager Class

Constructor	Description
WebPartManager()	Creates a new instance of the WebPartManager class with the default values for all its properties.

Table 8.2. The Properties of the WebPartManager Class

Property	Description
DisplayMode	Returns a value from the WebPartDisplayMode enumeration that indicates the display mode for the page. The display mode is set using the SetDisplayMode method.
Zones	Returns a reference to a WebPartZoneCollection that contains all the zones in the page.
WebParts	Returns a reference to a WebPartCollection that contains all the Web Parts for the page.
WebPartToEdit	Returns a reference to the WebPart instance that is currently being edited, or null if none are selected for editing.
EnablePersonalization	Sets or returns a Boolean value that indicates whether the properties of the zones and Web Parts can be set through the ASP.NET personalization system. The default is True .
PersonalizationType	Sets or returns a value from the ControlPersonalizationType enumeration that indicates the type of personalization to use. Valid values are AllPersonalizableProperties , Default , and None . See Chapter 7 for details of the ASP.NET 2.0 personalization features.
ConnectionPointManager	Returns a reference to a ConnectionPointManager instance for this page. This maintains details of all the connections between the Web Parts in the page.
Connections	Returns a reference to a ConnectionCollection instance that contains details of each connection between the Web Parts on the page.

The Methods of the WebPartManager Class

The WebPartManager class allows you to mirror the client-side user actions of adding, moving, and closing Web Parts by calling the methods directly. There are also methods to manage connection and one to change the display mode (see Table 8.3).

The Events of the WebPartManager Class

The WebPartManager class exposes six events that are specific to Web Parts and can be used to interact with the various actions taken by users, in some cases allowing you to prevent actions they take from being carried out (see Table 8.4 on the next page).

Table 8.3. The Methods of the WebPartManager Class

Method	Description
SetDisplayMode(mode)	Sets the display mode of the page using a value from the WebPartDisplayMode enumeration. Valid vales are Normal , Design , Catalog , and Edit . No return value.
GetWebPartsForZone(zone)	Takes a reference to a WebPartZone and returns a WebPartCollection that contains references to all of the Web Parts in the specified zone.
AddWebPart(part, zone, index)	Adds a Web Part to a zone given a reference to the WebPart to add, a reference to the WebPartZone to add it to, and an Integer that is the zero-based index of the position of the new Web Part within the target zone. No return value.
MoveWebPart(part, zone, index)	Moves a Web Part to another zone, or to another location within the same zone. Takes a reference to the WebPart to move, a reference to the WebPartZone to move it to, and an Integer that is the zero-based index of the new position of the Web Part within the target zone. No return value.
DeleteWebPart(part)	Removes the specified WebPart instance from the page. No return value.
BeginWebPartEditing(part)	Takes a reference to a WebPart instance, places it into Edit mode, and updates the WebPartToEdit property. No return value.
EndWebPartEditing()	Takes a reference to a WebPart instance, returns it from Edit mode to Normal mode, and sets the WebPartToEdit property to null . No return value.
CreateConnection(provider, consumer)	Creates a connection between the two specified ConnectionPoint instances. Returns a reference to the new Connection instance.
DeleteConnection (connection)	Deletes the specified Connection instance. No return value.

Table 8.4. The Events of the WebPartManager Class

Event	Description
DisplayModeChanging	Raised immediately before the current mode of the page changes. Passes an instance of a WebPartDisplayModeCancelEventArgs to the event handler, which has the following properties: Cancel : A Boolean value that can be set to True to prevent changes to the display mode. NewDisplayMode : A value from the WebPartDisplayMode enumeration that indicates the new display mode and can be changed to specify a different display mode.
DisplayModeChanged	Raised after the current mode of the page has changed. Passes an instance of a WebPartDisplayModeEventArgs to the event handler, which has the following property: OldDisplayMode : A value from the WebPartDisplayMode enumeration that indicates the previous display mode.
WebPartAdded	Raised after a Web Part has been added to the page. Passes an instance of a WebPartEventArgs to the event handler, which has the following property: WebPart : A reference to the Web Part that was added.
WebPartDeleted	Raised after a Web Part is closed or removed from the page. Passes an instance of a WebPartEventArgs to the event handler, which has the following property: WebPart : A reference to the Web Part that was closed or removed.
WebPartEditModeChanging	Raised immediately before an individual Web Part is placed into edit mode by clicking its Edit link or button. Passes an instance of a WebPartEditCancelEventArgs to the event handler, which has the following properties: Cancel : A Boolean value that can be set to True to prevent the Web Part from entering edit mode. WebPart : A reference to the Web Part that will change to edit mode.
WebPartEditModeChanged	Raised after an individual Web Part returns from edit mode. Passes an instance of a WebPartEditEventArgs to the event handler, which has the following property: WebPart : A reference to the Web Part that is in edit mode.

The WebPartZone Class

The WebPartZone class represents a zone within the page and is a member of the Zones collection of the current WebPartManager . It is descended from WebPartZoneBase , which in turn descends from Zone , which is itself descended from WebControl . So WebPartZone exposes all the members of these base classes as well as some that it adds itself. The tables in this subsection summarize all the interface members that are relevant to working with Web Parts.

The WebPartZone Constructor

There is a single constructor for the WebPartZone class, creating a new WebPartZone that can be added to the Zones collection of the WebPart Manager (see Table 8.5).

The Behavior Properties of the WebPartZone Class

The WebPartZone has many properties, and to make it easier to see those that are relevant to this chapter, they are divided into three sections: behavior properties, appearance properties, and style properties. Table 8.6 on the next page summarizes the behavior properties.

Table 8.5. The Constructor for the WebPartZone Class

Constructor	Description
WebPartZone()	Creates a new instance of a WebPartZone with the default values for all its properties.

Table 8.6. The Behavior Properties of the WebPartZone Class

Property	Description
AllowLayoutChange	Sets or returns a Boolean value that indicates whether the Web Parts in this zone can be moved to another zone or to another position within this zone. The default is True .
DragMode	Sets or returns a value from the DragMode enumeration that indicates the appearance of the Web Parts in this zone when they are dragged to a new position in design or edit mode. Valid values are Normal (the default), Image (as defined by the DragImageUrl property), and WebPartTitle (just the title bar).
DragHighlightColor	Sets or returns a Color instance that specifies the color of the "target block" that will receive the Web Part. This "block" appears when a Web Part is dragged to another position, indicating the actual location it will take if dropped at that point.
DragImageUrl	Sets or returns a String that is the URL of an image to use when dragging a Web Part to a new position in design or edit mode. The DragMode property must be set to DragMode.Image .
Orientation	Sets or returns a value from the Orientation enumeration that indicates how the Web Parts in this zone will be laid out. Valid values are Horizontal and Vertical .
WebPartCloseVerb	Returns a reference to a WebPartVerb instance that describes the command verb that will be used to create the Close link or button for the Web Parts in this zone. Read-only. The WebPartVerb class is described in Table 8.7.
WebPartEditVerb	Returns a reference to a WebPartVerb instance that describes the command verb that will be used to create the Edit link or button for the Web Parts in this zone. Read-only.
WebPartHelpVerb	Returns a reference to a WebPartVerb instance that describes the command verb that will be used to create the Help link or button for the Web Parts in this zone. Read-only.
WebPartMinimizeVerb	Returns a reference to a WebPartVerb instance that describes the command verb that will be used to create the Minimize link or button for the Web Parts in this zone. Read-only.
WebPartRestoreVerb	Returns a reference to a WebPartVerb instance that describes the command verb that will be used to create the Restore link or button for the Web Parts in this zone. Read-only.
VerbButtonType	Sets or returns a value from the ButtonType enumeration that indicates how the command verbs for the Web Parts in this zone will appear in their title bars. Valid values are Link (the default), Button , and Image .
ZoneTemplate	Sets or returns a reference to an ITemplate class that represents the ZoneTemplate section of the declaration of this zone.
Enabled	Sets or returns a Boolean value that indicates whether all of the Web Parts within this zone are enabled. The default is True .

The WebPartVerb Class

The WebPart xxx Verb properties shown in Table 8.6 contain a reference to a WebPartVerb class, which defines the appearance and behavior of the command links or buttons in the title bar of each Web Part. Table 8.7 shows the properties of the WebPartVerb class.

Table 8.7. The Properties of the WebPartVerb Class

Property	Description
Text	Sets or returns a String value that is the name of the command verb, such as Edit.
Description	Sets or returns a String that is displayed as a tooltip or long description of the command, such as Closes the Web Part.
ImageUrl	Sets or returns a String that is the URL of the image to display for this command in the title bar of the Web Part when command links are shown as images.
Visible	Sets or returns a Boolean value that indicates whether this command link is displayed.
Enabled	Sets or returns a Boolean value that indicates whether the command is available.
Checked	Sets or returns a Boolean value that indicates whether a "tick" should appear in a menu containing this verb.
ServerClickHandler	Returns a reference to the WebPartEventHandler that will be executed when the command is carried out. Read-only.
ClientClickHandler	Returns a String value that is the name of the client-side function, or the client-side script code, that runs when the user executes the command. Read-only.

The Appearance Properties of the WebPartZone Class

Many of the properties of a WebPartZone are the same as those you use with any other ASP.NET server control. For example, you can set and retrieve the values for the BackColor , ForeColor , BorderColor , BorderWidth , and BorderStyle ; specify the URL of an image for the background of the zone as the BackImageUrl property; and specify CSS styles directly in the CssClass property. Table 8.8 summarizes other properties that specify the appearance of Web Parts and are more directly applicable to this technology.

Table 8.8. The Appearance Properties of the WebPartZone Class

Property	Description
Title	Sets or returns a String that is the text to display at the top of the zone when the page is in catalog, design, or edit mode.
EmptyZoneText	A String that is the text to display within the zone when it contains no Web Parts.
ShowIconInPartTitle	Sets or returns a Boolean value that indicates whether the image specified in the SmallIconImageUrl property of the Web Parts in this zone will be displayed at the left end of the title bars.
TitleHorizontalAlign	Sets or returns a value from the HorizontalAlign enumeration that indicates the alignment of the text within the zone when the page is in catalog, design, or edit mode. Valid values are Left , Right , Center , Justify , and NotSet .
Font	A reference to a FontInfo class that specifies the font type and style for the text displayed by the Title property.
Width	Sets or returns the width of the zone as a Unit value.
Height	Sets or returns the height of the zone as a Unit value.
WebPartPadding	Sets or returns an Integer that is the number of pixels of space between Web Parts within this zone.
EnablePersonalization	Sets or returns a Boolean value that indicates whether the properties of the Web Parts in this zone can be set through the ASP.NET personalization system. The default is True .
PersonalizationType	Sets or returns a value from the ControlPersonalizationType enumeration that indicates the type of personalization to use. Valid values are AllPersonalizableProperties , Default , and None . See Chapter 7 for details of the ASP.NET 2.0 personalization features.
ToolTip	Sets or returns a String that is displayed as a pop-up tooltip for the zone.
Visible	Sets or returns a Boolean value that indicates whether the zone and its content will be visible. The default is True . When False , the zone and its constituent controls still appear in the control tree of the page.
PartFrameType	Sets or returns a value from the PartFrameType enumeration that specifies the type of frame to display around the constituent Web Parts of this zone, unless they override the value individually. Valid values are TitleAndBorder , TitleOnly , BorderOnly , None , and Default .
PartTitleFormatString	Sets or returns a String that indicates how the Title and Caption property values of each Web Part are combined in the title bar. The default is {0}-{1} , indicating that they are separated by a hyphen.
PartTitleHorizontalAlign	Sets or returns a value from the HorizontalAlign enumeration that indicates how the title text of the constituent Web Parts is aligned. Valid values are Left , Right , Center , Justify , and NotSet .

The Style Properties of the WebPartZone Class

The final set of properties for the WebPartZone class that affect the Web Parts in a zone are those that use a standard ASP.NET Style class to specify the appearance of specific sections of each Web Part. The applicable properties are shown in Table 8.9.

Table 8.9. The Style Properties of the WebPartZone Class

Property	Description
TitleStyle	A reference to a Style instance that specifies the style and appearance of the text that appears at the top of the zone when the page is in catalog, design, or edit mode.
PartStyle	A reference to a Style instance that specifies the style and appearance of all the Web Parts in this zone unless overridden at Web Part level.
PartContentStyle	A reference to a Style instance that specifies the style and appearance of the content within all the Web Parts in this zone unless overridden at Web Part level.
PartTitleStyle	A reference to a Style instance that specifies the style and appearance of the title bar for all the Web Parts in this zone unless overridden at Web Part level.
PartVerbStyle	A reference to a Style instance that specifies the style and appearance of the links in the title bar for all the Web Parts in this zone unless overridden at Web Part level.
FooterStyle	A reference to a Style instance that specifies the style and appearance of any footer sections in the Web Parts in this zone unless overridden at Web Part level.
EditWebPartStyle	A reference to a Style instance that specifies the style and appearance of the Web Part in this zone that is currently being edited unless overridden at Web Part level.
EmptyZoneTextStyle	A reference to a Style instance that specifies the style and appearance of the text that appears within the zone when it contains no Web Parts.

The Events of the WebPartZone Class

The WebPartZone class exposes a single event that is directly relevant to Web Parts (see Table 8.10).

Table 8.10. The Event of the WebPartZone Class

Event	Description
CreateVerbs	Raised when the zone creates the links for the title bars of each Web Part. Passes an instance of a WebPartVerbsEventArgs to the event handler, which exposes a WebPartVerbCollection instance that contains all the verbs for the Web Part.

The WebPart Class

The WebPart class represents an individual Web Part on the page and is a member of the WebParts collection of the WebPartZone that contains this Web Part. The WebPart class is descended from Part , which itself descends from Panel (all of these reside in the System.Web.UI.WebControls namespace).

Many of the properties of the WebPart class are inherited from Panel , as this is effectively how a Web Part is represented in the markup that is generated and sent to the client. However, a number of properties are specific to Web Parts, and for clarity these have again been divided into sections: behavior properties and appearance properties.

The Behavior Properties of the WebPart Class

The WebPart class exposes several properties that specify what actions a user can take with this Web Part, plus a set of properties that define the content of various sections of the Web Part (in particular the items that will appear in the title bar). There are also properties that indicate the location of the Web Part within the page and allow it to be moved (see Table 8.11).

Table 8.11. The Behavior Properties of the WebPart Class

Property	Description
AllowMinimize	Sets or returns a Boolean value that indicates whether the Web Part can be minimized or "rolled up" so that only the title bar is displayed. The default is True .
AllowClose	Sets or returns a Boolean value that indicates whether the Web Part can be closed (i.e., removed from a zone). The default is True .
AllowHide	Sets or returns a Boolean value that indicates whether the Web Part can be hidden using the controls in an EditZone , so that it still remains in the zone but is not visible. The default is True .
AllowZoneChange	Sets or returns a Boolean value that indicates whether the Web Part can be moved to another zone when the page is in design or edit mode. The default is True .
AllowPersonalize	Sets or returns a Boolean value that indicates whether the properties of the Web Part can be set through the ASP.NET personalization system. The default is True .
AllowExport	Sets or returns a Boolean value that indicates whether the properties of the Web Part can be exported. The default is True .
AllowPaginate	Sets or returns a Boolean value that indicates whether the content of the Web Part can be paginated using a Pager control. See Chapter 10 for details of the paging mechanism in ASP.NET 2.0.
ConnectionPoints	Returns a reference to a ConnectionPointCollection that contains the connection points for this Web Part. Each ConnectionPoint instance in the collection defines how the Web Part connects to another Web Part and whether it is a provider or consumer. Read-only.
TitleUrl	Sets or returns a String that is the URL of a page containing more information about the Web Part. When set, a link appears in the title bar of the Web Part.
HelpMode	Sets or returns a value from the WebPartHelpMode enumeration that indicates how the Help window will be displayed. Valid values are Modal (the defaulthelp content is displayed in a modal window if the client supports this feature or in a separate pop-up window if not), Modeless (help content is displayed in a separate pop-up window), and Navigate (the current browser instance navigates directly to the help page).
HelpUrl	Sets or returns a String that is the URL of the help page to display for this Web Part when the Help icon or link on the title bar is clicked.
EditUrl	Sets or returns a String that is the URL of a page that can be used to edit any custom properties of this Web Part. Allows control-specific editing actions to be defined instead of using the default editing process provided by an EditZone .
IsShared	Returns a Boolean value that indicates whether this Web Part is shared between multiple users or is available only to the current user.
Roles	Sets or returns a String array that is the list of roles to which the Web Part is available. The roles are defined by the ASP.NET personalization configuration. When not specified ( null ), any user can load the Web Part. A comma-delimited list of roles can be specified for the Roles attribute when declaring a Web Part.
Verbs	Returns a reference to a WebPartVerbCollection that contains the verbs or commands that the user can execute for this Web Part, such as Minimize, Edit, Close, and Help.
Zone	Returns a reference to the zone containing this Web Part as a WebPartZone instance. Read-only.
ZoneID	Sets or returns a String that is the ID of the zone containing this Web Part. Setting this property moves the Web Part to the specified zone.
ZoneIndex	Sets or returns an Integer value that is the zero-based index of the Web Part within the current zone. Setting this property moves the Web Part to the specified position within the zone.

The Appearance Properties of the WebPart Class

The WebPart class exposes many of the same appearance properties as the WebPartZone class, for example, Style , CssClass , BorderWidth , BackColor , TitleStyle , Height , Width , Enabled , EnablePersonalization , and so on. There are also several other appearance properties relevant only to Web Parts (see Table 8.12).

Table 8.12. The Appearance Properties of the WebPart Class

Property	Description
Title	Sets or returns a String value that is the text to display in a catalog, as a tooltip, and in the title bar of the Web Part.
Caption	Sets or returns a String that is added to the end of the title bar text. Intended to be a dynamic value that is used to display instance-specific details for Web Parts that are used more than once on a page, for example, a document name.
SmallIconImageUrl	Sets or returns a String that is the URL of the image to display at the left end of the title bar for the Web Part.
LargeIconImageUrl	Sets or returns a String that is the URL of the image to display when representing the Web Part, for example, in a gallery of available Web Parts.
FrameType	Sets or returns a value from the PartFrameType enumeration that specifies the type of frame to display around the Web Part. Valid values are TitleAndBorder , TitleOnly , BorderOnly , None , and Default .
FrameState	Sets or returns a value from the PartFrameState enumeration that specifies the way the Web Part will be displayed. Valid values are Normal (the default) and Minimized .
Direction	Sets or returns a value from the ContentDirection enumeration that specifies the text layout direction for the Web Part content. Valid values are LeftToRight (the default), RightToLeft , and NotSet .
ScrollBars	Sets or returns a value from the ScrollBars enumeration that indicates whether the Web Part will display scroll bars when the size of the content exceeds the available space (the Height and/or Width properties must be set to force this to occur). Valid values are Auto (the default), Both , Horizontal , Vertical , and None .
Wrap	Sets or returns a Boolean value that indicates whether the text and markup content of the Web Part will wrap when the line length exceeds the width of the Web Part. The default is True .
Hidden	Sets or returns a Boolean value that indicates whether the user has hidden the Web Part using the options in the EditZone . When hidden it remains within the current zone but is not displayed. The default is False .
Visible	Sets or returns a Boolean value that indicates whether the Web Part is displayed. It remains as part of the control tree when not displayed. The default is True .
MissingAssembly	Sets or returns a String that is the text to display in the Web Part content area if the user attempts to add a Web Part that is implemented as an assembly and that assembly cannot be found.