Section 10.5. Using FrontPage RPC | Essential SharePoint 2007: A Practical Guide for Users, Administrators and Developers

10.5. Using FrontPage RPC

The FrontPage Remote Procedure Call (RPC) methods provide yet another way to change SharePoint sites and get content remotely. The RPC methods are similar to the URL commands discussed earlier, except RPC uses HTTP POST rather than GET to send requests .

Don't confuse FrontPage RPC with .NET RPC. They are very distinct technologies that unfortunately share the same acronym.

Use RPC methods when you want to compose your changes or queries in Collaborative Markup Language (CAML) rather than through web service methods. CAML is a declarative approach to programming SharePoint using XML rather than a procedural programming language such as Visual Basic .NET. There are several advantages to this approach:

RPC methods can be included on a web page as content rather than as server-side code.
Users can compose and run queries in CAML without installing web parts or other code on the server.
SharePoint templates and descriptions are in CAML, so understanding it helps you create custom site definitions.
RPC incurs less overhead than web services.

Table 10-8 lists the methods available through RPC. The URL commands are also available through RPC but aren't included in this table since they are already listed in Table 10-6.

Table 10-8. SharePoint RPC methods

Method	Parameters	Use to
Cltreq	UL, STRMVER, ACT, URL	Perform web discussion operations such as adding, editing, or deleting a discussion associated with a web page or with a document stored in a document library.
Delete	ID, List, NextUsing, owsfileref	Delete an item in a list.
DeleteField	List, Field, owshiddenversion	Delete a field from the list.
DeleteList	List, NextUsing	Delete a list.
DeleteView	List, View	Delete the view.
ImportList	Title, RootFolder, ListSchema	Create a list based upon a specified XML schema.
ModListSettings	List, OldListTitle, NewListTitle, Description, ReadSecurity, WriteSecurity, SchemaSecurity	Change the properties of the list.
NewField	List, FieldXML, AddToDefaultView, owshiddenversion	Add a new field to the list specified.
NewList	ListTemplate, Description, displayOnLeft, VersioningEnabled, GlobalMtgDataList, AllowMultiVote, showUsernames	Create a list of a specified type, such as Contacts, Discussions, or Survey.
NewViewPage	List, PageURL, DisplayName, HiddenView	Add a new view page to the list.
NewWebPage		Create a new web part page or a new basic page in the document library.
ReorderFields	List, ReorderedFields	Change the order in which fields in the list are displayed on the data entry form.
Save	ID, List, NextUsing	Save a new list or save modifications to an existing list.
SiteProvision	CreateLists	Add the default set of lists to an existing SharePoint site.
UpdateField	List, FieldXML, showshiddenversion	Modify the schema of an existing field in the list.

10.5.1. Preparing a Page for RPC

Because RPC methods can change content, the post must include user information so SharePoint can authenticate and authorize the method. That means you must take a few special steps to execute RPC commands on a web page:

Add a FormDigest control to the page .
Create a form element that includes the method to execute and that posts its contents to http: //server/site / _vti_bin/owssvr.dll .
Create a client-side script to insert the value from the FormDigest control into the form before it is posted .
Add a Submit button to post the form .

When creating a page that includes RPC commands, it's easiest if you start with a web part page generated by SharePoint, since those pages include the @ Register directive for the SharePoint web controls.

For example, I created RPCDemo.aspx in the TestPages document library and edited it using FrontPage to create a platform for testing RPC commands. Then, I added the following script to the HEAD element at the beginning of the page:

 <!-- This directive registers the FormDigest WebControl -->     <%@ Register Tagprefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls"  Assembly="Microsoft.SharePoint, Version=11.0.0.0, Culture=neutral,  PublicKeyToken=71e9bce111e9429c" %>     <html dir="ltr">     <HEAD>     <!-- Add this script to include user info in the CASML -->     <script type="text/javascript" language="JavaScript">     function InsertSecurityValidation(oForm)     {         var sFormDigest = '<SetVar Name="_  _REQUESTDIGEST">' +           oForm.elements["_  _REQUESTDIGEST"].value + "</SetVar>\n";         var oPostBody = oForm.elements["PostBody"];         var rePattern = /<\/Method>/g;         oPostBody.value = oPostBody.value.replace(rePattern, sFormDigest + "</Method>");     }     </script>     </HEAD>

Next , I added the following form after the closing form tag generated by SharePoint:

 <!-- SharePoint web part zones omitted here -->     <\form>     <!-- Form used to post RPC commands to SharePoint -->     <form class="ms-formbody" method="post"       action="http://wombat1/_vti_bin/owssvr.dll"       onsubmit="InsertSecurityValidation(this);"       target="result" >       <!-- This control provides user information -->       <SharePoint:FormDigest runat="server"/>       Enter CAML containing RPC methods and click Run to see the result:       <input type="hidden" name="Cmd" value="DisplayPost" />       <!-- Source for CAML -->       <textarea name="PostBody" style="width=100%;height=200">       </textarea>       <br>       <input type="submit" value="Run" />       <input type="reset" value="Clear" />       <br>       Result:       <!-- Target for results -->       <IFRAME name="result" src="::blank.htm" style="width=100%;height=200"/>     </form>

