spscript-b
v4.2.12
Published
ShareP0oint Rest Api Wrappers
Downloads
9
Maintainers
Readme
I only modify work of DroopyTersen for specific usage, use original package for your project :)
Original package -> Visit https://spcript.com for full documentation.
SPScript
Getting Started
Install NPM Pacakge: NPM Package
npm install spscript
Initialization
Most SPScript methods require an SPScript Context
var ctx = SPScript.createContext();
You can also pass an explicit url. If you don't pass a url, it will use your current web.
var siteUrl = "http://urltomysharepointsite.com";
// If you don't pass a site url, it will use your current web
var ctx = SPScript.createContext(siteUrl);
Methods
Core HTTP Request Helpers
ctx.get(url, opts)
- Generic helper to make AJAX GET request. Sets proper headers, promisifies, and parses JSON response.url
is the API url relative to "/_api".ctx.post(url, body, opts)
- Generic helper to make AJAX POST request.url
is the API url relative to "/_api".ctx.authorizedPost(url, body, opts)
- Same asctx.post
except that it also takes care of including the proper authorization headers.
Auth Helpers
ctx.auth.getRequestDigest()
- Retrieves a token needed to authorize any updatesctx.auth.ensureRequestDigest(digest?)
- Retrieves a token needed to authorize if a digest isn't givenctx.auth.getGraphToken()
- Retrieves an token that can be used to authorize requests to the MS Graph API
Web
ctx.web.getInfo()
- Gets you the SPWeb properties of your sitectx.web.getSubsites()
- Gets you all the sub sites and their SPWeb propertiesctx.web.getUser(email)
- Gets you a SP.User object based on the specified emailctx.web.getFile(serverRelativeUrl)
- Gets you an SP.File objectctx.web.copyFile(sourceUrl, destinationUrl)
- Copies a file (both source and destination urls are server relative)ctx.web.permissions.getRoleAssignments()
- Gets you an array of permissions that have been setup for that site. Each permission object has amember
(the user or group) and aroles
array (the permissions that user or group has).ctx.web.permissions.check()
- Looks up the permissions of the current user.ctx.web.permissions.check(email)
- Looks up a user by their email address, then gets you a list of permissions that user has for your site. Similiar to "Check Permissions".ctx.web.permissions.getRoleDefinitionId(name)
- Find role ID for specifiedname
.ctx.web.createFolder(libraryUrl, folderTitle)
- Creates folder within specifiedlibraryUrl
with namefolderTitle
ctx.web.breakRoleInheritanceForFolder(folderUrl)
- Breakes role inheritance for folder with specified relativefolderUrl
ctx.web.clearFolderPermissionRoleForGroup(fileUrl, targetId)
- Clears all permissions for specified group or user IDtargetId
, for file at relativefileUrl
ctx.web.assignPermissionRoleForFolder(fileUrl, permissionId, targetId)
- Sets specified permissionpermissionId
, for file at relatvefileUrl
, for provided group or user IDtargetId
List & List Items
ctx.lists(listname).getInfo()
- gets you that list's SPList propertiesctx.lists(listname).checkExists()
- resolves to a boolean based on whether the specified list name existsctx.lists(listname).getItems()
- gets you all the items in that listctx.lists(listname).getItems(odata)
- gets all the items in that list based on the OData you pass in. This allows you to trim selection, filter, sort etc..ctx.lists(listname).getItemsByCaml(caml)
- gets all the items based on the specified CAML query.ctx.lists(listname).getItemsByView(viewName)
- gets all the items based on the specified View name.ctx.lists(listname).getItemById(id)
- gets you a specific item based on the SharePoint Idctx.lists(listname).findItems(key, value)
- gets you all items whose field(key) matches the value. Currently only text and number columns are supported.ctx.lists(listname).findItems(key, value, extraOdata)
- gets you all items whose field(key) matches the value. Currently only text and number columns are supported.ctx.lists(listname).findItem(key, value)
- get you an item whose field(key) matches the value. If multiple matches are found, the first is returned. Currently only text and number columns are supported.ctx.lists(listname).addItem(item)
- takes a javascript object and creates a list item.ctx.lists(listname).updateItem(id, updates)
- takes a SharePoint Id, and updates that item ONLY with properties that are found in the passed inupdates
object.ctx.lists(listname).deleteItem(id)
- deletes the item with the specified SharePoint Idctx.lists(listname).permissions.getRoleAssignments()
- Gets you an array of permissions that have been setup for that list. Each permission object has amember
(the user or group) and aroles
array (the permissions that user or group has).ctx.lists(listname).permissions.check()
- Looks up the permissions of the current user.ctx.lists(listname).permissions.check(email)
- Looks up a user by their email address, then gets the permissions that user has for that list. Similiar to "Check Permissions".ctx.lists(listname).getItemAttachmentsById(id)
- gets you all attachments attached in list wit providedid
.ctx.lists(listname).deleteItemAttachment(id, fileTitle)
- delete attachment with desired title from list with providedid
ctx.lists(listname).addItemAttachment(id, file)
- adds attachment with providedFile
object (conversion to binary string) to list with providedid
Search
ctx.search.query(queryText)
- performs a SharePoint search and returns aSearchResults
object which contains elapsedTime, suggestion, resultsCount, totalResults, totalResultsIncludingDuplicates, items. Theitems
property is what contains the actual "results" array.ctx.search.query(queryText, queryOptions)
- same asquery(queryText)
but with the ability to override default search options.ctx.search.people(queryText)
limits the search to just peoplectx.search.sites(queryText)
limits the search to just sites (STS_Web)ctx.search.sites(queryText, scopeUrl)
limits the search to just sites (STS_Web) that are underneath the specifiedscopeUrl
CustomActions
ctx.customActions.get()
- Gets all of the 'Site' and 'Web' scoped UserCustomActions.ctx.customActions.get(name)
- Get a UserCustomAction by name. Searches both 'Site' and 'Web' scoped custom actions.ctx.customActions.update(updates)
- Updates properties on an exisiting custom action. You must set theName
property on youupdates
object to identify the targeted custom action.ctx.customActions.remove(name)
- Removes a UserCustomAction with that namectx.customActions.add(customAction)
- Takes in an object withSP.UserCustomAction
properties.ctx.customActions.addScriptLink(name, url, opts)
- injects a Javascript file onto your sitectx.customActions.addCssLink(name, url, opts)
- injects a CSS file onto your site
Profiles
ctx.profiles.current()
- gets you all the profile properties for the current userctx.profiles.get()
- gets you all the profile properties for the current userctx.profiles.get(email)
- looks up a user based on their email and returns their profile propertiesctx.profiles.get({ AccountName|LoginName })
- gets you all the profile properties of the passed in user object. It must have a validAccountName
(orLoginName
) propertyctx.profiles.setProperty(key, value)
- sets a profile property (key) for the current userctx.profiles.setProperty(key, value, { AccountName|LoginName })
- sets a profile property (key) for the specified user. User object should haveAccountName
orLoginName
propertyctx.profiles.setProperty(key, value, email)
- sets a profile property (key) for the user tied to that email address
Utility Functions
SPScript.utils.openModal(url, modalOpts)
- Launch a SharePoint modalSPScript.utils.validateODataV2(data)
- Helps parse raw ODATA response to remove data.d/data.d.results namespace.SPScript.utils.parseJSON(data)
- Wraps JSON.parse in a try/catch
Loaders
SPScript.utils.loadScript(url)
- loads a javascript file onto the pageSPScript.utils.loadScripts(urls)
- loads multiple javascript files onto the pageSPScript.utils.loadCSS(url)
- Load a CSS stylesheet onto your page
Dependency Management
SPScript.utils.validateNamespace(namespace)
- Safely check a nested namespaces exists on the globalSPScript.utils.waitForLibrary(namespace)
- waits for the library to be on the pageSPScript.utils.waitForLibraries(namespaces)
- waits for all libraries to be on the pageSPScript.utils.waitForElement(selector)
- Wait/Ensure for an element to exist on a page page
Query String Helpers
SPScript.utils.qs.toObj(str)
- returns a javascript object. Each query string key is a property on the object.SPScript.utils.qs.fromObj(str)
- turns a javascript object into a string in format of "key1=value1&key2=value2"
Request Header Helpers
SPScript.utils.headers.getStandardHeaders(digest?)
- sets theAccept
andContent-Type
headers to the JSON Mime type. If the optionaldigest
token is passed, it sets the proper authoorization headers. Returns the headers as an object.SPScript.utils.headers.getAddHeaders(digest)
- returns the headers object needed in order to create an item.SPScript.utils.headers.getUpdateHeaders(digest)
- returns the headers object needed in order to update an item.SPScript.utils.headers.getDeleteHeaders(digest)
- returns the headers object needed in order to delete an item.
Usage Examples
Query List Items
Get all "Tasks" with a status of "Approved"
var taskList = ctx.lists("Tasks");
// BEST: Option 1 - 'Find' syntax sugar
taskList.findItems("Status", "Approved").then(logApprovedTasks);
// BETTER: Option 2 - OData support in the '.items()'
taskList.getItems("$filter=Status eq 'Approved'").then(logApprovedTasks);
// GOOD: Options 3 - Manual 'GET'
ctx.get("/web/lists/getByTitle('Tasks')?$filter=Status eq 'Approved'").then(
function(data) {
if (data && data.d && data.d.results) {
logApprovedTasks(data.d.results);
}
}
);
var logApprovedTasks = function(tasks) {
tasks.forEach(function(task) {
console.log(task.Title);
});
};
Get Item By Id
Get the task with a SharePoint ID of 29
ctx.lists("Tasks")
.getItemById(29)
.then(displayTask);
var displayTask = function(task) {
//blah blah blah
};
Add List Item
Add item to the "Tasks" list
var newItem = {
Title: "My New Task",
Status: "Not Started",
RemainingHours: 12,
};
ctx.lists("Tasks").addItem(newItem);
Update List Item
Update item in the "Tasks" list. Set item 29's status to "Completed"
var updates = { Status: "Completed", RemainingHours: 0 };
ctx.lists("Tasks").updateItem(29, updates);
Find One
Get the one item whose "RequestId" is "abc123"
ctx.lists("IT Requests")
.findItem("RequestId", "abc123")
.then(function(request) {
console.log(request.RequestId + ": " + request.Title);
});
If there is more than one match, it will return the first result. If there are zero matches, it will return null
Get Every List Item
Get all items in the "Tasks" list and log the 'Title'
ctx.lists("Tasks")
.getItems()
.then(function(tasks) {
tasks.forEach(function(task) {
console.log(task.Title);
});
});
import SPScript from "spscript";
const getPublishedNews = async function(siteUrl) {
let ctx = SPScript.createContext(siteUrl);
let pages = await ctx.lists("Site Pages").findItems("PromotedState", 2);
console.log(pages); // This will show an Array of Page List Items
return pages;
};
GET & POST Requests
Every REST Api call that SharePoint supports can be called using SPService. Both the RestDao and CrossDomainDao implement a .get()
and post()
method that allow you to type in the api call's relative url. For example, you could rewrite the code above as:
ctx.get("/web/lists/getByTitle('Tasks')/items").then(function(data) {
var tasks = data.d.results;
tasks.forEach(function(task) {
console.log(task.Title);
});
});
Here is a more advanced usage that uses ctx.authorizedPost to update the site's logo
var setSiteLogo = function(siteLogoUrl, siteUrl) {
var ctx = SPScript.createContext();
var body = { __metadata: { type: "SP.Web" }, SiteLogoUrl: siteLogoUrl };
ctx.authorizedPost("/web", body)
.then(function(result) {
console.log("Set Site Logo Success!");
})
.catch(function(error) {
console.log("Set Site Logo Error. Message: " + error);
});
};
Profiles
Get the current user's profile properties
ctx.profiles.current().then(function(profile) {
console.log(JSON.stringify(profile));
});
Search
Search for "petersen" and get the url of each search result
ctx.search.query("petersen").then(function(searchResults) {
searchResults.items.forEach(function(item) {
console.log(item.FileRef);
});
});
Search for People named "petersen"
ctx.search.people("petersen").then(function(searchResults) {
console.log(
"There are " + searchResults.totalResults + " people named 'andrew'"
);
});
NodeJS
Fetch Polyfill
In order to work in Node.js, you need to import isomorphic-fetch
. This is because under the hood, SPScript uses fetch
for all the requests. However, I wanted to leave it up to the consumer to decide whether they needed a fetch
polyfill (old IE or Node).
For node, Just add this line to the top of your entry file
require("isomorphic-fetch")
You can pass a headers
property to the ContextOptions
param in createContext
.
For example you could use node-sp-auth to log in with username and password (only do this serverside), then pass the Fed Auth cookie you receive to SPScript:
// Use node-sp-auth to get a Fed Auth cookie.
// This cookie can be include in the headers of REST calls to authorize them.
let auth = await spauth.getAuth(process.env.SITE_URL, {
online: true,
username: process.env.SP_USER,
password: process.env.PASSWORD,
});
// Pass the auth headers to SPScript via the optional ContextOptions param
let ctx = SPScript.createContext(siteUrl, { headers: auth.headers });
let webInfo = await ctx.web.getInfo();
console.log(webInfo);
With that snippet, you could easily perform REST operation in a Node.js app using service account creds.