How to: Retrieve List Items Using JavaScript
Applies to: SharePoint Foundation 2010
To return items from a list using ECMAScript (JavaScript, JScript), use the getItemById(id) function to return a single item, or use the getItems(query) function to return multiple items. You then use the load(clientObject) function to attain list item objects that represent the items.
Retrieving Items from a List Using JavaScript
The getItems(query) function enables you to define a Collaborative Application Markup Language (CAML) query that specifies which items to return. You can pass an undefined CamlQuery object to return all items from the list, or use the set_viewXml function to define a CAML query and return items that meet specific criteria.
The following example displays the ID, in addition to the Title and Body column values, of the first 100 items in the Announcements list, starting with list items whose collection ID is greater than 10.
var siteUrl = '/sites/MySiteCollection';
function retrieveListItems() {
var clientContext = new SP.ClientContext(siteUrl);
var oList = clientContext.get_web().get_lists().getByTitle('Announcements');
var camlQuery = new SP.CamlQuery();
camlQuery.set_viewXml('<View><Query><Where><Geq><FieldRef Name=\'ID\'/>' +
'<Value Type=\'Number\'>1</Value></Geq></Where></Query><RowLimit>10</RowLimit></View>');
this.collListItem = oList.getItems(camlQuery);
clientContext.load(collListItem);
clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
}
function onQuerySucceeded(sender, args) {
var listItemInfo = '';
var listItemEnumerator = collListItem.getEnumerator();
while (listItemEnumerator.moveNext()) {
var oListItem = listItemEnumerator.get_current();
listItemInfo += '\nID: ' + oListItem.get_id() +
'\nTitle: ' + oListItem.get_item('Title') +
'\nBody: ' + oListItem.get_item('Body');
}
alert(listItemInfo.toString());
}
function onQueryFailed(sender, args) {
alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}
The previous example loads the collection of items specified by the CAML query, and all default properties can subsequently be accessed on each list item object that is returned. In ECMAScript (JavaScript, JScript), specify the Include statement as part of the query string that is passed to the load(clientObject) function.
Using the Include Method
Four properties of ListItem objects are not available by default when you return list items—displayName, effectiveBasePermissions, hasUniqueRoleAssignments, and roleAssignments. The previous example returns a PropertyOrFieldNotInitializedException if you try to access one of these properties. To access these properties, use Include as part of the query string. For more information about non-default properties, see Data Retrieval Overview.
To modify the previous example so that it returns the value of displayName and hasUniqueRoleAssignments, you can replace the previous call to the load(clientObject) function with a call that uses a LINQ query. In JavaScript, you specify Include.
Note
When you use LINQ to create queries against the client object model, you are using LINQ to Objects, not the LINQ to SharePoint provider, which can only be used when you write code against the server object model.
var siteUrl = '/sites/MySiteCollection';
function retrieveListItemsInclude() {
var clientContext = new SP.ClientContext(siteUrl);
var oList = clientContext.get_web().get_lists().getByTitle('Announcements');
var camlQuery = new SP.CamlQuery();
camlQuery.set_viewXml('<View><RowLimit>100</RowLimit></View>');
this.collListItem = oList.getItems(camlQuery);
clientContext.load(collListItem, 'Include(Id, DisplayName, HasUniqueRoleAssignments)');
clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
}
function onQuerySucceeded(sender, args) {
var listItemInfo = '';
var listItemEnumerator = collListItem.getEnumerator();
while (listItemEnumerator.moveNext()) {
var oListItem = listItemEnumerator.get_current();
listItemInfo += '\nID: ' + oListItem.get_id() +
'\nDisplay name: ' + oListItem.get_displayName() +
'\nUnique role assignments: ' + oListItem.get_hasUniqueRoleAssignments();
}
alert(listItemInfo.toString());
}
function onQueryFailed(sender, args) {
alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}
Because this example uses an Include, only the specified properties are available after query execution. Therefore, you receive a PropertyOrFieldNotInitializedException if you try to access other properties beyond those that have been specified. In addition, you receive this error if you try to use functions such as get_contentType) or get_parentList) to access the properties of containing objects.
Restrictions on Retrieving List Items
The loadQuery(clientObjectCollection, exp) method of the JavaScript object model in Microsoft SharePoint Foundation 2010 does not support LINQ methods and operators that are used by the managed object model.
See Also
Concepts
SharePoint 2010 Client Object Model Guidelines
How to: Create, Update, and Delete List Items Using JavaScript
Common Programming Tasks in the JavaScript Object Model