Figure 10-8 shows the resulting web part page. You can enter CAML in the textbox, click Run, and see the results in the IFRAME as shown in the figure.

animal 10-8. Using RPCDemo.aspx to test RPC methods

I created RPCDemo.aspx as a test bed for composing RPC method calls. If the CAML is incorrect, an error displays in the result. You can cut and paste samples from the SharePoint SDK into the textbox, modify the parameters, and run the commands to see how they work.

Once you're satisfied with the results, you can hard-code the CAML onto a new web page using a hidden input control as shown here:

 <!-- Embedded RPC -->     <form class="ms-formbody" method="post"       action="http://wombat1/_vti_bin/owssvr.dll"       onsubmit="InsertSecurityValidation(this);"       target="_blank" >       <!-- This control provides user information -->       <SharePoint:FormDigest runat="server"/>       Click Run to see the result in a pop-up window.       <input type="hidden" name="Cmd" value="DisplayPost" />       <!-- Source for CAML -->       <input type="hidden" name="PostBody" value="           <Method ID='0,DisplayPost'>               <SetList Scope='Request'>Lists</SetList>               <SetVar Name='View'>EnumLists</SetVar>               <SetVar Name='Cmd'>DisplayPost</SetVar>               <SetVar Name='XMLDATA'>TRUE</SetVar>         </Method>" />       <br>       <input type="submit" value="Run" />     </form>

Don't forget to add the InsertSecurityValidation script to the new page's header. This sample displays the results in a new pop-up window ( target="_blank ") rather than on the page in an inline frame.

10.5.2. Common RPC Tasks

The following sections make up a quick tour of some common tasks you might want to perform using RPC. In each of these samples, you'll need to replace the GUIDs provided for lists and views with values from your own sites.

10.5.2.1 Identifying lists

RPC methods identify the list they act on by the list's GUID. You can get the GUIDs of all the lists in a site through RPC by calling the DisplayPost method with the View parameter set to EnumLists as shown here:

 <Method ID="0,DisplayPost">       <SetList Scope="Request">Lists</SetList>       <SetVar Name="View">EnumLists</SetVar>       <SetVar Name="Cmd">DisplayPost</SetVar>       <SetVar Name="XMLDATA">TRUE</SetVar>     </Method>

Once you find the GUID of the list you want, you specify that value in the SetList element. For example, the following method exports the Announcements list:

 <Method ID="0,ExportList">       <SetList Scope="Request">{41D7D046-1E0A-4FB2-A096-C063D210D552}</SetList>       <SetVar Name="Cmd">ExportList</SetVar>     </Method>

10.5.2.2 Combining multiple methods

Use the Batch element to combine two or more RPC methods in a single post. For example, the following CAML adds two items to the Announcements list:

 <ows:Batch Version="6.0.2.5608" OnError="Return">       <Method ID="Anouncement1">         <SetList>{41D7D046-1E0A-4FB2-A096-C063D210D552}</SetList>         <SetVar Name="ID">New</SetVar>         <SetVar Name="Cmd">Save</SetVar>         <SetVar Name="urn:schemas-microsoft-com:office:office#Title">Annoucment Title1</SetVar>         <SetVar Name="urn:schemas-microsoft-com:office:office#Body">Annoucement text</SetVar>         <SetVar Name="urn:schemas-microsoft-com:office:office#Expires">2005-09-14T00:00:00Z</SetVar>       </Method>       <Method ID="Announcment2">         <SetList>{41D7D046-1E0A-4FB2-A096-C063D210D552}</SetList>         <SetVar Name="ID">New</SetVar>         <SetVar Name="Cmd">Save</SetVar>         <SetVar Name="urn:schemas-microsoft-com:office:office#Title">Annoucement Title2</SetVar>         <SetVar Name="urn:schemas-microsoft-com:office:office#Body">Announcment text</SetVar>         <SetVar Name="urn:schemas-microsoft-com:office:office#Expires">2005-12-18T00:00:00Z</SetVar>       </Method>     </ows:Batch>

The Batch element's OnError attribute determines what happens if one of the methods fails. The Return setting causes the methods to stop as soon as an error occurs; Continue causes SharePoint to skip the methods with errors and continue with the next method.

10.5.2.3 Querying lists

