A javascript API for the SharePoint and Office Live Web Services

July 22nd, 2008 • Related • Filed Under

Quite a while ago I published a small article on how to call a SharePoint web service via javascript. Back then (and now too) I was doing a lot of work with Office Live and this was one of the only ways to really interact with the system since running server side code in Office Live is prohibited (with good reason).

That article gets quite a lot of hits and comments and it seems that a lot of people call the SharePoint web services from javascript routinely, although I guess this shouldn’t be a surprise in the modern world of AJAX and so on. The original article was a quick and dirty way to get at the List Data Retrieval web service of the WSS 3.0 SDK. It had some issues though. Firstly many people got confused with the way the XML packet was built up in a string- a quote missing here or there and you’re doomed to the server 500 error. The second problem was that the code only works in Internet Explorer since it relies on the XMLHttp object. This should really be made cross browser, but at the time Office Live was only available on Internet Explorer- not so now as the horizons have been expanded to include Firefox.

So I decided to redo the code and make it cross browser. I also wanted to clean up the way the XML packets were created to make it less error prone for people. Lastly, I wanted to offer some support for the processing of the result messages and examples of how to do this in a cross browser way.

To start with I wrote a little program that generated a javascript proxy for a web service. This was a fairly simple process and resulted in a large number of methods like the one below:

this.getListItems = function(listName, viewName, query, viewFields, rowLimit, queryOptions, webID)
{
    if (queryOptions == null || queryOptions == '') queryOptions = '<QueryOptions/>';

    var action = 'http://schemas.microsoft.com/sharepoint/soap/GetListItems';
    var params = [listName, viewName, query, viewFields, rowLimit, queryOptions, webID];
    var packet = '<?xml version="1.0" encoding="utf-8"?><soap:Envelope></soap:Envelope>';

    return this.core.executeRequest(this.serviceUrl, action, packet, params);
}

Each method actually has the full XML of a soap request packet specific to the web method. This is marked with placeholders for the various parameters which makes it easy to call. So I ran this against all of the SharePoint web service except the admin one.

Each SharePoint web service is represented by a single javascript class named after the service. There are 21 of these classes, each of which contains a method for each of the web methods in the service. The classes are all named after a single SharePoint web service with a JSAPI_ extension. So the class for the lists.asmx web service is in a class called JSAPI_Lists in a file called JSAPI_Lists.js. Each method within the class is named after a web method. In addition to this there is a single utility class JSAPI_Core which is in the JSAPI_Core.js file- this handles the cross browser web service calls and is required by all of the other classes.

I’ve also provided a helper class for creating request packets for the search web services. This is contained in JSAPI_Types.js. This provides a programmatic method for creating the XML request packets for searching without resorting to string building.

The intention of this library is to make it easier for solution developers to interact with the Office Live and SharePoint web service APIs and should help to make the code required easier to develop and maintain- take the following example which performs a keyword search on a SharePoint site collection:

var lists = new SPAPI_Search('');
var query = new SPAPI_QueryPacket(SPAPI_Query_Type_Keyword, 'Sharepoint', 'Title,Path,Description,Write,Rank,Size');

// Add a new sort property - sort by ID, descending, first sort property
query.addSortProperty('ID', false, 0);

// Add a new sort property - sort by Title, ascending, second sort property
query.addSortProperty('ID', true, 1);

var res = lists.query(query.getXML());

