Chapter 26
Working with the Web Part Pages Web Service
IN THIS CHAPTER
If you have used Microsoft Office SharePoint Server (MOSS) for more than five minutes, you have encountered Web Part pages. Any page within SharePoint that renders Web Parts is a Web Part page—a page that builds on top of the ASP.NET 2.0 Web Part functionality by adding SharePoint-specific features on top.
You can choose to manipulate these pages programmatically via the object model or via the Web Part Pages Web Service. This chapter deals with the latter, providing you with information on how to use this web service to query and manipulate Web Parts on Web Part pages.
Overview of the Web Part Pages Web Service
The Web Part Pages Web Service can be accessed at http://[server]/[site]/_vti_bin/webpartpages.asmx. This web service provides facilities for querying and manipulating Web Parts on Web Part pages within the site to which the client is connected. Table 26.1 provides an overview of the methods available on this web service.
Table 26.1. Web Part Pages Web Service Methods
As with all web services within SharePoint, any client code connecting to the web service needs to provide valid credentials to access the service both for discovery and for runtime execution.
Adding and Updating Web Parts
Adding Web Parts to Web Part pages is unfortunately somewhat of an ugly looking process. To add a Web Part to a Web Part page, you need to provide an Extensible Markup Language (XML) fragment representing the entire Web Part and all of its properties as input to the AddWebPart or AddWebPartToZone methods. Thankfully, the element names for the Web Part XML fragment have a fairly straightforward relationship to the configurable properties within the Web Part tool pane on a SharePoint site.
Listing 26.1 shows some code that uses the AddWebPart method to add a new Web Part to a page. The Web Part is a content editor part and the XML fragment also contains the value for the Web Part’s Content property. The XML fragment defines the content for the Web Part. Those of you used to doing low-level SharePoint administration will recognize the XML fragment from Web Part definitions found in XML files on the SharePoint server in the templates directory.
Listing 26.1. Adding a Web Part to a Web Part Page
The XML format for the Web Part as well as a very similar sample can be found online in the Windows SharePoint Services (WSS) Software Development Kit (SDK) on MSDN, so don’t worry if you don’t have the format memorized.
After executing the code in Listing 26.1, the page in question has been modified to include a new Web Part, as shown in Figure 26.1.
Figure 26.1. Rendered page after adding a Web Part programmatically.
Similarly, the act of saving changes to a Web Part must be done using an XML fragment that is passed to the SaveWebPart method, as shown in Listing 26.2.
Listing 26.2. Updating an Existing Web Part
Other than the tedious and unfortunate XML manipulation that must take place to add and update Web Parts, the other thing that can catch developers unaware is that you must specifically have the globally unique identifier (GUID) of the Web Part being modified to save changes. You can obtain the GUID either by maintaining a reference to it after initial creation, or by querying the Web Part page in any number of ways, some of which are illustrated later in the chapter.
Figure 26.2 shows two content editor Web Parts, one was created using the web service and the other was created and modified using the web service.
Figure 26.2. Rendered output after modifying an existing Web Part.
Querying Web Part Pages
There is a wealth of information that can be obtained from the Web Part Pages Web Service, including information on individual Web Parts, Web Part connection data, properties for all Web Parts on a page, and even information on Assembly metadata and the list of trusted Assemblies installed. This section shows you a few of the methods available on the Web Part Pages Web Service for enumerating Web Parts and querying information.
Using the GetWebPart Method
The GetWebPart method obtains property details for an individual Web Part contained on a Web Part page and returns that information in the form of a string that can be read into an XML document. Some methods on this web service return strings, whereas others return XmlNode instances. Being aware of the inconsistency in design of the web service up front makes it a little easier to use. Listing 26.3 shows how to use the GetWebPart method.
Listing 26.3. Calling the GetWebPart Method
When the preceding code is executed, the following output is shown, which contains the contents of the Content node:
<![CDATA[<P>Content <B><i><u>modified</b></i></u> programmatically.</P> ]]>
Getting Safe Assembly Details
Safe Assemblies are Assemblies indicated as “safe” by various configuration files used by SharePoint. For more information on what constitutes a Safe Assembly and Assembly security within SharePoint, consult a SharePoint administration guide or Microsoft SharePoint 2007 Unleashed (Sams, ISBN: 0672329476). The following code snippet illustrates how to call the GetSafeAssemblyInfo method and interpret the results:
Figure 26.3 shows the output from the preceding code.
Figure 26.3. Safe Assembly output.
Summary
This chapter provided some examples of how you can write code that will remotely query and manipulate Web Parts within Web Part pages, a key component of SharePoint’s content management capabilities.