Use the Display method to perform a query on a list and return only a specific set of fields. For example, the following query returns three fields from a list using the filter criteria introduced=2000 (note that field names are case-sensitive):

 <Method ID="0,Display">       <SetList Scope="Request">{5E6561D4-7048-45AB-BFA1-2D1991BAF3B1}</SetList>       <SetVar Name="Cmd">Display</SetVar>       <SetVar Name="XMLDATA">False</SetVar>       <SetVar Name="Query">name Title introduced</SetVar>      <SetVar Name="FilterField1">introduced</SetVar>      <SetVar Name="FilterValue1">2000</SetVar>     </Method>

For queries that require filtering or sorting, you can also specify a view that defines those criteria. For example, the following query returns items from the list specified by one of the list views:

 <Method ID="0,Display">       <SetList Scope="Request">{5E6561D4-7048-45AB-BFA1-2D1991BAF3B1}</SetList>       <SetVar Name="Cmd">Display</SetVar>       <SetVar Name="XMLDATA">False</SetVar>       <SetVar Name="View">{21E03766-D0CF-4942-B2C0-DF4E3706DD50}</SetVar>     </Method>

10.5.2.4 Creating lists

Use the NewList method to create a new list or document library on a site. The ListTemplate parameter determines what type of list is created, as shown in Table 10-9.

Table 10-9. ListTemplate settings

Setting	List type	Setting	List type
100	Generic	101	Document library
102	Survey	103	Links
104	Announcements	105	Contacts
106	Events list	107	Tasks
108	Discussion board	109	Picture library
110	Data sources	111	Site template gallery
113	Web part gallery	114	List template gallery
115	Form library	120	Custom grid for a list
200	Meeting series	201	Meeting agenda
202	Meeting attendees	204	Meeting decisions
207	Meeting objectives	210	Meeting textbox
211	Meeting things to bring	212	Meeting workspace pages
1100	Issue tracking

For example, the following method creates a new document library:

 <Method ID="0,NewList">       <SetVar Name="Cmd">NewList</SetVar>       <SetVar Name="ListTemplate">101</SetVar>       <SetVar Name="Title">New Document Library</SetVar>     </Method>

10.5.2.5 Creating pages

To add a new web page to the document library created in the preceding section, get the library's GUID; then use the NewWebPage method:

 <Method ID="0,NewWebPage">       <SetList Scope="Request">{28F54F4C-BA98-43E9-A60F-8C81E5365560}</SetList>       <SetVar Name="Cmd">NewWebPage</SetVar>       <SetVar Name="ID">New</SetVar>       <SetVar Name="Type">WebPartPage</SetVar>       <SetVar Name="WebPartPageTemplate">3</SetVar>       <SetVar Name="Overwrite">true</SetVar>       <SetVar Name="Title">TempPage</SetVar>     </Method>

The WebPartPageTemplate parameter determines the layout of the new page, as shown in Table 10-10.

Table 10-10. WebPartPageTemplate settings

Setting	Page layout
1	Full page, vertical
2	Header, footer, 3 columns
3	Header, left column, body
4	Header, right column, body
5	Header, footer, 2 columns, 4 rows
6	Header, footer, 4 columns, top row
7	Left column, header, footer, top row, 3 columns
8	Right column, header, footer, top row, 3 columns

10.5.2.6 Deleting items

The following code deletes the web page created in the preceding section:

 <Method ID="0,Delete">       <SetList Scope="Request">28F54F4C-BA98-43E9-A60F-8C81E5365560</SetList>       <SetVar Name="Cmd">Delete</SetVar>       <SetVar Name="ID">1</SetVar>       <SetVar Name="owsfileref">http://wombat1/New Document Library/TempPage.aspx</SetVar>     </Method>

10.5.2.7 Deleting lists

Use this code to delete the document library created earlier:

 <Method ID="0,DeleteList">       <SetList Scope="Request">28F54F4C-BA98-43E9-A60F-8C81E5365560</SetList>       <SetVar Name="Cmd">DeleteList</SetVar>     </Method>

10.5.3. Resources

To learn about	Look here
Installing the Office Web Services Toolkit	Search http://www.microsoft.com/downloads for "Web Services Toolkit."
Lists web service	http://msdn.microsoft.com/library/en-us/spptsdk/html/soapcLists.asp
DOMDocument	http://msdn.microsoft.com/library/en-us/xmlsdk/html/xmobjPMEXMLDOMDocument.asp
IXMLDOMNodeList	http://msdn.microsoft.com/library/en-us/xmlsdk30/htm/xmobjxmldomnodelist.asp
Query element	http://msdn.microsoft.com/library/en-us/spptsdk/html/tscamlquery.asp
ViewFields element	http://msdn.microsoft.com/library/en-us/spptsdk/html/tscamlviewfields.asp
QueryOptions element	http://msdn.microsoft.com/library/en-us/spptsdk/html/tscSPQuery.asp
Batch element	http://msdn.microsoft.com/library/default.asp?url=/library/en-us/spsdk11/caml_schema/spxmlelbatch.asp