BreezeJS makes client-side SharePoint REST dev easy.

In this article, I want to introduce you to BreezeJS - a library very much like Entity Framework, but for client-side solutions.

by Andrew Connell
Last updated March 4, 2014
6 minutes read

This post is part of a series I’ve written on using the popular Breeze JavaScript library with the SharePoint REST API. The other posts in this series can be found here:
Simplify SharePoint (2013-present) REST queries BreezeJS

SharePoint 2013 REST API with jQuery

One of the downsides though is that you generally have to write a lot more plumbing.

SharePoint 2013 REST API - SELECT ALL

Here’s what a request looks like for a bunch of items in a list using jQuery and the REST API:

// get multiple items
var requestUri = _spPageContextInfo.webAbsoluteUrl +
    '/_api/Web/Lists/getByTitle(\'Contacts\')/items/' +
    '?$select=Id,FirstName,Title,Email'

// execute AJAX request
var requestHeaders = {
  'accept': 'application/json;odata=verbose'
};

$.ajax({
  url: requestUri,
  contentType: 'application/json;odata=verbose',
  headers: requestHeaders,
  success: function (response){ /* do something on success */ },
  error: function(error){ /* do something on fail */ }
});

SharePoint 2013 REST API - SELECT ONE

Here’s what a request looks like for a simple select of one item in a list using jQuery and the REST API:

// get one item
var requestUri = _spPageContextInfo.webAbsoluteUrl +
    '/_api/Web/Lists/getByTitle(\'Contacts\')/items/' +
    '?$select=Id,FirstName,Title,Email' +
    '&$filter=Id eq 1'

// execute AJAX request
var requestHeaders = {
  'accept': 'application/json;odata=verbose'
};

### SharePoint 2013 REST API - UPDATE ITEM

And here’s what an update looks like:

```javascript
// update an item
var requestUri = _spPageContextInfo.webAbsoluteUrl +
          '/_api/Web/Lists/getByTitle(\'Contacts\')/items(1)';

var requestHeaders = {
  'Accept': 'application/json;odata=verbose',
  'X-RequestDigest': $('#__REQUESTDIGEST').val(),
  'X-HTTP-Method': 'MERGE',
  'If-Match': etag
};

var customerData = {
  __metadata: { 'type': 'SP.Data.ContactsListItem' },
  Title: 'NewName',
};

requestBody = JSON.stringify(customerData);

$.ajax({
  url: requestUri,
  type: 'POST',
  contentType: 'application/json;odata=verbose',
  headers: requestHeaders,
  data: JSON.stringify(customerData);
  success: function (response){ /* do something on success */ },
  error: function(error){ /* do something on fail */ }
});

Introducing BreezeJS

Allow me to introduce you to a slick client-side library: Breeze! In a nutshell, Breeze is Entity Framework in the client… or to the non-Microsoft developer, it’s a client-side ORM.

Selecting Items From a List with Breeze

To start, let’s compare the SELECT ALL above… here’s how I’d write the exact same thing with Breeze:

breeze.EntityQuery
  .from(contactType.defaultResourceName)
  .using(entityManager)
  .execute()
  .then(function (response) {
    var results = response.results;
    // write results > div
    if (results && results.length) {
      var message = '';
      for (var index = 0; index < results.length; index++) {
        message += results[index].FirstName
          + ' ' + results[index].Title
          + ' (' + results[index].Email + ')';
      }
      jQuery("#results").html(message);
    }
  });

Updating Items with Breeze

Selects are always easy, but what about updating items with Breeze? In the code above, I showed you how to do it with just the raw SharePoint 2013 REST API using jQuery. Thankfully you don’t have to do that with Breeze!

// get the first item
var promise = breeze.EntityQuery
  .from(contactType.defaultResourceName)
  .using(entityManager)
  .execute()
  .where('Id', 'eq', 1)
  .then(function (data) {
    return data.entity;
  });

// update the first item
promise.then(function (contact) {
  contact.Title = 'NewName';
  entityManager.saveChanges().then(function () {
    jQuery("#results").html('saved first item in list');
  });
});

Preserving Round Trips to the Server with the Local Cache in Breeze

// try to get a single item from the cache, then revert to server
entityManager.fetchEntityByKey('Contact', 1, true)
  .then(function (data) {
    var message = data.entity.FirstName
        + ' ' + data.entity.Title
        + ' (' + data.entity.Email + ')';
    message += 'pulled from: ' + (data.fromCache ? 'cache' : 'server');
    jQuery("#results").html(message);
  });

Andrew Connell is a full stack developer who focuses on Microsoft Azure & Microsoft 365. He’s a 22-year recipient of Microsoft’s MVP award and has helped thousands of developers through the various courses he’s authored & taught.

Feedback & Questions

• Oldest
• Newest