Section 9.1. Understanding Web Parts

9.1. Understanding Web Parts

Web parts are based on ASP.NET web controls. In fact, the WebPart class inherits from System.Web.UI.Control . That means most of the programming issues of composition, lifetime, state, and server versus client-side processing are the same. In case you're not familiar with those concepts, here's a brief synopsis:

Composition

Web parts are made up of other componentsmainly ASP.NET web controls, HTML controls, literal strings, and client-side scripts. Components are assembled in a Controls collection and then rendered into HTML that is sent back to the client.

Lifetime

A web part instance is created on the server in response to a request from a client. That instance runs code, responds to events, renders the response, and then is destroyed soon after the response is sent back to the client. The next request creates a new instance which is in turn destroyed, and so on.

State

The properties of web controls are preserved beyond this lifetime by means of a built-in ViewState object. ViewState saves settings by means of hidden HTML controls rendered with the web part. The web part loads these values shortly after it is initialized with LoadViewState and saves any changes back just before it is rendered using SaveViewState .

Server/Client Code

The web part class runs on the server and that code only executes when the page is posted back to the server by means of a command button or some other postback control. You can also include JavaScript that runs on the clientthose scripts respond to events on the web part without returning to the server. That is more efficient and improves performance in many cases.

Figure 9-1 illustrates these concepts in terms of the life cycle of a web part on the server and how that is presented on the client.

animal 9-1. Key events in the life cycle of a web part

9.1.1. Extending ASP.NET

The previous section described high-level concepts that are constant for web parts and ASP.NET custom controls, but web parts extend the ASP.NET Control class to allow members to modify, save, and connect web part properties, as described here:

Modify

Members can set properties of web parts by choosing Modify Shared Web Part or Modify My Web Part from the web part menu and then entering their changes on the properties task pane.

Save

Web part properties can be saved to the content database. That allows members to modify the personal or shared view of a page and have those changes persist the next time they view the page.

Connect

Members can connect a property from one web part to a property on another web part. This creates a Lego-block type approach to building web part pages.

The SharePoint documentation calls web parts designable that is, authorized members can change their appearance and function from within the browser as shown in Figure 9-2.

animal 9-2. Designing a web part in the browser

Under ASP.NET those changes can be made only by editing a control's HTML, and there is no built-in way to save settings or connect parts. The SharePoint WebPart and WebPartZone classes provide the infrastructure for those features.

9.1.2. Using Web Parts

That said, not all web parts are designable. The navigation bar and Quick Launch areas on the default SharePoint home pages are examples of nondesignable NavBar web parts. Whether or not a web part is designable depends on where it is placed on a page:

• Web parts inside web part zones are designable and can be changed by members. The SharePoint documentation calls these dynamic web parts .

• Web parts outside of web part zones can't be modified by members. SharePoint calls these static web parts .

In Chapter 8, I showed you how to import dynamic web parts into a web part zone on a page. To add a static web part, edit the . aspx page in FrontPage to register the web part assembly and include an element for the web part. For example, the following line registers sample assembly used throughout this chapter:

 <%@ Register TagPrefix="Ch09" Namespace="Ch09Samples" Assembly="Ch09Samples,      Version=1.0.0.0, Culture=neutral, PublicKeyToken=fb6919fe58e4ba63" %> 

All the attributes of the @ Register directive match those defined for the web parts in the SafeControl element in Web.config , with the exception of TagPrefix . The TagPrefix attribute defines the prefix you'll use to qualify the web part element on the page. For example, the following element adds Webpart1 to the page:

 <ch09:WebPart1 text="New text property setting." title="WebPart1">      </ch09:WebPart1> 

Properties of the web part are included as attributes in the element. In this case, the text attribute sets the Text custom property and the title attribute sets the web part's built-in Title property. Figure 9-3 shows the result.

animal 9-3. Setting a static web part's properties

In this context, the terms static and dynamic are misleading. Nondesignable (static) web parts can accept entries and display results dynamically the same way that designable parts can (Figure 9-4).

animal 9-4. Is this interactive part static or dynamic?

See the StaticParts.aspx sample for examples of including web parts outside of web part zones.

9.1.3. Programming Tasks

In ASP.NET you can create three types of custom controls: user controls, composite controls, and rendered controls. Because SharePoint doesn't directly support user controls (. ascx ), all web parts are either made up of other web controls (composite controls) or rendered directly as HTML (rendered controls). In most cases, web parts use a combination of the two techniques, so that's what I show in my examples.

Table 9-1 summarizes the major tasks I cover in this chapter and provides a guide to some of the key members, clauses, attributes, and interfaces used to complete the task.

Table 9-1. Web part programming tasks

Task	Summary	Key members
Create user interface	Add ASP.NET controls to the Controls collection; then render those controls and additional HTML to an output object in RenderWebPart .	Controls CreateChildControls RenderControls RenderControl RenderWebPart
Add JavaScript and HTML	Write code to import and modify HTML control IDs to use the SharePoint-generated names .	ClassResourcePath IsClientScriptBlockRegistered RegisterClientScriptBlock ReplaceTokens UniqueID
Handle child control events	Hook up server-side event handling for ASP.NET controls in the Controls collection.	AddHandler WithEvents (clause) Handles (clause)
Create properties	Add property procedures to a web part and specify attributes that tell SharePoint how to display them in the property task pane and whether or not to save their values.	Browsable (attribute) Category (attribute) DefaultValue (attribute) ElementName (attribute) SaveProperties ShouldSerialize WebPartStorage (attribute) XmlElement (attribute) XmlRoot (attribute)
Add menus	Add items to the web part drop-down menu that respond to server or client events.	CreateWebPartMenu MenuItem MenuItems
Customize property task pane	Change the display of a web part's properties in the property task pane and control how the web part is updated from those settings.	ApplyChanges CancelChanges CustomPropertyToolPart GetToolParts ParentToolPane RenderToolPart WebPartToolPart
Make web parts connectable	Implement interface in the web part class to provide data to other web parts or consume data from other web parts.	ICellProvider ICellConsumer IRowProvider IRowConsumer IListProvider IListConsumer IFilterProvider IFilterConsumer IParametersInProvider IParametersInConsumer IParametersOutProvider IParametersOutConsumer

You can find reference information for these keywords in the SharePoint SDK or in the Visual Studio Helpthe SharePoint SDK omits items that aren't part of their namespace. For instance, it doesn't cover the RenderControl method because that is part of the .NET Framework.