Sharepoint 2013 : Overview of The Client-Side Object Model and Rest APIs - JAVASCRIPT (part 2) - Querying

Querying

Similarly to the Managed CSOM, the JS CSOM also includes built-in batching and filtering. These features are especially important in client applications where the browser executing the code is always remote and often on an unknown quality of connection. To ensure your application stays responsive and fast you must take measures to make as few requests as possible and only return the data you really need.

Prior to making any requests you must set up a ClientContext. To get the context associated with the site and page the script is running on, use the get_Current() method:

var clientContext = context = new SP.ClientContext.get_current();

You can then start requesting data. One of the simplest requests you can make is for the information about the site, like so:

var web;
web = clientContext.get_web();
clientContext.load(web);

Now you are ready to make the request to the server. Because you don’t want to block the application thread processing while this potentially long-running task is in progress, you provide callback functions that will be called either after the operation completes or if an error occurs.

To do this, make a call to executeQueryAsync like this:

clientContext.executeQueryAsync(
        myQuerySucceeded, 
        myQueryFailed);

In the myQuerySucceeded function you can start using the objects you asked for:

function onQuerySucceeded() {alert(this.web.Title);}

Additionally, your application should be able to handle when errors occur. This might be due to connectivity issues, for example, like the following:

function myQueryFailed(sender, args) {alert('Call to SharePoint failed :(');}

When querying lists and libraries you have the choice of querying for a specific item whose ID you already know using the getItemById(id) method, or with a query using the getItems(query) method. The latter is slightly more complex in that you need to set up the query against that list using CAML syntax. The following sample code shows querying a simple list for all items whose Title column equals “Foo”:

    var list = listContext.get_web().get_lists().getByTitle('My Custom List');
    
    var camlQuery = new SP.CamlQuery();
 
    camlQuery.set_viewXml(
    '<View><Query><Where><Eq><FieldRef Name=\'Title\'/>' + 
    '<Value Type=\'Text\'>New Item 1</Value></Eq></Where></Query>' + 
    '<RowLimit>10</RowLimit></View>' );
 
    items = list.getItems(camlQuery);
 
    context.load(items);
    context.executeQueryAsync(myQuerySucceeded, myQueryFailed);

You can use the CAML query to carefully construct the exact query against the list you want to make and also the data you want to bring back.

To create and manipulate list items, use the ListItemCreationInformation object as shown in the following code example. This gives you a context object that allows you set up the item prior to sending it to the server along with the data you want to create:

var newListItem;
 
function createItems()
{
    var listContext = new SP.AppContextSite(context, hostUrl);
    var list = listContext.get_web().get_lists().getByTitle('My Custom List');
    
    var itemCreateInfo = new SP.ListItemCreationInformation();
    newListItem = list.addItem(itemCreateInfo);
         newListItem.set_item('Title', 'Created via JS CSOM!');
         newListItem.update();
         context.load(newListItem);
         context.executeQueryAsync(onCreateListItemsSuccess,onCreateListItemsFail);
         }
 
function onCreateListItemsSuccess() {
    alert('New ListItem created: ' + newListItem.get_id());
}
 
// This function is executed if the above call fails
function onCreateListItemsFail(sender, args) {
    alert('Failed to create list item. Error:' + args.get_message());
}

For updates you simply get the list item in question, make the update to the data, and then call update() on it like so:

var listItem = list.getItemById(1);
listItem.set_item('Title', 'Updated via JS CSOM');
listItem.update();

You can try out these APIs and techniques in the following exercise to get a better feel for how they work with SharePoint Online using the new Napa developer tools.