ShareCoffee.CrossDomain

CSOM

When you're creating an Auto-Hosted or a Provider-Hosted App it may be a little bit tricky to interact with the AppWeb or the HostWeb. ShareCoffee is offering a wrapper to make these interactions easier for you.

load SharePoint's CrossDomain library

In order to work with ShareCoffee.CrossDomain wrapper, you've to explicitly reference Microsoft.Ajax.js because SP.Runtime.js and SP.js are relying on this library. After adding the reference to your page you can load SharePoint's CrossDomain libraries by calling

ShareCoffee.CrossDomain.loadCSOMCrossDomainLibrary(onSuccess, onError);

Once the required scripts are loaded from SharePoint, you can start using ShareCoffee's CrossDomain library.

Accessing the AppWeb

Remember that Provider-Hosted Apps don't have an AppWeb until you create it explicitly (Adding any kind of SP-I to the AppWeb).

In order to get the ClientContext you just have to call

var ctx = ShareCoffee.CrossDomain.getClientContext();
// continue with common CSOM here
var lists = ctx.get_web().get_lists();
ctx.load(lists);
// ...

Accessing the HostWeb

Accessing the HostWeb is quiet easy. But you've to request the permissions within the AppManifest!! Once this is done, you can use ShareCoffee to get the HostWeb.

var ctx = ShareCoffee.CrossDomain.getClientContext();
var hostWeb = ShareCoffee.CrossDomain.getHostWeb(ctx);
var blogWebUrl = ShareCoffee.Commons.getHostWebUrl() + "/blog";
var blogWeb = ShareCoffee.CrossDomain.getHostWeb(ctx, blogWebUrl);
// continue with common CSOM here
var lists = hostWeb.get_lists();
var blogLists = blogWeb.get_lists();

ctx.load(lists);
ctx.load(blogLists);
// ...

REST Services

load SharePoint's CrossDomain library

In order to work with ShareCoffee.CrossDomain wrapper, you've to explicitly load SharePoint's CrossDomain libraries by calling

ShareCoffee.CrossDomain.loadCrossDomainLibrary(onSuccess, onError);

Once the required scripts are loaded from SharePoint, you can start using ShareCoffee's CrossDomain library.

HostWeb - AppWeb

SharePoint's SP.RequestExecutor is acting a little bit different. You've to explicitly create a new instance of SP.RequestExecutor and pass the AppWebUrl. When using ShareCoffee.CrossDomain.build.for.SPCrossDomainLib() methods you can specify the HostWebUrl, if present, ShareCoffee will configure the request to interact with the HostWeb instead of interacting with the AppWeb. (Again, remember to request the Permissions within the AppManifest)

Configuring Requests

Each of the following methods is configured by a single parameter of type ShareCoffee.CrossDomain.SharePointRestProperties. You can either create a new instance by using the constructor ShareCoffee.CrossDomain.SharePointRestProperties() or you can pass a JSON object with corresponding properties.

/// Create property-object by using the constructor
var properties = new ShareCoffee.CrossDomain.SharePointRestProperties(url, payload, hostWebUrl, eTag, onSuccess, onError);
/// Create a property-object by using JSON syntax
var properties2 = { url: 'web/title')

Reading Elements using ShareCoffee.CrossDomain.build.read.for.SPCrossDomainLib()

description: TODO

Usage

var executor = new SP.RequestExecutor(ShareCoffee.Commons.getAppWebUrl());
executor.executeAsync(ShareCoffee.CrossDomain.build.read.for.SPCrossDomainLib({url:"web/lists/?$select=Title,Id", onSuccess: onListsLoaded, onError: onError}));

Creating Elements using ShareCoffee.CrossDomain.build.create.for.SPCrossDomainLib()

description: TODO

Usage

 var payload = {
   '__metadata': { 'type': 'SP.List' },
   'AllowContentTypes': true,
   'BaseTemplate': 100,
   'ContentTypesEnabled': true,
   'Description': 'My list created by REST',
   'Title': "Thorstens List"
 };
 var executor = new SP.RequestExecutor(ShareCoffee.Commons.getAppWebUrl());
 executor.executeAsync(ShareCoffee.CrossDomain.build.create.for.SPCrossDomainLib({url: "web/lists/", 
   onSuccess: onListCreated,
   onError: onError,
   payload: payload}));

Updating Elements using ShareCoffee.CrossDomain.build.update.for.SPCrossDomainLib()

description: TODO

Usage

 var payload = {
   '__metadata': { 'type': 'SP.List' },
   'Title': 'CHANGED BY REST - Thorstens list'
 };
 var executor = new SP.RequestExecutor(ShareCoffee.Commons.getAppWebUrl());
 executor.executeAsync(ShareCoffee.CrossDomain.build.update.for.SPCrossDomainLib({ url: "web/lists('" +   customListId + "')",
   onSuccess: onListUpdated,
   onError: onError
   payload: payload})); 

Deleting Elements using ShareCoffee.CrossDomain.build.delete.for.SPCrossDomainLib()

description: TODO

Usage

var executor = new SP.RequestExecutor(ShareCoffee.Commons.getAppWebUrl());
executor.executeAsync(ShareCoffee.CrossDomain.build.delete.for.SPCrossDomainLib({url: "web/lists('" + customListId + "')",
  onSuccess: onListDeleted,
  onError: onError}));