SPServices Stories #3 – AddWebPart Method of the WebPartPages Web Service

This entry is part 3 of 21 in the series SPServices Stories

Introduction

Eric Alexander (@ejaya2) should be no stranger to those of you who have visited NothingButSharePoint‘s Stump the Panel forums. If you’ve ever visited those forums, odds are very good that Eric has helped you out. He’s a stalwart member of the SharePoint support community.

Eric wrote a post on his blog about using SPServices to add Web Parts to existing pages that I thought was worth sharing as an SPServices Story.

AddWebPart Method of the WebPartPages Web Service

There are a lot of documentation black holes out there in the Sharepoint land and it seems that the WebPartPages web service is one of them.

In a project I’m currently working on, there is a need to automate a project creation process that is very manual to something more automated. Fortunately we have Nintex Workflow to handle situations like this.​ Part of this workflow is to provision a new subsite after the project is approved by the project manager. Nintex makes this easy with their LazyApproval feature and create site action.

What I needed to do was upon site creation from a template, add some web parts to the home page. This is where I was running into the huge documentation gap. I turned to one of my goto libraries, SPServices, to protoype the actual calls before porting it over to my workflow. Fortunately someone had tried to do this same thing in the past and provided a working example for adding a content editor web part. That is described here and worked no problem. My issue is I need to add list view web parts of document libraries and lists. I tried many things over the span of a couple days to tweak that to get my web parts onto the page. No dice.

Today I stumbled upon a post by Glyn Clough that filled that documentation black hole.

I need to use the List View Web Part markup like this for lists:

<?xml version="1.0" encoding="utf-8" ?>
<webParts>
 <webPart xmlns="http://schemas.microsoft.com/WebPart/v3">
  <metaData>
   <type name="Microsoft.SharePoint.WebPartPages.XsltListViewWebPart, Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" />
   <importErrorMessage>Cannot import this Web Part.</importErrorMessage>
  </metaData>
  <data>
   <properties>
    <property name="ListUrl" type="string">Lists/CustomList</property>
    <property name="ExportMode" type="exportmode">All</property>
   </properties>
  </data>
 </webPart>
</webParts>

and like this for document libraries:

<?xml version="1.0" encoding="utf-8" ?>
<webParts>
 <webPart xmlns="http://schemas.microsoft.com/WebPart/v3">
  <metaData>
   <type name="Microsoft.SharePoint.WebPartPages.XsltListViewWebPart, Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" />
   <importErrorMessage>Cannot import this Web Part.</importErrorMessage>
  </metaData>
  <data>
   <properties>
    <property name="ListUrl" type="string">Library</property>
    <property name="ExportMode" type="exportmode">All</property>
   </properties>
  </data>
 </webPart>
</webParts>

Once escaped and passed into my SPServices function I had web parts on my web part page.

SPServices Code

Eric’s post doesn’t have the SPServices call in his post, so I thought I’d provide an example here. This is built from the example from the documentation on the SPServices Codeplex site for AddWebPart. It adds an XLV Web Part showing the default view of my Tasks list to the home page of my root site and shows me an alert with the results.

var str = "&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot; ?&gt;" +
"&lt;webParts&gt;" +
 "&lt;webPart xmlns=&quot;http://schemas.microsoft.com/WebPart/v3&quot;&gt;" +
  "&lt;metaData&gt;" +
   "&lt;type name=&quot;Microsoft.SharePoint.WebPartPages.XsltListViewWebPart, Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c&quot; /&gt;" +
   "&lt;importErrorMessage&gt;Cannot import this Web Part.&lt;/importErrorMessage&gt;" +
  "&lt;/metaData&gt;" +
  "&lt;data&gt;" +
   "&lt;properties&gt;" +
    "&lt;property name=&quot;ListUrl&quot; type=&quot;string&quot;&gt;Lists/Tasks&lt;/property&gt;" +
    "&lt;property name=&quot;ExportMode&quot; type=&quot;exportmode&quot;&gt;All&lt;/property&gt;" +
   "&lt;/properties&gt;" +
  "&lt;/data&gt;" +
 "&lt;/webPart&gt;" +
"&lt;/webParts&gt;";

$().SPServices({
  operation: "AddWebPart",
  webPartXml: str,
  pageUrl: "/SitePages/Home.aspx",
  storage: "Shared",
  async: true,
  completefunc: function (xData, Status) {
    alert("Status: " + Status + " xData: " + xData.responseText);
  }
});
Series Navigation<< SPServices Stories #2 – Charting List Data with HighChartsSPServices Stories #4 – Using SPServices to Process Files from a Non-Microsoft Source >>

4 Comments

    • Bryan:

      True dat. The nice thing about using the SOAP Web services is that the same code will work in 2007, 2010, 0r 2013. It all depends on where you are in your SharePoint Journey.

      M.

      Reply
  1. Oh that’s a mess! I used to do these using features and site templates. Marc, can your tool do connected web parts? That was always a fun one to figure out.
    So if you can emit the escaped XML to the soap service, it can provision and the web part. Interesting.

    Reply
    • Yup, pretty neat, eh? You could store the XML definitions in a list and read them for instantiation. It’s simply a different way of deploying Web Parts (and there’s certainly the possibility for many other artifacts as well).

      It’s not “my tool”, really. The SOAP Web Services have long offered far more capabilities than most people have ever taken advantage of. SPServices just makes the calls easier.

      M.

      Reply

Have a thought or opinion?