Updated Wiki: $().SPServices.SPGetListItemsJson

Function

Certification

Functionality

SPGetListItemsJson combines several SPServices capabilities into one powerful function. By calling GetListItemChangesSinceToken, parsing the list schema, and passing the resulting mapping and data to SPXmlToJson automagically, we have a one-stop shop for retrieving SharePoint list data in JSON format. No manual mapping required!

Prerequisites

None

Syntax

$().SPServices.SPGetListItemsJson({
  webURL: "",
  listName: "",
  CAMLViewName: "",
  CAMLQuery: "",
  CAMLViewFields: "",
  CAMLRowLimit: "",
  CAMLQueryOptions: "",
  changeToken: "",
  contains: "",
  mapping: null,
  mappingOverrides: null,
  debug: false
});

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 which contains the parent/child relationships. 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 thewebURL 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>"

See the MSDN documentation for GetListItemsChangesSinceToken for the syntax.

CAMLViewFields 
If specified, only the columns in CAMLViewFields plus some other required columns are retrieved. This can be very important if your list has a lot of columns, as it can reduce the amount of data returned from the call. See the MSDN documentation for GetListItemsChangesSinceToken for the syntax.

CAMLRowLimit
This option can be used to limit the number of items retrieved from the list. See the MSDN documentation for GetListItemsChangesSinceToken for the syntax.

CAMLQueryOptions
This option can be used to specify additional options for retrieval from the list. See the MSDN documentation for GetListItemsChangesSinceToken for the syntax.

changeToken 
GetListItemChangesSinceToken passes back a changeToken on each call. If you are making calls after the initial one and pass in thechangeToken value, only the changes since that token will be retrieved. See the MSDN documentation for GetListItemsChangesSinceToken for the syntax.

contains
This option allows you to pass in an additional filter for the request. It should be a valid CAML clause. See the MSDN documentation for GetListItemsChangesSinceToken for the syntax.

mapping
If you have created your own mapping, as specified in SPXmltoJson, pass it as this option. If present, the function will use your mapping and ignore the list schema returned by GetListItemChangesSinceToken.

mappingOverrides
If you want the function to use the list schema returned by GetListItemChangesSinceToken for the majority of the columns but you would like to specify your own mapping for some of the columns, pass those mappings in using themappingOverrides option.

As an example, this mappingOverride would only change the way the two specified columns are converted by the SPXmlToJson function internally in the call (the JSONobjectType is not available from the list schema):

mappingOverrides: {
  ows_FiscalPeriodData: {
    mappedName: "FiscalPeriodData",
    objectType: "JSON"
  },
  ows_FiscalPeriodNames: {
    mappedName: "FiscalPeriodNames",
    objectType: "JSON"
  }
} 

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.