JavaScript library used with axios.js to make SharePoint REST calls more fun. axios.js required separately.
npm install sprestassistasync/await that is part of ECMAScript 2017.
CLI
npm install sprestassist
`
$3
Using jsDelivr CDN:
`html
`
Using unpkg CDN:
`html
`
Setup the environment
> NOTE: axios is required to use this library.
- Include axios in your project by preferred method (NPM, Bower, Yarn, etc.), or CND. See the axios documentation for more information
- Import sprestassist.min.js as seen below
`js
import * as spra from ;
OR use feature imports
import { getItems, createItem, updateItem, deleteItem, getCurrentUserProps, getCurrentUserGroups, verifyCurrentUserGroupMembership } from ;
`
Examples
Examples will not use named feature imports. Feature imports are supported & recommended in production
$3
>Parameters required for the getItems method:
>
>Pass the method an object containing the following
>- url: [required] the url of the base SharePoint site
>- list: [required] list or library name
>- action: [required] items or fields (items when dealing with list or library items, fields when dealing with columns)
>- query: [optional] query string to include, such as sort, orderby, filter, etc
>- verbose: [optional] boolean determines whether the returned metadata will be verbose or minimal (minimal is default)
`js
// Pass in an object with the following parameters {url:, action, query:}
// The action is either 'items' OR 'fields' - for list items it will be 'items', for getting column information it will be 'fields'
// requests all list items
spra.getItems(
{
url:'https://domain.com/', // base location of list
list:'MyList',
action:'items',
// query: optional // this is where a custom query string can be passed to sprestassist for filtering, sorting, etc.
}
)
// then - Do something with the returned list items
.then( (response) => {
// payload is returned as response.data.value. See axios documentation for available response properties
console.log('%cThe list items for Example 1 are: ', 'color: green; font-size: 20px', response.data.value);
})
.catch( (error) => {
// should there be an error, do something with it
alert(
An error occurred. The error is as follows:\n\n ${error});
});
// requests all list items and returns the array of attachment details for each list item, each containing an array of Attachment Files
spra.getItems(
{
url:'https://domain.com/', // base location of list
list:'MyList',
action:'items',
query:'$select=AttachmentFiles&$expand=AttachmentFiles'
}
)
// then - Do something with the returned list items
.then( (response) => {
// payload is returned as response.data.value
console.log('%cThe list of attachments for each file are: ', 'color: green; font-size: 20px', response.data.value);
})
.catch( (error) => {
// should there be an error, do something with it
alert(An error occurred. The error is as follows:\n\n ${error});
});
// requests all the choices from a provided choice column
spra.getItems({url:'https://domain.com/', list:'MyList', action:'fields', query:$filter=EntityPropertyName eq '})
.then( (response) => {
// do something with the response data
console.log('%cThe choices for this column are: ', 'color: green; font-size: 20px', response.data.value[0].Choices);
})
.catch((error) => {
// should there be an error, do something with it
alert(An error occurred. The error is as follows:\n\n ${error});
});
// requests all the picture details for each picture in the library - Returns an array of objects containing an object for each picture
spra.getItems({url:'https://domain.com/', list:'Pictures', action:'items', query:'select=Title,File/ServerRelativeUrl,AlternateText,imageLink&$expand=file'})
.then( (response) => {
// Do something with the returned data
console.log('%cThe picture details are: ', 'color: green; font-size: 20px', response.data.value);
})
.catch((error) => {
// should there be an error, do something with it
alert(An error occurred. The error is as follows:\n\n ${error});
});
// requests all the file details for each file in the library
spra.getItems({url:'https://domain.com/', list:'Documents', action:'items', query:'select=Title,File/ServerRelativeUrl&$expand=file'})
.then( (response) => {
// Do something with the returned data
console.log('%cThe files details are: ', 'color: green; font-size: 20px', response.data.value);
})
.catch((error) => {
// should there be an error, do something with it
alert(An error occurred. The error is as follows:\n\n ${error});
});
// requests Current User Details
// common properties requested include: AccountName, DisplayName, Email, Title
// to request all properties omit the property parameter from the passed in object
const property = <'property to request'> ;
spra.getCurrentUserProps( { url:'https://domain.com/', selectedProperty:${property} })
.then( (response) => {
// Do something with the returned data
property ? console.log('%cThe user property requested is: ', 'color: green; font-size: 20px', response.data.value) : console.log('%cThe properties are: ', 'color: green; font-size: 20px', response.data);
})
.catch((error) => {
alert(An error occurred. The error is as follows:\n\n ${error});
});
// request Current User SharePoint Group Memberships
spra.getCurrentUserGroups( { url:'https://domain.com/' } )
.then( (response) => {
// Do something with the returned data
let groupNames = response.map((item) => {return '${item.Title}' }).reduce( (accumulator ,next) => { return accumulator += next; });
console.log('%cThe users group memberships are: ', 'color: green; font-size: 20px', groupNames);
})
.catch( (error) => {
// should there be an error, do something with it
console.log('%cThere was an error', 'color: red; font-size: 20px', error);
})
// check if current user is a member of specified SharePoint group - returns boolean value
spra.verifyCurrentUserGroupMembership( { url:'https://domain.com/', groupName: } )
.then( (response) => {
// Do something with the returned boolean value
response ? console.log(%cThe response is ${response}, which means the current logged in user is a member of the group., 'color: green; font-size: 20px') : console.log(%cThe response is ${response}, which means the current logged in user is NOT a member of the group!, 'color: red; font-size: 20px');
})
.catch( (error) => {
// should there be an error, do something with it
console.log('%cThere was an error', 'color: red; font-size: 20px', error);
})
`
#### Performing multiple concurrent requests
Requesting multiple REST calls and waiting for all promises to resolve before proceeding
>CAUTION: The method below has been deprecated. Please see the axios documentation for more information.
>Instead please us Promise.all, or manage this with custom code.
This is an axios method, this examples shows how this can be done utilizing sprestassist
`js
axios.all( [spra.getItems({url:'https://domain.com/', list:'MyList', action:'items'}), spra.getItems({url:'https://domain.com/', list:'MyList', action:'fields', query:$filter=EntityPropertyName eq '}) ])
.then(axios.spread( (listItems, columnChoices) => {
// do something with the data from both promises once both have resolve
console.log('%cThis is the result of two promises resolving. Both must resolve before any action can be taken. Here the list items are: ', 'color: green; font-size: 20px', listItems.data.value);
console.log('%cand the column choices are: ', 'color: green; font-size: 20px', columnChoices.data.value[0].Choices);
}))
.catch((error) => {
// should there be an error, do something with it
alert(An error occurred. The error is as follows:\n\n ${error});
});
`
$3
>NOTE: eTag is a version tracking system used by SharePoint
>
>Parameters required for the createItem method:
>
>Pass the method an object containing the following
>
>- url: [required] the url of the base SharePoint site
>- list: [required] list or library name
>- data: [required] object containing column names and values stringified
>- verbose: [optional] boolean determines whether the returned metadata will be verbose or minimal (minimal is default)
For information about eTags see the Microsoft Documentation
#### Creating a new list item
`js
// creates a new list item
// Pass in an object containing the required properties - url, list name, data (the payload formatted as a string)
const title = 'This is going to be used to fill the title field',
choice = 'seven'; // this will be used to fill in a column field that is a column type of choice
// These are example fields, your list and your data will determine which fields you assign
// the data parameter must be a string, all properties and keys must be wrapped in quotes or single quotes
spra.createItem({url:'https://domain.com/', list:'My List', data:'Title': '${title}', 'choose': '${choice}', verbose: true})
.then( (response) => {
// Do something with the response
console.log('%cThe item has been created with a Title of', 'color: green; font-size: 20px', response.data.d.Title);
console.log('%cyour choice of ', 'color: green; font-size: 20px', response.data.d.choose);
console.log('%cand an ID of ', 'color: green; font-size: 20px', response.data.d.ID);
})
.catch( (error) => {
// should there be an error, do something with it
alert(An error occurred. Please note the following:\n\n ${error.response.data.error.message.value});
})
`
#### Updating an existing list item
>Parameters required for the createItem method:
>
>Pass the method an object containing the following
>- url: [required] the url of the base SharePoint site
>- list: [required] list or library name
>- data: [required] object containing column names and values stringified
>- etag: [optional] eTag of the item to be updated (omit this field if you wish to overwrite the item without verifying version)
>- verbose: [optional] boolean determines whether the returned metadata will be verbose or minimal (minimal is default)
`js
const id = 27,
title = 'Title of my item',
field2 = 'field2 info';
spra.updateItem({url:'https://domain.com/', list:'My List', data:'Title': '${title}', 'field2': '${field2}', updateId:${id}})
.then( () => {
// There is no response data for an update
console.log('%cThe Item has been updated. There is no response to an update. Check the item to verify.', 'color: green; font-size: 20px',);
})
.catch( (error) => {
// should there be an error, do something with it
console.log('%cThere was an error', 'color: red; font-size: 20px', error.response.data.error.message.value);
})
`
#### Deleting a list item
Parameters required for the deleteItem method:
>Pass the method an object containing the following
>- url: the url of the base SharePoint site
>- list: list or library name
>- data: object containing column names and values stringified
>- etag: eTag of the item to be updated (omit this field if you wish to delete the item without verifying version)
>- verbose: [optional] boolean determines whether the returned metadata will be verbose or minimal (minimal is default)
`js
const id = 27,
etag = 2;
let deleteObject = {};
if (etag) { deleteObject = {url:'https://domain.com/', list:'My List', itemId:${id}, etag:"${etag}"}; }
else { deleteObject = {url:'https://domain.com/', list:'My List', itemId:${id}}; }
spra.deleteItem(deleteObject)
// delete the specified item
.then( () => {
console.log('%cThere is no response to an update. Check the list to verify.', 'color: green; font-size: 20px',);
})
.catch( (error) => {
// should there be an error, do something with it
console.log('%cThere was an error', 'color: red; font-size: 20px', error.response.data.error.message.value);
alert(An error occurred. Please try again, if this issue continues please call the help desk with the following:\n\n ${error.response.data.error.message.value});
})
`
Response Schema
> NOTE: The following is the Response Schema provided by axios and is still exposed while using sprestassist
The response for a request contains the following information
`js
{
// data is the response that was provided by the server
data: {},
// status is the HTTP status code from the server response
status: 200,
// statusText is the HTTP status message from the server response
statusText: 'OK',
// headers the HTTP headers that the server responded with
// All header names are lower cased and can be accessed using the bracket notation.
// Example: response.headers['content-type']
headers: {},
// config is the config that was provided to axios for the request
config: {},
// request is the request that generated this response
// It is the last ClientRequest instance in node.js (in redirects)
// and an XMLHttpRequest instance in the browser
request: {}
}
`
> NOTE: The response is provided via axios, and is still exposed directly using sprestassist
When using then, you will receive the response as follows:
`js
spra.method(`
Versioning
Breaking changes may be released with a new minor version until sprestassist extends to release 1.0.0
For example, 0.1.1, and 0.1.4 will not have any breaking changes, but 0.2.0` may have breaking changes