SharePoint Data Service Adapter

Provides BreezeJS support for SharePoint 2010 & 2013+ (including SharePoint Online in Office 365).

The breeze labs github repo holds the latest official release.

See Andrew Connell's on-going blog posts for the latest information and indepth discussion of Breeze/Angular/SharePoint/Office365 development, including future plans & milestones.

Installation

The Breeze data service adapter for SharePoint is provided as a single NuGet Package that includes everything you need to use it in a SharePoint 2010 or 2013+ project.

Install-Package "Breeze.DataService.SharePoint"

Setup

1. Add the necessary Breeze JavaScript libraries to the server.
2. Configure BreezeJS SharePoint data service adapter
3. Create & populate the BreezeJS metadata store
4. Initialize BreezeJS

Step 1 - Add necessary JavaScript Library References

<script src="https://github.com/Breeze/breeze.js.labs/raw/1.5.11/breeze.debug.js" type="application/javascript"></script>


<script src="https://github.com/Breeze/breeze.js.labs/raw/1.5.11/breeze.bridge.angular.js" type="application/javascript"></script>


<script src="https://github.com/Breeze/breeze.js.labs/raw/1.5.11/breeze.metadata-helper.js" type="application/javascript"></script>
<script src="https://github.com/Breeze/breeze.js.labs/raw/1.5.11/breeze.labs.dataservice.abstractrest.js" type="application/javascript"></script>
<script src="https://github.com/Breeze/breeze.js.labs/raw/1.5.11/breeze.labs.dataservice.sharepoint.js" type="application/javascript"></script>

Step 2 - Configure SharePoint Data Service Adapter

For SharePoint 2013+, either on-premises deployments or SharePoint Online deployments in Office 365, use the following code to configure the SharePoint 2013+ data service adapter:

````javascript // configure breeze to use SharePoint OData service var dsAdapter = breeze.config.initializeAdapterInstance('dataService', 'SharePointOData', true);

// tell breeze how to get the security validation token // for HTTP POST & DELETE calls // NOTE: Setting the request digest is not required when using OAuth tokens // for authentication. The request digest is used when cookies are used for // authentication to protect against XSRF. When OAuth tokens are used, there // is no XSRF issue as there are no cookies. Version 0.6.3 of the adapter // added conditional logic to omit the X-RequestDigest header in the HTTP // request if this method is not set. dsAdapter.getRequestDigest = function () { return jQuery('#__REQUESTDIGEST').val(); }; ````

For SharePoint 2010, use the following code to configure the SharePoint 2010 data service adapter (note the name of the adapter):

javascript // configure breeze to use SharePoint OData service var dsAdapter = breeze.config.initializeAdapterInstance('dataService', 'SharePointOData2010', true);

Step 3 - Create & Populate the BreezeJS Metadata Store

// create a new breeze metadata store
metadataStore = new breeze.MetadataStore();

// setup a helper to create entities
var namespace = '';
var helper = new breeze.config.MetadataHelper(namespace,
                                              breeze.AutoGeneratedKeyType.Identity);

// create entity for contacts
var contactEntity = {
  name: 'Contacts',
  // the defaultResourceName endpoint will vary based on the entity endpoint & SharePoint version
  defaultResourceName: 'getbytitle(\'Contacts\')/items',
  dataProperties: {
    Id: { type: breeze.DataType.Int32 },
    FirstName: { nullable: false },
    Title: { nullable: false },
    Email: {
      nullable: false,
      validators: [breeze.Validator.emailAddress()]
    }
  }
};

// add entity to metadata store
helper.addTypeToStore(metadataStore, contactEntity);

Note that it is very important that the name of the entity matches exactly the name of the SharePoint list the entity is coming from. If it doesn't Breeze will not be able to associate data from an HTTP GET it makes with the entity defined in the metadata store.

Step 4 - Initialize BreezeJS

// get reference to contact entity type
contactType = metadataStore.getEntityType('Contacts');

// create the data service
var dataService = new breeze.DataService({
  // tell breeze the root REST endpoint to use
  //  since we only are using lists, point to that
  // NOTE this will depend on the SharePoint version - for instance the
  //  _spPageContextInfo object is only present in SharePoitn 2013
  //  and the '/_api/' endpoint is only used in SharePoint 2013 while
  //  '/_vti_bin/listdata.svc' is used in SharePoint 2010
  serviceName: _spPageContextInfo.webAbsoluteUrl + '/_api/web/lists/',
  // tell breeze not to interrogate sharepoint for it's
  //  massive OData $metadata response... we created it manually
  hasServerMetadata: false
});

// create an instance of the entity manager
entityManager = new breeze.EntityManager({
  dataService: dataService,
  // tell breeze where the metadata is
  metadataStore: metadataStore
});

Reference Examples

• BreezeSP2013Sample: Demonstrates usage within SharePoint 2013. This sample is a SharePoint Hosted App which can be used in either an on-premises or Office 365 deployment.
• BreezeSP2010Sample: Demonstrates usage within SharePoint 2010. This sample is a fully-trusted farm solution.

Supported SharePoint Versions

• SharePoint 2013
• Office 365 / SharePoint Online: RTM -> present version
• SharePoint 2013 On-Premises: RTM -> present version
• SharePoint 2010
• Data service adapter v0.7.0
• SharePoint 2007
• Support not planned

Supported SharePoint Versions

• All evergreen browsers (Chrome, Firefox)
• Internet Explorer 9+

References

• Documentation on the BreezeJS site for more information & background: BreezeJS.com - SharePoint SPA
• Andrew Connell's session on using BreezeJS with SharePoint: BreezeJS Makes Client-Side SharePoint 2013 REST Development a... BREEZE!.