Pnp-js is a really cool library built on top of the SharePoint rest api. It simplifies writing JavaScript to query the SharePoint REST Api and allows us to focus on getting the data we need without having to manage all the ajax requests ourselves.
GET
Getting items from a list is one of the basic actions that most applications require. This is made easy through the library and the following examples demonstrate these actions.
Basic Get
Paged Get
To assist with paging list items whose skip value relates to the item id and not the number of items to skip you can use the getPaged method. This method will return a paged items collection that helps you move through the collection.
Retrieving Lookup Fields
When working with lookup fields you need to use the expand operator along with select to get the related fields from the lookup column. This works for both the items collection and item instances.
Retrieving PublishingPageImage
The PublishingPageImage and some other publishing-related fields aren't stored in normal fields, rather in the MetaInfo field. To get these values you need to use the technique shown below, and originally outlined in this thread. Note that a lot of information can be stored in this field so will pull back potentially a significant amount of data, so limit the rows as possible to aid performance. This technique also works only within a Pages library on publishing sites.
If you need to retrieve a PublishingRollupImage from a non-pages list you will need to make two calls. They first to get all the items and the second to load the FieldValuesAsHtml value for each item. This is expensive so should be avoided if possible. The below serves as an example you can use as a starting point for loading this value in non-pages lists.
Paging with getItemsByCAMLQuery
When building queries with CAML you will need to manage paging on your own. This can be done via the ListItemCollectionPosition property of the query as shown below.
Add Items
There are several ways to add items to a list. The simplest just uses the add method of the items collection passing in the properties as a plain object.
Content Type
![Filter Filter](/uploads/1/2/4/7/124768305/500908457.png)
You can also set the content type id when you create an item as shown in the example below:
User Fields
There are two types of user fields, those that allow a single value and those that allow multiple. For both types, you first need to determine the Id field name, which you can do by doing a GET REST request on an existing item. Typically the value will be the user field internal name with 'Id' appended. So in our example, we have two fields User1 and User2 so the Id fields are User1Id and User2Id.
Next, you need to remember there are two types of user fields, those that take a single value and those that allow multiple - these are updated in different ways. For single value user fields you supply just the user's id. For multiple value fields, you need to supply an object with a 'results' property and an array. Examples for both are shown below.
Lookup Fields
What is said for User Fields is, in general, relevant to Lookup Fields:
- Lookup Field types:
- Single-valued lookup
- Multiple-valued lookup
Id
suffix should be appended to the end of lookup'sEntityPropertyName
in payloads- Numeric Ids for lookups' items should be passed as values
Add Multiple Items
Update
The update method is very similar to the add method in that it takes a plain object representing the fields to update. The property names are the internal names of the fields. If you aren't sure you can always do a get request for an item in the list and see the field names that come back - you would use these same names to update the item.
Getting and updating a collection using filter
Update Multiple Items
This approach avoids multiple calls for the same list's entity type name.
Delete
Delete is as simple as calling the .delete method. It optionally takes an eTag if you need to manage concurrency.
Resolving field names
It's a very common mistake trying wrong field names in the requests.Field's
EntityPropertyName
value should be used.The easiest way to get know EntityPropertyName is to use the following snippet:
Lookup fields' names should be ended with additional
Id
suffix. E.g. for Editor
EntityPropertyName EditorId
should be used.This article describes completing basic operations using the JS core library. It assumes you have added the library to your project either via CDN, bower, or npm package. The API is fluent and matches the structure of the underlying REST API to make it easy to discover the capabilities through intellisense.
Quick note on notation
All of the samples posted below are TypeScript examples. If you are using the library directly in JavaScript they will all still work, with a few modifications.
- Where you see something like pnp.sp.* just replace it with $pnp.sp.*
- Where you see something like:use:
Read Data
The simplest thing you can do is read data. Below are several examples of reading data. As you can see the get method returns a Promise. For GET operations you must call the get() method to finalize the property chain and execute the request. It is also good practice to include a catch() in your promise handling chain to ensure you track and handle any errors.
OData Operators
The library also supports the OData operations select and expand for instances (such as a list or an item) as well we the select, filter, expand, orderBy, skip, and top operations for collections (collection of lists, or items). Some examples are provided below. Remember, the get() method call must always be the last call in your chain as that executes the request.
Add and Update Values
The next step is to update or add to SharePoint and the API helps with this as well. One of the most common operations is adding/updating list items, shown here. The properties you pass in should match the field names of the list item you want to add.