[6/13/2013] Update: I have changed the terminology, from Future back to Promise, to conform to the living standard.
Disclaimer: the solution presented in this article is part of SPELL, a coaching program offered by User Managed Solutions LLC. Access to the full set of SPELL solutions requires a paid registration. However, the program also includes free evaluation samples like pocketSOAP, all you need to do to get them is show your interest by registering to the SPELL newsletter.
The SPELL newsletter currently has ~180 subscriber companies. The issue featuring pocketSOAP is scheduled for the first half of June.
For years, the SharePoint SOAP services have been a favorite among power users and front end developers. Their popularity is due to an accumulation of factors:
- They are supported across all SharePoint versions
- They offer a wide range of features, from simply accessing list items to building sites or managing permissions
- They work in client side environment, and don’t require server side access.
- They are well documented, thanks in particular to the work of SharePoint bloggers (cf. references at the end of this post)
Since the SP 2010 release, Microsoft has been embracing more and more the client side, and has pushed additional tools like CSOM, REST (listdata.svc, _api), and client side rendering for list views (JSLink). At the same time SOAP services have been deprecated (but are still supported in SP 2013). Developers are faced with a difficult choice: they’d like to adopt new technologies, but at the same time these technologies don’t offer (yet) the same coverage as the legacy SOAP services. And of course they don’t work in older versions.
The purpose of pocketSOAP is to showcase how I dealt with this dilemma in SPELL. When you want to interact with half a dozen interfaces, as SPELL does, you can’t afford a 100 kb footprint just for one! So here we go, 5 kb of fully functional code, no dependency! The list of pocketSOAP ingredients:
- SOAP: ~ 1 kb
- Ajax: ~ 0.4 kb
- Promises: ~ 1 kb
- Templating: ~ 1 kb
- Various helper functions: ~ 1.6 kb
A simple example
Note: pocketSOAP targets developers and assumes that you are comfortable with JavaScript patterns such as ajax, promises and templating. If you are an end user, you might be more interested in user friendly samples like the SPELL Tabs or the SPELL Charts (and of course the SharePoint User Toolkit).
For my simple example, I have just created a custom list called “Projects”, with 2 columns:
- Title is a text field for the item name (Project 1, Project 2,…)
- Status is a choice field for the item status: green, yellow or red.
Expected result (cf. screenshot): color coded indicators that displays the health of each project.
The code (pS is the shorthand for pocketSOAP):
var promisedItems = pS.soap({
// Service info
site:"https://usermanaged.sharepoint.com/TestSite",
service:"Lists",
operation:"GetListItems",
// Service parameters
listName:"Projects"
});
pS.when(promisedItems).then(function(request){
// Apply template
document.getElementById("results").innerHTML=pS.applyHTMLTemplate({
template:"<table>[<|<tr><td><div style='width:12px;height:12px;background-color:|Status|;'> </div></td><td>|Title|</td></tr>|>]</table>",
prefix:"ows_",
data:pS.byTagNS(request.responseXML,"row","z")
});
});
How the code works:
- pS.soap() handles the SOAP request (ajax). It needs two sets of options: information about the service itself (in our case Lists/GetListItems) and parameters specific to the call (in the case of GetListItems: the list name, and maybe specific filtering options and a shortlist of the fields to retrieve).
- pS.when().then() is a promises pattern. It ensures that the SOAP request is completed before we move to the next step.
- pS.applyHTMLTemplate() runs the templating engine, in this specific example to output a html string. In the template expression, [< >] means that we are dealing with a collection of nodes. If we were using the new REST interface and retrieving JSON, we would simply use [{ }] instead of [< >].
- the prefix ows_ is just here to address an oddity with SharePoint Web services, where “ows_” is prepended to each field name. So for example to get the Title field, you need to retrieve the attribute called ows_Title.
- the data is the result of ajax xmlHttpRequest. If you are familiar with the SOAP service GetListItems, you know that each item is returned as a namespaced “z:row” node.
How many SOAP services does pocketSOAP support?
I don’t know. So far I have only tested it for half a dozen services representative of my scenarios (90% of real life use cases are about getting or updating list items). I plan to document this as I and the SPELL followers continue testing more services.
Can I use SPELL/pocketSOAP to aggregate values from multiple lists?
Yes. Thanks to the promises pattern, the script can collect data from multiple lists in parallel, then trigger the rendering when all the items have been collected. The pocketSOAP documentation will include such an example.
Note however that for a large number of lists, client side code might not be the best approach and you’ll want to consider other techniques.
How do I make a synchronous call?
You can’t, this option has been removed from SPELL last year. The choice is to embrace a modern JavaScript approach where remote calls are asynchronous (the first “a” in ajax), and dependencies are managed via promises: when(this is completed).then(do that).
In SPELL, not only ajax calls, but also script loading, iframe loading, document ready, and some other operations are treated as promises.
Did I go too far with pocketSOAP?
The answer is… yes! If you play with pocketSOAP, keep in mind that it is a laboratory rat. The SPELL library – the production version – offers much better balance between the load effort and efficiency at runtime.
How is SPELL different from pocketSOAP?
1/ SPELL is for production, while pocketSOAP is an experiment. For example error handling has been reduced to a minimum in pocketSOAP.
2/ SPELL supports half a dozen interfaces, SOAP just being one of them. Apart from SOAP ($P.soap), it also relies on the RPC method ($P.rpc), the REST services ($P.listdata and $P._api), etc.
3/ SPELL offers not only core features aimed at developers, but also end user solutions like the SPELL Tabs and mini-BI.
How come SOAP has never been mentioned before on Path to SharePoint?
Until recently, I have always considered that SOAP was a heavy solution and should only be used in large scale implementations, or when everything else fails. For the samples showcased in this blog and in the SharePoint User Toolkit, my preference went to the RPC method, a more straightforward and end user friendly approach.
However when I started building SPELL two years ago, SOAP was an essential building block in a projet of that size. The decision to include SOAP was even easier after I reduced the code size to just a couple kb!
References
The official Microsoft reference for SharePoint 2013 Web services can be found here.
The first to publish a JavaScript library to wrap SOAP services was Darren Johnstone in 2008. His original site doesn’t seem to exist anymore, to get the files try an internet search for “SPAPI”.
SharePoint superstar Jan Tielens published in 2009 a series of posts to showcase the use of SOAP services in conjunction with jQuery.
That same year, Marc Anderson released SPServices. This remains to date the most useful and comprehensive resource on the subject. When people look for documentation on the SOAP services, I usually point them to Marc’s Codeplex site rather than the official Microsoft documentation.
SOAP services are also a favorite of Alexander Bautz, and he uses them in some of his published work.
Alexander’s blog drove me to another library called SharePointPlus, developed by DELL employee Aymeric Kodono and released under a GPL v2 license.
There are certainly others I am not aware of. For example I haven’t tested this framework that seems to deal with the SOAP services (and btw is not maintained anymore). If you have more information feel free to post it in the comments!
Path to SharePoint... and Beyond! 