PnP JSCore 1.0.2
Today we are releasing the latest update for the SharePoint Patterns and Practices JSCore Library, version 1.0.2. This update includes new functionality as well as some fixes for a few reported issues. Much of the new functionality was designed in response to feedback received from the community.
The two largest additions are the ability to batch and cache requests. These methods are also composable so you can cache the results from batched requests.
Caching
First let's take a look at adding caching to a request. First, caching is never done for POST requests, only GET.
As you can see this is done in-line along with the other requests, and the "usingCaching" method should be chained immediately before the action - generally "get()". By default the data will be cached in the session store for 30 seconds using the full request url and query as the key. You can also specify options if you prefer:
In this case we are setting the expiration, key, and storeName ("local" or "session") explicitly - though each is optional. Likely though the default options will be sufficient for most cases. We also added the ability to turn off caching globally using the setup method added in the last release. This should help in development scenarios and testing where caching data is not desired. Additionally you can set the other caching defaults using setup:
Batching
Working hand in hand with caching is batching. Batching works for GET or POST requests and is also used in your method chain before the final execution, usually "get()" or "update(...)" for example. Here is a simple example that will get both the list data and item data in a batch:
The key take-away here is that you continue to chain your promises as before, however they will not be resolved until the batch's execute command is called. Write the same code as before, just add in the inBatch() method to your chain and get the benefits of REST batching and your promises will be resolved as expected once the entire batch is resolved. It is important to note that batching is not currently supported in SharePoint 2013. You can also batch update, add, delete, and get operations together - but remember they are executed in order so be careful how you order and batch your requests.
It is important to remember that these operations can be used together - allowing you to cache the results of your batched GET requests as shown below:
As you can see the order in which these two methods, "inBatch" and "usingCaching", are chained does not matter - however both should be the final methods chained before the request execution. The ability to easily batch and cache requests can help you address performance considerations in your applications.
Granular Control of GET requests
In addition to the batching and caching we also added the capability to pipe options directly to the underlying fetch operation on a per get request basis. This is done using the second argument in the get method and takes a FetchOptions struct defined in /src/net/HttpClient.ts. This is likely not necessary for most scenarios, but provides some added flexibility if needed. When possible it is easier to either accept the library defaults or set them global rather than setting them on each call.
Use SP.RequestExecutor to enable Provider Hosted Add-In Scenarios
Added in PR 135 is the ability to use the SP.RequestExecutor to make requests. This enables use of the library in provider hosted add-ins in the same way it is used in other scenarios. To enable this functionality you need to set the global flag in setup "useSPRequestExecutor" and then use either the crossDomainWeb or crossDomainSite entry points as shown below. You will also need to ensure that the SP.RequestExecutor.js file is included in the page. We chose to not attempt to auto-load this file at this time due to the myriad different ways folks are loading js files.
Other Changes
getWopiFrameUrl
In addition to the above we also added the getWopiFrameUrl method on the item object. This method takes a single optional parameter indicating the type of action: (Display mode: 0: view, 1: edit, 2: mobileView, 3: interactivePreview):
Fixes
Fix for search in PR 143 related to odata=verbose update in 1.0.1.
Code of Conduct
We also added a notice regarding the global Microsoft open source Code of Conduct. This applies to all open source projects under the Microsoft umbrella and serves to codify the mindset under which we were already working.
What is the JS Core Component?
The Patterns and Practices JavaScript Core Library was created to help developers by simplifying common operations within SharePoint. This is aligned with helping folks transitioning into client side development in support of the upcoming SharePoint Framework. Currently it contains a fluent API for working with the full SharePoint REST API as well as utility and helper functions. This takes the guess work out of creating REST requests, letting developers focus on the what and less on the how.
"Sharing is Caring"