SharePoint JS API

- Darren’s SharePoint and .Net blog - http://darrenjohnstone.net -

Examples for the SharePoint and Office Live javascript APIPosted By darren On July 22, 2008 @ 3:54 pm In Office Live, SharePoint | 25 Comments

The following examples illustrate the use of the javascript API for SharePoint and Office Live. These examples are intended to demonstrate thecore uses of the API for solution developers.

Get the full definition of a list [1]

Get the full definition of a list and associated view [2]

Get the basic detail of all lists in a site [3]

Get the GUID of a list from it’s name [4]

Querying a list using the Lists web service [5]

Querying a list using the List Data Retrieval Service [6]

Create a new list from an existing list template [7]

Delete a list [8]

Create one or more new list items [9]

Update one or more list items [10]

Delete one or more list items [11]

Create a new folder within a list [12]

Performing a keyword search [13]

Performing a full text search [14]

1- Get the full definition of a listThe lists web service contains a method GetList which can be used to obtain the XML definition of a list.This definition contains a great deal of information about the list. The result is a fragment of CAML as described on MSDN [15].

Services JS API Includes Required

Lists.asmxSPAPI_Core.jsSPAPI_Lists.js

Code sample

var lists = new SPAPI_Lists('http://localhost') var listDef = lists.getList('Pages');

