SharePoint 2013 / 15: Complete basic operations using JavaScript library code in SharePoint 2013

In this article

SharePoint 2013 client APIs
Perform basic tasks in SharePoint 2013 using the JavaScript client object model
SharePoint website tasks
SharePoint list tasks
Create, update, and delete lists
Create, update, and delete folders
Create, read, update, and delete files
SharePoint list item tasks
Create, update, and delete list items
Access objects in the host web
Additional resources

You can use the SharePoint client object model to retrieve, update, and manage data in SharePoint 2013. SharePoint makes the object model available in several forms.

.NET Framework redistributable assemblies
JavaScript library
REST/OData endpoints
Windows Phone assemblies
Silverlight redistributable assemblies

The following sections describe tasks that you can complete programmatically, and they include JavaScript code examples that demonstrate the operations.
When you create a cloud-hosted add-in, you can add a reference to the object model by using HTML <script> tags. We recommend that you reference the host web because the add-in web may not exist in every scenario in cloud-hosted add-ins. You can retrieve the host web URL from the SPHostUrl query string parameter if you are using the {StandardTokens} token. You can also use your custom defined query string parameter if you are using the {HostUrl} token. After you have the host web URL, you must use JavaScript code to dynamically create the reference to the object model.
The following code example performs these tasks to add a reference to the JavaScript object model:

References the AJAX library from the Microsoft Content Delivery Network (CDN).
References the jQuery library from the Microsoft CDN.
Extracts the host web URL from the query string.
Loads the SP.Runtime.js and SP.js files by using the getScript function in jQuery. After loading the files, your program has access to the JavaScript object model for SharePoint.
Continues the flow in the execOperation function.

References the AJAX library from the Microsoft CDN.
References the SP.Runtime.js file by using a URL relative to the add-in web.
References the SP.js file by using a URL relative to the add-in web.

Use the Include method to access properties of ListItem objects

Four properties of ListItem objects are not available by default when you return list items—displayName, effectiveBasePermissions, hasUniqueRoleAssignments, and roleAssignments. The previous example returns a PropertyOrFieldNotInitializedException if you try to access one of these properties. To access these properties, use the Include method as part of the query string, as shown in the following example.

function retrieveListItemsInclude(siteUrl) {
    var clientContext = new SP.ClientContext(siteUrl);
    var oList = clientContext.get_web().get_lists().getByTitle('Announcements');
    var camlQuery = new SP.CamlQuery();
    camlQuery.set_viewXml('<View><RowLimit>100</RowLimit></View>');
    this.collListItem = oList.getItems(camlQuery);
    clientContext.load(
        collListItem,
        'Include(Id, DisplayName, HasUniqueRoleAssignments)'
    );
    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded),
        Function.createDelegate(this, this.onQueryFailed)
    );
}
function onQuerySucceeded(sender, args) {
    var listItemInfo = '';
    var listItemEnumerator = collListItem.getEnumerator();

    while (listItemEnumerator.moveNext()) {
        var oListItem = listItemEnumerator.get_current();
        listItemInfo += '\nID: ' + oListItem.get_id() +
            '\nDisplay name: ' + oListItem.get_displayName() +
            '\nUnique role assignments: ' +
            oListItem.get_hasUniqueRoleAssignments();
    }
    alert(listItemInfo.toString());
}
function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() +
        '\n' + args.get_stackTrace());
}

Create a list item

function createListItem(siteUrl) {
    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());
}

Update a list item

function updateListItem(siteUrl) {
    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());
}

Delete a list item

function deleteListItem(siteUrl) {
    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.

function deleteListItemDisplayCount(siteUrl) {
    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());
}

While developing your add-in, you might need to access the host web to interact with items in it. Use the AppContextSite object to reference the host web or other SharePoint sites, as shown in the following example. For a full code sample, see Get the host web title using the cross-domain library (JSOM).

function execCrossDomainRequest(appweburl, hostweburl) {
    // context: The ClientContext object provides access to
    //      the web and lists objects.
    // factory: Initialize the factory object with the
    //      add-in web URL.
    var context;
    var factory;
    var appContextSite;
    context = new SP.ClientContext(appweburl);
    factory = new SP.ProxyWebRequestExecutorFactory(appweburl);
    context.set_webRequestExecutorFactory(factory);
    appContextSite = new SP.AppContextSite(context, hostweburl);
    this.web = appContextSite.get_web();
    context.load(this.web);
    // Execute the query with all the previous
    // options and parameters.
    context.executeQueryAsync(
        Function.createDelegate(this, successHandler),
        Function.createDelegate(this, errorHandler)
    );
    // Function to handle the success event.
    // Prints the host web's title to the page.
    function successHandler() {
        alert(this.web.get_title());
    }
    // Function to handle the error event.
    // Prints the error message to the page.
    function errorHandler(data, errorCode, errorMessage) {
        alert("Could not complete cross-domain call: " + errorMessage);
    }
}

SharePoint 2013 / 15

Monday, 7 September 2015

Complete basic operations using JavaScript library code in SharePoint 2013

Use the Include method to access properties of ListItem objects

No comments:

Post a Comment