if (res.status == 200)
{
   // Get the response document
   var resultDocument = query.getResultDocument(res.responseXML);
   var status = resultDocument.getElementsByTagName('Response')[0].getElementsByTagName('Status')[0].childNodes[0].nodeValue;

   alert('The status of the search was: ' + status);

   if (status == 'SUCCESS')
   {
        var count = resultDocument.getElementsByTagName('Range')[0].getElementsByTagName('Count')[0].childNodes[0].nodeValue;
        alert(count + ' results were returned');

        var items = resultDocument.getElementsByTagName('Response')[0].getElementsByTagName('Document');

        for (var i=0; i<items.length; i++)
        {
            // Process each document result
        }
   }
  else
{
  alert('There was an error processing the search');
}

Anyway, hopefully this will be of use to people. The libraries are available in the downloads section and as usual are released open source under the Lesser GNU license. A series of examples on how to use the libraries in various scenarios will follow in my next post.

Popularity: 58% [?]

There Are 30 Responses So Far. »

Comment by Matt Borsuk on 27 August 2008:

Hello Darren,

I would like to preface by saying that as a newbie web developer I truly appreciate the work you have done and posted in order for the rest of us out here to learn and advance our skills.

I came across your blog: http://darrenjohnstone.net/2008/07/22/examples-for-the-sharepoint-and-office-live-javascript-api/#topic-5 and have a few questions regarding how to use and implement these methods.

My company just set up SharePoint to be used as our intranet platform and I have been assigned a project of creating a module that can be placed on multiple pages that will query a SharePoint list and return all of the data. I plan on doing this by creating a JavaScript function that can be called on each of those pages.

Here is what I have thus far based off of your work Thanks! -

function GetListItems() { // Return all items in the default view of a list var lists = new SPAPI_Lists('rootURL') var items = lists.getListItems( 'OutageAlerts', // listName '', // viewName '100', // query '', // viewFields 100, // rowLimit 'FALSE' // queryOptions );if (items.status == 200) { var rows = items.responseXML.getElementsByTagName('z:row');// document.getElementById('output').value = items.responseText; for (var i=0; i<rows.length; i++) { document.getElementById('outputdiv').innerHTML = rows; } } else { alert('There was an error: ' + items.statusText); } } _spBodyOnLoadFunctionNames.push("GetListItems");

I am able to successfully read the list, if I set the output to show the length of the rows in the list I receive the correct number, but when I have it output the rows, it returns [object]. How can I get it to return each list item in a ? I know it’s probably something simple, I just need another set of eyes to point it out I hope.

Thanks for your help and time,

Matt Borsuk
Comment by darren on 27 August 2008:

Hi Matt,

I think the line

document.getElementById('outputdiv').innerHTML = rows;

is wrong.

This will always emit [object] as rows is an array of objects (in itself an object).

What you need is

document.getElementById('outputdiv').innerHTML = rows[i].getAttribute(name);

where name is the name of the attribute in the row (SharePoint internal column name) you wish to show.

Good luck.

Cheers,
Darren
Comment by Matt Borsuk on 27 August 2008:

Hi Darren,

Thank you so much for getting back to me, I really appreciate your willingness to help!

I’ve tried what you’ve suggested but the output that is being returned is null. This is what I attempted –

document.getElementById('outputdiv').innerHTML = rows[i].getAttribute(‘Title’);

I’m not sure if I’m calling the correct field name, are they titled something different than what is displayed in the list itself? Also, I’d rather return the entire row rather than just the column, is there a way to do that?

Thanks again for you help!

Best!
Matt
Comment by darren on 27 August 2008:

Hi Matt,

The column you need will be called ows_Title. There is an example XML packet here: http://darrenjohnstone.net/wp-content/jsapi/packets/GetListItems.xml.

If you want to get the entire row you’ll need to build it up manually from the columns. You could also consider using a client side XSL transform on the responseXML property.

Cheers,
Darren
Comment by Matt Borsuk on 29 August 2008:

Hi Darren,

I just wanted to follow up with you in regards to my inquiry. Thank you for your assistance,I was able to get everything working as I needed now I just need to style the output which shouldn’t be an issue.

Thanks again!

Matt
Comment by Hans on 28 October 2008:

Can anyone provide a demo how to put this in a content editor web part? So including a button to call the script etc.
Pingback by No assembly required « Path to SharePoint on 3 November 2008:

[...] usually require more programming efforts than other solutions listed here. Darren Johnstone has a very interesting post (including code) that can help you get started. Similar techniques are REST methods, and the [...]
Comment by robin on 17 November 2008:

I would also like to see how to put this in a CEWP if possible
Comment by Dave Newman on 19 November 2008:

Darren,
I’m trying to get your API installed on a server and I had done it before on a long lost server. What folder on the server should I save the API support files to? I’m getting “SAPI_Lists is undefined” in a page error. I loaded the files to either of Program Files\Common Files\Microsoft Shared\web server extensions\12\ISAPI (the _vti_bin folder) or just the \bin folder.
What is the best suggestion?

Thanks!
Dave
Comment by Dave Newman on 19 November 2008:

Darren,
I figured it out. I put the API .js files in the _layouts/1033 folder with the other Sharepoint .js files. I was not adding the include script to my code.

I do appreciate the work you have done on these API calls, and they are very helpful. One thing to mention is that many of us are newbees to Sharepoint and Javascript in general. It’s helpful to have the more obvious items like where to install and the script includes in the examples.

Thanks again for the neat API!

Dave
Pingback by Power User Toolbox: JavaScript for SharePoint - Pt8 | End User SharePoint on 11 December 2008:

[...] JavaScript API may not work for anonymous users. If you use Audience Targeting to only load for authenticated [...]
Pingback by JQuery for Everyone: Cleaning Windows Pt2 | End User SharePoint on 22 December 2008:

[...] server-side profile store, like a SharePoint list that you connect to using JSAPI and web services, can honor the user’s preferences regardless of which device they use to [...]
Pingback by JQuery for Everyone: Degrading Dynamic Script Loader | End User SharePoint on 20 January 2009:

[...] bootstrapped jQuery 1.3 library, and sample scripts (JSAPI show name)… First, download the SPAPI files and update the configuration file’s path to each file. [...]
Comment by Erik on 26 January 2009:

First off…this site/code is incredible. Thanks for all your hard work!

I am trying to use these libraries in combination with the sharepoint charting code you created. It’s working great, and now I’m trying to extend it a little to create summary graphs. I’m wondering if you’ve already addressed this in your libraries?

For instance, I have a list that includes rows for bugs. Each row has a bug description and a date. I’m trying to present a graph that shows how many bugs were added on each date…essentially doing a count of list items within a specific date grouping. Does your API support a quick way for doing this?

Thanks!
Comment by darren on 15 February 2009:

Hi Erik,
You could create a custom list view in SharePoint to do the grouping for you and then draw the chart from that. In this way you’re not doing number crunching in javascript. I don’t have a specific example- sorry. Cheers.
Comment by nick on 17 February 2009:

hi
i need to know like as we download a software from a site by click on download how can we build this in a .net project plz help me regarding this.
Comment by orry on 5 March 2009:

Hi Darren,
First off, thanks for doing this, as a non ASP web dev this helps a lot. I have a question on the addAttachment method in SPAPI_Lists.js. My goal is to be able to upload attachments to a list entry. Do you just pass a pointer to a file, or do you need to pass the byte array of the file ? Any hint on how do you do this with JS ?

Thanks again,
Orry
Comment by Tom Clarkson on 4 May 2009:

Very useful. I’ve been using this code to implement threaded discussions in a content editor web part and just got the details online:

http://www.tqcblog.com/archive/2009/05/04/sharepoint-discussion-with-jquery.aspx
Comment by Andrew on 19 June 2009:

Hi,

I have been trying the above examples and they work great – Thanks.

Will the API work if we are using “Forms Based Authentication”?

Thanks

Andrew
Comment by Deykun Marat on 25 June 2009:

Hello.

I’ve got server side code restriction. And i need to upload picture from custom page to SP picture library. i’am going to use “this.upload = function(strListName, strFolder, bytes, fileName, fOverWriteIfExist)” from SPAPI_Imaging (Is it right way?). Could you explain me how can I get bites when user select picture using “”.

Thank you.
Comment by Deykun Marat on 25 June 2009:

Hello.

I’ve got server side code restriction. And i need to upload picture from custom page to SP picture library. i’am going to use “this.upload = function(strListName, strFolder, bytes, fileName, fOverWriteIfExist)” from SPAPI_Imaging (Is it right way?). Could you explain me how can I get bites when user select picture using “input type=”file””.

Is there another approachs to solve a problem?

Thank you.
Pingback by PhoneBook Search – No code required | End User SharePoint on 21 August 2009:

[...] partially inspired by SharePoint Search-As-You-Type with JQuery by Jan Tielens. I also used Javascript API for the SharePoint webservices by Darren Johnstone to query the data and jQuery PHP Ajax Autosuggest by Ashley to create the [...]
Comment by Mark on 25 August 2009:

Darren,

Thank you for all the excellent information on your site. However, I have encountered the same issue as Dave where I received a “SPAPI_Lists is undefined” page error. I have moved the SPAPI files into my layouts/1033 folder, but I am still receiving the page error. Can you please help?

Thanks,
Mark
Comment by tfforums on 23 October 2009:

i can’t get this to work in firefox… the core js fails when using the request.send method with “0×80004005 (NS_ERROR_FAILURE).

according to this:
http://mxr.mozilla.org/mozilla1.8.0/source/extensions/xmlextras/base/src/nsXMLHttpRequest.cpp#1423

its because a request is already happening???? would really like this cross browser api to actually work cross browser.
Comment by Tom Tolleson on 26 October 2009:

Hi, Darren. I’m new to SharePoint, and I currently need to be able to pull the ID from a SharePoint list asynchronously. Using the JavaScript API seems to be the perfect thing for me. However, due to having only a small amount of experience with SharePoint, I’m not sure where to place this code. Does it go in the head of an .aspx page and return the queried results in the browser window? I’ve tried this and it doesn’t seem to work, nor does placing it in a Content Editor Web Part.

Would someone mind giving me a sort of wider context of how to implement this code?

Thanks everyone!

Tom
Comment by Tom Tolleson on 26 October 2009:

Also, is the JavaScript getting this information from the SharePoint Database or from the output on the page?

What I need is for the JavaScript to query if a new list item has been created.
Comment by John on 27 January 2010:

Heya. Fantastic library you’ve created here. Huge thanks for saving me ripping countless hairs from my head!

Used it with a cross breed of JQuery and some prototyped functions to really excel in timescales.
Comment by Sampath Kumar K on 2 February 2010:

Can someone tell me if it is possible to send attachments with web services using JavaScript in SharePoint? If so how to send?

As per my investigation, there is a webservice http://servername/_vti_bin/lists.asmx and in that there is a method called AddAttachment(). But its asking for a parameter of type base64Binary. So how can i convert one file/document to base64Binary in javascript?
Pingback by Use case: PhoneBook Search – no code required | SharePoint Use Cases on 12 April 2010:

[...] was partially inspired by Search as you type by Jan Tielens, I used Javascript API for the SharePoint webservices by Darren Johnstone to query the data and jQuery PHP Ajax Autosuggest by Ashley to create suggestion [...]
Pingback by Search as you type for Links list | SharePoint Use Cases on 12 April 2010:

[...] to work with any list you wish, but you need to tweak the code a bit. I am using very powerful Javascript API for the SharePoint webservices by Darren Johnstone that allows you to do [...]

Darren’s SharePoint and .Net blog

A javascript API for the SharePoint and Office Live Web Services

There Are 30 Responses So Far. »

Popular

Most Comments

Search

Tags

Archives

Recent Comments