How to: Create, Update, and Delete List Items Using JavaScript
Applies to: SharePoint Foundation 2010
Creating, updating, or deleting list items through the client object model works similarly to performing these tasks through the server object model. You create a list item object, set its properties, and then update the object. To modify or delete a list item object, use the getById(id) function of the ListItemCollection object to return the object, and then either set properties and call update on the object that this method returns, or call the object's own method for deletion. Unlike the server object model, each of these operations in the client object model must conclude with a call to executeQueryAsync(succeededCallback, failedCallback) for changes to take effect on the server.
Creating a List Item Using ECMAScript (JavaScript, JScript)
To create list items, you create a ListItemCreationInformation object, set its properties, and pass it as parameter to the addItem(parameters) function of the List object. Set properties on the list item object that this method returns, and then call the update() function, as seen in the following example.
var siteUrl = '/sites/MySiteCollection';
function createListItem() {
var clientContext = new SP.ClientContext(siteUrl);
var oList = clientContext.get_web().get_lists().getByTitle('Announcements');
var itemCreateInfo = new SP.ListItemCreationInformation();
this.oListItem = oList.addItem(itemCreateInfo);
oListItem.set_item('Title', 'My New Item!');
oListItem.set_item('Body', 'Hello World!');
oListItem.update();
clientContext.load(oListItem);
clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
}
function onQuerySucceeded() {
alert('Item created: ' + oListItem.get_id());
}
function onQueryFailed(sender, args) {
alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}
Because the previous example creates a standard list item, you do not need to set properties on the ListItemCreationInformation object before it is passed to the addItem(parameters) function. However, if your code must create a new folder, for example, you must set the underlyingObjectType function of the ListItemCreationInformation object to folder.
Updating a List Item Using JavaScript
To set most list item properties, you can use a column indexer to make an assignment, and call the update() function so that changes will take effect when you call executeQueryAsync(succeededCallback, failedCallback). The following example sets the title of the third item in the Announcements list.
var siteUrl = '/sites/MySiteCollection';
function updateListItem() {
var clientContext = new SP.ClientContext(siteUrl);
var oList = clientContext.get_web().get_lists().getByTitle('Announcements');
this.oListItem = oList.getItemById(3);
oListItem.set_item('Title', 'My Updated Title');
oListItem.update();
clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
}
function onQuerySucceeded() {
alert('Item updated!');
}
function onQueryFailed(sender, args) {
alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}
Deleting a List Item Using JavaScript
To delete a list item, call the deleteObject() function on the object. The following example uses the getItemById(id) function to return the second item from the list, and then deletes the item.
SharePoint Foundation 2010 maintains the integer IDs of items within collections, even if they have been deleted. So, for example, the second item in a list might not have 2 as its identifier. A ServerException is returned if the deleteObject() function is called for an item that does not exist.
var siteUrl = '/sites/MySiteCollection';
function deleteListItem() {
this.itemId = 2;
var clientContext = new SP.ClientContext(siteUrl);
var oList = clientContext.get_web().get_lists().getByTitle('Announcements');
this.oListItem = oList.getItemById(itemId);
oListItem.deleteObject();
clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
}
function onQuerySucceeded() {
alert('Item deleted: ' + itemId);
}
function onQueryFailed(sender, args) {
alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}
If you want to retrieve, for example, the new item count that results from a delete operation, include a call to the update() method to refresh the list. In addition, you must load either the list object itself or the itemCount property on the list object before executing the query. If you want to retrieve both a start and end count of the list items, you must execute two queries and return the item count twice, as shown in the following modification of the previous example.
var siteUrl = '/sites/MySiteCollection';
function deleteListItemDisplayCount() {
this.clientContext = new SP.ClientContext(siteUrl);
this.oList = clientContext.get_web().get_lists().getByTitle('Announcements');
clientContext.load(oList);
clientContext.executeQueryAsync(Function.createDelegate(this, this.deleteItem), Function.createDelegate(this, this.onQueryFailed));
}
function deleteItem() {
this.itemId = 58;
this.startCount = oList.get_itemCount();
this.oListItem = oList.getItemById(itemId);
oListItem.deleteObject();
oList.update();
clientContext.load(oList);
clientContext.executeQueryAsync(Function.createDelegate(this, this.displayCount), Function.createDelegate(this, this.onQueryFailed));
}
function displayCount() {
var endCount = oList.get_itemCount();
var listItemInfo = 'Item deleted: ' + itemId +
'\nStart Count: ' + startCount + ' End Count: ' + endCount;
alert(listItemInfo)
}
function onQueryFailed(sender, args) {
alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}
See Also
Concepts
SharePoint Client Object Creation
SharePoint 2010 Client Object Model Guidelines
How to: Retrieve List Items Using JavaScript
Common Programming Tasks in the JavaScript Object Model