Function

$().SPServices.SPUpdateMultipleListItems

Certification

Certified for SharePoint 2007 Certified for SharePoint 2010

Functionality

SPUpdateMultipleListItems allows you to update multiple items in a list based upon some common characteristic or metadata criteria.

IMPORTANT NOTE: The first iterations of this function only worked with lists, not Document Libraries. As of v0.6.1, it works with Document libraries as well.

How Does It Work?

The SPUpdateMultipleListItems function works like this:

  • It first calls GetListItems with the provided CAMLQuery to find all off the items which meet the criteria
  • Then the function calls UpdateListItems and updates all of the items found with the values provided

Prerequisites

None

Syntax

$().SPServices.SPUpdateMultipleListItems({
webURL: "",
listName: "",
CAMLQuery: "",
batchCmd: "Update",
valuepairs: [],
debug: false, completefunc: null
});

webURL
The URL of the Web (site) which contains the list. If not specified, the current site is used. Examples would be: "/", "/Accounting", "/Departments/HR", etc. Note: It's always best to use relative URLs.

listName
The name or GUID of the list. If you choose to use the GUID, it should look like: "{E73FEA09-CF8F-4B30-88C7-6FA996EE1706}". Note also that if you use the GUID, you do not need to specify the webURL if the list is in another site.

CAMLQuery
The CAMLQuery option allows you to specify the filter on the list. CAMLQuery here should contain valid CAML such as:

CAMLQuery: "<Query><Where><Eq><FieldRef Name='Status'/><Value Type='Text'>Active</Value></Eq></Where></Query>"

batchCmd
The batchCmd option specifies what the action should be. The choices are Update or Delete. Update is the default.

completefunc
If specified, the completefunc will be called each time there is a change to parentColumn. Potential uses for the completefunc: consistent default formatting overrides, additional lookup customizations, image manipulations, etc. You can pass your completefunc in either of these two ways:

completefunc: function() {
  ...do something...
},
or
completefunc: doSomething,                  // Where doSomething is the name of your function

 

debug
Setting debug: true indicates that you would like to receive messages if anything obvious is wrong with the function call, like using a column name which doesn't exist. I call this debug mode.
NOTE: Debug mode is not implemented in the initial release of SPUpdateMultipleListItems in v0.5.8.

Examples

$().SPServices.SPUpdateMultipleListItems({
  listName: "States",
  CAMLQuery: "<Query><Where><Eq><FieldRef Name='Status'/><Value Type='Text'>Active</Value></Eq></Where></Query>",
  valuepairs: [["Status", "Inactive"]]
}); 

This call to SPUpdateMultipleListItems will update all of the items in the States list which have their Status = "Active", setting their Status = "Inactive".

$().SPServices.SPUpdateMultipleListItems({
  listName: "States",
  CAMLQuery: "<Query><Where><Eq><FieldRef Name='Status'/><Value Type='Text'>Inactive</Value></Eq></Where></Query>",
  batchCmd: "Delete"
});

This call to SPUpdateMultipleListItems will delete all of the items in the States list which have their Status = "Inactive".

Last edited Jan 26 at 6:37 PM by sympmarc, version 12

Comments

jrichview Sep 18, 2013 at 2:50 PM 
Looking for example of what is passed to the completefunc. I need to log the updates it makes.

DavidGardner Aug 26, 2013 at 3:50 PM 
hi, i would like to use this function when i click save on a NewForm....where to i place the code?

samanchi Mar 2, 2013 at 7:10 AM 
valuepairs:[["Status","Inactive"]] is not working if Status is Multiple Lines item... Any solution towards this is gr8ly appreciated....

SPTechQ Jun 25, 2012 at 6:42 PM 
Question - I have a custom form on which I have added two Data View's. The first "Data View" gets data as "Single Item Form" from LIST_1 and the second gets data as "Single Item Form" also but from LIST_2.

I will let the user make changes to the data in both the lists.

My question is, can I call the "SPServices.SPUpdateMultipleListItems" two times on the same page so that I can update the two seperate lists one by one ?

Thanks.

SPTechQ Jun 25, 2012 at 6:27 PM 
In your second sample example, I believe you have an error. The CAML query will description should be "This call to SPUpdateMultipleListItems will update all of the items in the States list setting their Status = "Inactive". Is that right ?

sympmarc Nov 24, 2010 at 11:18 AM 
crusu: Thanks for the comment. If you get a chance, I'd appreciate some details on what you mean by the observation in case there's something I can improve. Please use the Discussions in general for this, as there's no alerting here on the Wiki pages. M.

crusu Nov 24, 2010 at 9:34 AM 
I've just used SPUpdateMultipleListItems in a script to update a Infopath form library hosted in SharePoint 2010. It worked, with a little observation: the default view is inactive (it means it isn't displayed),
Thank you for this great contribution.