There's a good amount of code snippets in this post. Typically code formatting doesn't render great in RSS readers so check out the post on my blog for a well formatted version.
So far in this series of posts I've introduced you to the Breeze library (part 1) and some challenges we have in using it OOTB (part 2). In this post I want to explain how you can use it. This breaks down into a few different tasks:
- Acquire the Breeze Library
- Acquire the Breeze SharePoint Data Service
- Configure Breeze to work with SharePoint
- Define your Entity Metadata Model
- Use It!
Let's dive in so you can see what's involved…
Acquire the Breeze Library
You first need to get the Breeze client-side library. This is provided as a NuGet package: Breeze.Client. For this you need the latest version (v1.4.9) which came out in late February 2014. This is by far the easiest step because you can skip it! You'll see why in a moment…
Acquire the Breeze SharePoint Data Service
Next, you need to get the Breeze SharePoint Data Service adapter. This is what Ward Bell, one of the brains behind Breeze, and I have been working on. It's in a easy to grab NuGet package: Breeze.DataService.SharePoint. Best part is it already includes the Breeze client library package which is why you could ignore the previous step. It also includes a few other dependencies.
Once you've done this, add the necessary references to your HTML page, as shown here:
… just the HTML page with references
Configure Breeze to work with SharePoint
After you get everything, you then need to configure Breeze. This involves first initializing Breeze to use the new SharePoint data service adapter using the
Then you need to tell Breeze how to get the security validation token, also known as the form digest, security digest, or the request digest. This is needed when you want to do an HTTP POST or DELETE against the SharePoint REST API. For this I'll simply use the hidden form field added to the page:
OK… everything is all configured. Next up, tell Breeze about our entities.
Define your Entity Metadata Model
In this step you will build the metadata that tells Breeze about the list we want to work with. In my sample app I created a simple Contacts list in the app and to keep things simple, I only want to deal with the first and last names as well as the email address.
Writing the metadata can involve a good amount of code as you would expect. However over in the Breeze Labs there is a slick helper utility library called the Breeze Metadata Helper that helps quite a bit. I'll add this via an easy to use NuGet package: Breeze.Metadata.Helper.
Then I'll get a reference to the metadata helper and create an alias named
addType() that will add the new entity type to the metadata store for me as well as setup a default select statement so I don't have to deal with that in my code:
Last but not least, I'm going to create an entity that maps to the contact list… take notice that I am not getting all fields from the contact list, just the ones I'm interested in. Oh, check out the email property… Breeze won't let me save it unless it passes Breeze's RegEx email address validation!:
There are a few properties to take note of:
- name: this is the name that we'll use to reference our entity if we need to throughout our app
- defaultResourceName: this is the endpoint for the list… not everything is listed here in the URL because as you'll see, we'll define the base part to the REST endpoint for the site in a moment
- dataProperties: collection of the fields we want to get from SharePoint; notice some of these also include validation statements to enforce some data integrity
So with that, Breeze has been added to the page, configured and the metadata has been defined. Let's now use it!
Using Breeze with SharePoint 2013's REST API
Before we start making calls, let's first get an instance of something called the
EntityManager. This is what will make the calls to the server for us. Part of this is also defining the data service, telling the SharePoint data service adapter to not request metadata from SharePoint's REST API and what the root URL is in the REST API:
Now let's see how to get data… for this I'll fetch all the results from the contact list, using Breeze:
And if we wanted to get only one item, here's how you do a filter:
What about updating items? Well all you do is get the item, make some changes and just call save!
And deleting an item? This is similar to an update item:
And a very cool piece to this. Once you get items back from SharePoint which are stored in the Breeze local cache, you can re-fetch them at a later time without going to the server. The following call is effectively telling Breeze “get a contact with ID=1 from cache, but if you don't find it, then go to the server to find it:”
Pretty slick huh? Again, remember what I said at the beginning of the post. I know you think “that was a lot of work at the start to configure and set it up.” I would agree with that to a point, but most of it is boilerplate code… everything except the creation of the metadata would be the same from one project to another.
Again… you can download the sample app I used to create this post from this public GitHub project I created: BreezeSP2013Sample. Just grab the code, open it in Visual Studio 2012/2013, change the Site URL property for the project to point to your SharePoint developer site (on-prem or Office 365) and hit F5 to see how it works! Hopefully you'll find this as cool as I do… I can't imagine working with SharePoint's REST API without Breeze ever again! It just makes working with SharePoint's REST API… well… a Breeze!
Page update history / changelogThis page has been updated since it was originally published. The following list details each change and when it occurred.
- Thursday, August 15, 2019 - 6:06 AM
Clean up HTML to markdown, convert code samples to gists.