if (listDef.status == 200) { // The list definition is in listDef.resultNode and is a browser specific XML document } else { alert('There was an error: ' + listDef.statusText); }

References

Lists.asmx on MSDN [16]

The GetList method definition on MSDN [15]

Related sample XML packets

Result packet from GetList showing the full list definition [17]

2- Get the full definition of a list and associated viewThe lists web service contains a method GetListAndView which can be used to obtain the XML definition of a list and an associated view. Thisdefinition contains a great deal of information about the list. The result is a fragment of CAML as described on MSDN [18].


Lists.asmx SPAPI_Core.jsSPAPI_Lists.js

Code sample

var lists = new SPAPI_Lists('http://localhost') var listDef = lists.getListAndView('Tasks', '{4011C1CE-A840-4BEB-89E3-A42DF3E3711E}');

if (listDef.status == 200) { // The list definition is in listDef.resultNode and is a browser specific XML document } else { alert('There was an error: ' + listDef.statusText); }

References


The GetListAndView method definition on MSDN [18]


Darren’s SharePoint and .Net blog » Examples for the SharePoint a... http://darrenjohnstone.net/2008/07/22/examples-for-the-sharepoint...

1 von 9 21.09.2009 14:44

http://darrenjohnstone.net

http://darrenjohnstone.net/2008/07/22/examples-for-the-sharepoint

Result packet from GetListAndView showing the full list and view definition [19]

3- Get the basic detail of all lists in a siteThe lists web service contains a method GetListCollection which can be used to obtain the basic XML details of all lists in a site. Once these havebeen retrieved they can be enumarated and further details loaded as required. The result is a fragment of CAML as described on MSDN [20].



Code sample

var lists = new SPAPI_Lists('http://localhost') var listCollection = lists.getListCollection();

if (listCollection.status == 200) { var items = listCollection.responseXML.getElementsByTagName('List');

alert('There are ' + items.length + ' lists in the site.');

for (var i=0; i<items.length; i++) { // Do something alert(items[i].getAttribute('Title') + ' ' + items[i].getAttribute('ID')); } } else { alert('There was an error: ' + listCollection.statusText); }

References


The GetListCollection method definition on MSDN [20]


Result packet from GetListCollection showing the full list and view definition [21]

4- Get the GUID of a list from it’s nameSome web services require that the internal guid of a list be passed as a paramter. Since this guid can potentially change between site backupsand certainly when the solution is shipped this can be a problem for solution developers. The GetListGuid function takes a list name and returnsthe guid of the list.



Code sample

function getListGuid(baseUrl, listName) { var res; var lists = new SPAPI_Lists(''); res = lists.getList(listName);

if (res.status == 200) { var listID = -1;

if (res.resultNode != null) { listID = res.resultNode.childNodes[0].getAttribute('ID'); }

return { listID : listID, fullResult : res }; } else { return { listID : null, fullResult : res }; } }

References


The GetList method definition on MSDN [15]


Result packet from GetList showing the full list definition [17]

5- Querying a list using the Lists web service


2 von 9 21.09.2009 14:44


The GetListItems method of the lists web service can be used to query a list using CAML query notation and return list items that match thecriteria. Of the different ways to return list data this is probably the easiest and most recommended way of doing so.

By default, GetListItems returns the records in a list view- either the default view or a custom view definition. In this way the filtering andordering may be specified by the view definition. However, the method also allows the query, row limit, and list of fields to be changed allowingcustom queries to be executed.

See the links given in the references section for more information on the parameters of this method.



Code sample

// Return all items in the default view of MyList

var lists = new SPAPI_Lists('http://localhost') var items = lists.getListItems('MyList');

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++) { // Do something with the row } } else { alert('There was an error: ' + items.statusText); }

// Return the first 5 items where ID < 10. Only return the Title and ID columns and do not include mandatory columns. var lists = new SPAPI_Lists('http://localhost') var items = lists.getListItems( 'MyList', // listName '', // viewName '<Query><Where><Lt><FieldRef Name="ID"/><Value Type="Counter">10</Value></Lt></Where></Query>', // query '<ViewFields><FieldRef Name="ID"/><FieldRef Name="Title"/></ViewFields>', // viewFields 5, // rowLimit '<QueryOptions><IncludeMandatoryColumns>FALSE</IncludeMandatoryColumns></QueryOptions>' // 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++) { // Do something with the row } } else { alert('There was an error: ' + items.statusText); }

References


GetListItems method on MSDN [22]


Sample GetListItems result packet [23]

6- Querying a list using the List Data Retrieval ServiceThe List Data Retrieval Service [24] allows lists to be queried using CAML notation. This service is one of several ways to search SharePoint andOffice Live lists. The service allows for complex search criteria, sorting, result count limiting, and selection of fields. The javascript API provides aspecific helper method to assist in calling this service.

The results are in the form of a CAML fragment containing an element for every row in the result set.

The example selects all pages from the site with an ID greater than or equal to 5. These are sorted in descending order of ID and limited to 10results. The getElementsById method is then used to extract the rows and display their attributes one by one.


dspsts.asmxSPAPI_Core.jsSPAPI_dspsts.js

Code sample

var dspsts = new SPAPI_dspsts('http://localhost'); var res = dspsts.queryRequest( "{CFD2A33E-EE89-47F3-9E28-24442E598326}", // listGuid "<Field Name='ID'/><Field Name='Title'/>", // fields "<Geq><FieldRef Name='ID' /><Value Type='Counter'>5</Value></Geq>", // where "<OrderField Name='ID' Type='xsd:int' Direction='DESC'/>", // orderBy 10 // rowLimit );

if (res.status == 200) {


3 von 9 21.09.2009 14:44


completely removed from the system.



Code sample

var lists = new SPAPI_Lists('http://localhost') var res = lists.deleteList('MyList');

if (res.status == 200) { alert('The list was deleted.'); } else { alert('There was an error: ' + res.statusText); }

References


The DeleteList method definition on MSDN [26]

9- Create one or more new list itemsCreation of new list items is carried out using the UpdateListItems method of the lists web service. This method takes a batch element as aparameter. The batch element contains a number of fields with appropriate values to populate the list item. The javascript API provides a utilitymethod called quickAddListItem which makes this process a little easier by taking care of the XML batch production automatically.

To use quickAddListItem pass in a list name and a javascript object which contains properties and value corresponding to the list item. You canuse the javascript shorthand notation for object creation to make this easy.

For example a basic list item may be expressed as:

{ Title: 'List item title', Description: 'List item description' }

You may also choose to create a number of list items at the same time by passing in an array of objects, each one of which will represent a listitem. All of the items will then be created in the same list. If creation of any item fails then processing will continue on to the next item. You canuse javascript shorthand array notation to make this easy.

[ { Title: 'My new item 3' }, { Title: 'My new item 4' } ]

If you need to create items within a folder simply specify the optional rootFolder parameter. Let’s say you’re creating items in a list called MyList.There’s a folder in there called Folder1. In Folder1 there’s another folder called Folder2. If you want to create items inside Folder2 you setrootFolder to /Lists/MyList/Folder1/Folder2.



Code sample

var lists = new SPAPI_Lists('http://localhost') var res = lists.quickAddListItem('MyList', { Title: 'My new item 2', Description: 'My Description' });

if (res.status == 200) { alert('The new list item was created.'); } else { alert('There was an error: ' + res.statusText); }

// Or to create multiple items....

var lists = new SPAPI_Lists('http://localhost') var res = lists.quickAddListItem('MyList', [ { Title: 'My new item 3' }, { Title: 'My new item 4' } ]);

if (res.status == 200) { alert('The new list items were created.'); } else { alert('There was an error: ' + res.statusText); }

// Or to create items in a folder var lists = new SPAPI_Lists('http://localhost') var res = lists.quickAddListItem('MyList', [ { Title: 'My new item 3' }, { Title: 'My new item 4' } ], '/Lists/MyList/Folder1/Folder2');

if (res.status == 200) { alert('The new list items were created.'); } else { alert('There was an error: ' + res.statusText); }

References


The UpdateItems method definition on MSDN [27]


5 von 9 21.09.2009 14:44


10- Update one or more list itemsUpdating of list items is carried out using the UpdateListItems method of the lists web service. This method takes a batch element as aparameter. The batch element contains a number of fields with appropriate values to update the list item. The javascript API provides a utilitymethod called quickUpdateListItem which makes this process a little easier by taking care of the XML batch production automatically.

To use quickUpdateListItem pass in a list name and a javascript object which contains properties and value corresponding to the list item. You canuse the javascript shorthand notation for object creation to make this easy. For example a basic list item may be expressed as:

{ ID: 8, Title: 'List item title', Description: 'List item description' }

Note that for an update to occur, the ID value must be populated with the id of the target list item. All columns other that the ID will be updated.Columns which are not expressed will be left as they are in the list.

You may also choose to update a number of list items at the same time by passing in an array of objects, each one of which will represent a listitem and contain the appropriate ID. All of the items will then be updated at the same time. If updating of any item fails then processing willcontinue on to the next item. You can use javascript shorthand array notation to make this easy.

[ { ID: 8, Title: 'My new item 3' }, { ID: 9, Title: 'My new item 4' } ]



Code sample

var lists = new SPAPI_Lists('http://localhost')

// Update the title of the item with ID 8 var res = lists.quickUpdateListItem('MyList', { ID: 8, Title: 'Updated title 1' } );

if (res.status == 200) { alert('The list item was updated.'); } else { alert('There was an error: ' + res.statusText); }

// Or to update multiple items....

var lists = new SPAPI_Lists('http://localhost')

// Update the titles of the items with ID 8 and 9 var res = lists.quickUpdateListItem('MyList', [ { ID: 8, Title: 'Updated title 1' }, { ID: 9, Title: 'Updated title 2' } ]);

if (res.status == 200)

{ alert('The list items were updated.'); } else { alert('There was an error: ' + res.statusText); }

References



11- Delete one or more list itemsDeletion of list items is carried out using the UpdateListItems method of the lists web service. This method takes a batch element as a parameter.The batch element contains a field element containing an ID of a list item to delete. The javascript API provides a utility method calledquickDeleteListItem which makes this process a little easier by taking care of the XML batch production automatically.

To use quickDeleteListItem pass in a list name and either a single ID number or array of ID numbers to delete.



Code sample

var lists = new SPAPI_Lists('http://localhost') var res = lists.quickDeleteListItem('MyList', 4);

if (res.status == 200) { alert('The list item was deleted.'); } else { alert('There was an error: ' + res.statusText); }

// Or to delete multiple items....

var lists = new SPAPI_Lists('http://localhost') var res = lists.quickDeleteListItem('MyList', [ 1, 2, 3, 4]);

if (res.status == 200)


6 von 9 21.09.2009 14:44


{ alert('The list items were deleted.'); } else { alert('There was an error: ' + res.statusText); }

References



12- Create a new folder within a listCreation of list folders is carried out using the UpdateListItems method of the lists web service. This method takes a batch element as aparameter. The batch element contains a field element containing the name of the folder and FSObjType of 1 (folder). The javascript API providesa utility method called createFolder which makes this process a little easier by taking care of the XML batch production automatically.

To use createFolder pass in a list name and a new folder name.

If you need to create a folder within a folder simply specify the optional rootFolder parameter. Let’s say you’re creating items in a list calledMyList. There’s a folder in there called Folder1. In Folder1 there’s another folder called Folder2. If you want to create a new folder inside Folder2you set rootFolder to /Lists/MyList/Folder1/Folder2.



Code sample

var lists = new SPAPI_Lists('http://localhost') var res = lists.createFolder('MyList', 'TestFolder2');

if (res.status == 200) { alert('The folder was created.'); } else { alert('There was an error: ' + res.statusText); }

// Or to create a folder within a folder

var lists = new SPAPI_Lists('http://localhost') var res = lists.createFolder('MyList', 'TestFolder2', '/Lists/MyList/TestFolder');

if (res.status == 200) { alert('The folder was created.'); } else { alert('There was an error: ' + res.statusText); }

References


The UpdateListItems method definition on MSDN [27]

13- Performing a keyword searchThe Query Service [28] allows developers to run keyword and SQL queries against a site collection. To do this, a CAML QueryPacket [29] issubmitted to the Query method of the service. This query packet contains the definition of the query. Creation of these packets is simpified in thejavascript API through the SPAPI_QueryPacket in the SPAPI_Types.js library.


Search.asmxSPAPI_Core.jsSPAPI_Search.jsSPAPI_Types.js

Code sample

var lists = new SPAPI_Search('');

// Create the new query // Type = SQL_Query_Type_Keyword // Query = Sharepoint // Fields to return = Title,Path,Description,Write,Rank,Size 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);


7 von 9 21.09.2009 14:44


Article printed from Darren’s SharePoint and .Net blog: http://darrenjohnstone.net

URL to article: http://darrenjohnstone.net/2008/07/22/examples-for-the-sharepoint-and-office-live-javascript-api/

URLs in this post:

[1] Get the full definition of a list: #topic-1[2] Get the full definition of a list and associated view: #topic-2[3] Get the basic detail of all lists in a site: #topic-3[4] Get the GUID of a list from it’s name: #topic-4[5] Querying a list using the Lists web service: #topic-5[6] Querying a list using the List Data Retrieval Service: #topic-6[7] Create a new list from an existing list template: #topic-7[8] Delete a list: #topic-8[9] Create one or more new list items: #topic-9[10] Update one or more list items: #topic-10[11] Delete one or more list items: #topic-11[12] Create a new folder within a list: #topic-12[13] Performing a keyword search: #topic-13[14] Performing a full text search: #topic-14[15] on MSDN: http://msdn.microsoft.com/en-us/library/lists.lists.getlist.aspx[16] Lists.asmx on MSDN: http://msdn.microsoft.com/en-us/library/lists.aspx[17] Result packet from GetList showing the full list definition: http://darrenjohnstone.net/wp-content/jsapi/packets/GetList.xml[18] on MSDN: http://msdn.microsoft.com/en-us/library/lists.lists.getlistandview.aspx[19] Result packet from GetListAndView showing the full list and view definition: http://darrenjohnstone.net/wp-content/jsapi/packets/GetListAndView.xml[20] on MSDN: http://msdn.microsoft.com/en-us/library/lists.lists.getlistcollection.aspx[21] Result packet from GetListCollection showing the full list and view definition: http://darrenjohnstone.net/wp-content/jsapi/packets/GetlistCollection.xml[22] GetListItems method on MSDN: http://msdn.microsoft.com/en-us/library/lists.lists.getlistitems.aspx[23] Sample GetListItems result packet: http://darrenjohnstone.net/wp-content/jsapi/packets/GetListItems.xml[24] List Data Retrieval Service: http://msdn.microsoft.com/en-us/library/ms774413.aspx[25] The AddList method definition on MSDN: http://msdn.microsoft.com/en-us/library/lists.lists.addlist.aspx[26] The DeleteList method definition on MSDN: http://msdn.microsoft.com/en-us/library/lists.lists.deletelist.aspx[27] The UpdateItems method definition on MSDN: http://msdn.microsoft.com/en-us/library/lists.lists.updatelistitems.aspx[28] Query Service: http://msdn.microsoft.com/en-us/library/search.queryservice.aspx[29] QueryPacket: http://msdn.microsoft.com/en-us/library/ms473235.aspx[30] The QueryService on MSDN: http://msdn.microsoft.com/en-us/library/search.queryservice_members.aspx[31] Sample full response packet from the search method: http://darrenjohnstone.net/wp-content/jsapi/packets/QueryResult.xml[32] Sample extracted query result packet from the search method: http://darrenjohnstone.net/wp-content/jsapi/packets/ExtractedQueryResult.xml

Copyright © 2008 Darren Johnstone. All rights reserved.


9 von 9 21.09.2009 14:44

http://darrenjohnstone.net

http://darrenjohnstone.net/2008/07/22/examples-for-the-sharepoint-and-office-live-javascript-api/

http://msdn.microsoft.com/en-us/library/lists.lists.getlist.aspx

http://msdn.microsoft.com/en-us/library/lists.aspx

http://darrenjohnstone.net/wp-content/jsapi/packets/GetList.xml

http://msdn.microsoft.com/en-us/library/lists.lists.getlistandview.aspx

http://darrenjohnstone.net/wp-content/jsapi/packets

http://msdn.microsoft.com/en-us/library/lists.lists.getlistcollection.aspx


http://msdn.microsoft.com/en-us/library/lists.lists.getlistitems.aspx

http://darrenjohnstone.net/wp-content/jsapi/packets/GetListItems.xml

http://msdn.microsoft.com/en-us/library/ms774413.aspx

http://msdn.microsoft.com/en-us/library/lists.lists.addlist.aspx

http://msdn.microsoft.com/en-us/library/lists.lists.deletelist.aspx

http://msdn.microsoft.com/en-us/library/lists.lists.updatelistitems.aspx

http://msdn.microsoft.com/en-us/library/search.queryservice.aspx

http://msdn.microsoft.com/en-us/library/ms473235.aspx

http://msdn.microsoft.com/en-us/library/search.queryservice_members.aspx

http://darrenjohnstone.net/wp-content/jsapi/packets/QueryResult.xml



SharePoint JS API

Documents

Transcript of SharePoint JS API