Version

Getting items from a list using a query

Overview

The List.getItemsWithOptions JavaScript API method allows you to retrieve the items from a SharePoint list from the server, also specifying a custom Object to query the list. The Array of items retrieved is returned to the success callback function. These items are Objects whose properties correspond to the requested fields.

Code

Before calling the List.getItemsWithOptions API method, you need to get ready the following parameters:

  • URL to the SharePoint site.

  • Custom JavaScript Object with information to be used to query to the SharePoint list.

You need to use the Query schema of CAML to define queries against the contents of a SharePoint list.

The structure of the options Object is the following:

Property

Type

Description

viewName

String

Name of the SharePoint List view.

fields

Array

Array of field values to be retrieved for each item.

where

String

Where condition used in the query.

orderBy

String

OrderBy condition used in the query.

queryOptions

XML node

XML node with several properties used in the query

The code for specifying the url and options Object should be similar to the following code snippet:

var listUrl = 'http://spdemo.infragistics.com/demo/Lists/Team%20Discussion';

var options = new Object();
options.viewName = 'All Documents';
options.fields = ['ows_Title', 'ows_Created'];
options.where = '<Or>' +
                    '<Contains>' +
                            '<FieldRef Name="FileLeafRef"/>' +
                            '<Value Type="File">SharePlus</Value>'+
                    '</Contains>' +
                    '<Contains>' +
                            '<FieldRef Name="FileLeafRef"/>' +
                            '<Value Type="File">ReportPlus</Value>'+
                    '</Contains>' +
               '</Or>';
options.orderBy = '<FieldRef Name="FileSizeDisplay"></FieldRef>';
options.queryOptions = '<QueryOptions>' +
                            '<IncludeMandatoryColumns>TRUE</IncludeMandatoryColumns>' +
                            '<DateInUtc>TRUE</DateInUtc>' +
                       '</QueryOptions>';

For further details, see the Lists.GetListItems Method MSDN topic.

You are now ready to call the List.getItemsWithOptions API method. Your code should be similar to the following code snippet:

SPlus.List.getItemsWithOptions (listUrl, options, function (items) {
    //Loop the items Array
    for (var i=0; i < items.length; i++) {
        //Getting a JSON object with the requested fields (item)
        var item = items[i];
        //Getting the fields for an item
        var title = item['ows_Title#displayValue'];
        var body = item['ows_Body#displayValue'];
        var created = item['ows_Created#displayValue'];
        // TODO: Display the items somewhere
    }
}, function (errorResponse) {
    SPlus.Utility.showMessage('Get Items Error',errorResponse['error#displayValue']);
    //TODO: Implement how to handle errors
}, function (cancelResponse) {
        //TODO: Implement how to handle a user’s cancel
});
Note
NOTE

The List.getItemsWithOptions method returns items directly from the SharePoint server. It does NOT take into account offline changes not yet impacted to the server.