├── .env.example
├── .gitignore
├── .npmignore
├── .prettierrc
├── .vscode
├── launch.json
├── settings.json
└── tasks.json
├── README.md
├── __tests__
├── Context.test.ts
├── CustomActions.test.ts
├── List.test.ts
├── MMS.test.ts
├── Profiles.test.ts
├── Search.test.ts
├── Securable.test.ts
├── Web.test.ts
├── namespace.test.ts
├── queryString.test.ts
└── testUtils.ts
├── docs
├── .nojekyll
├── arbitrary-requests.md
├── coverpage.md
├── getting-started.md
├── index.html
├── introduction.md
├── list-operations.md
├── mms.md
├── modifying-listitems.md
├── nodejs.md
├── profiles.md
├── search.md
├── sidebar.md
└── utilities.md
├── jest.config.js
├── legacy-tests
├── nodeauthtest.js
├── test.browser.js
├── test.html
├── test.server.js
└── tests
│ ├── authTests.js
│ ├── contextTests.js
│ ├── customActionTests.js
│ ├── index.js
│ ├── listTests.js
│ ├── permissionTests.js
│ ├── profileTests.js
│ ├── searchTests.js
│ ├── utilsTests.js
│ └── webTests.js
├── package.json
├── rollup.config.js
├── src
├── Auth.ts
├── Context.ts
├── CustomActions.ts
├── List.ts
├── MMS.ts
├── Profiles.ts
├── Search.ts
├── Securable.ts
├── Web.ts
├── index.ts
├── request.ts
└── utils
│ ├── dependencyManagement.ts
│ ├── headers.ts
│ ├── index.ts
│ ├── loaders.ts
│ └── queryString.ts
├── stats.html
├── tasks
└── setAuthCookie.js
├── tsconfig.json
└── yarn.lock
/.env.example:
--------------------------------------------------------------------------------
1 | SITE_URL=https://skylinespark.sharepoint.com/sites/spscript
2 | PASSWORD=SHHH!!
3 | SP_USER=apetersen@skylinespark.onmicrosoft.com
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | lib-cov
2 | *.seed
3 | *.log
4 | *.csv
5 | *.dat
6 | *.out
7 | *.pid
8 | .gz
9 | *.config
10 | pids
11 | logs
12 | results
13 | .c9
14 | npm-debug.log
15 | node_modules
16 | bower_components
17 | lib
18 | pkg
19 | dist
20 | coverage
21 | .env
22 | .cache
23 |
24 |
--------------------------------------------------------------------------------
/.npmignore:
--------------------------------------------------------------------------------
1 | lib-cov
2 | *.seed
3 | *.log
4 | *.csv
5 | *.dat
6 | *.out
7 | *.pid
8 | .gz
9 | *.config
10 | pids
11 | logs
12 | results
13 | .c9
14 | npm-debug.log
15 | node_modules
16 | bower_components
17 | coverage
18 | .env
19 | docs
20 | .vscode
21 | src
22 | .env
23 | .cache
--------------------------------------------------------------------------------
/.prettierrc:
--------------------------------------------------------------------------------
1 | {
2 | "trailingComma": "es5",
3 | "printWidth": 100,
4 | "tabWidth": 2,
5 | "semi": true,
6 | "singleQuote": false,
7 | "bracketSpacing": true,
8 | "arrowParens": "always"
9 | }
10 |
--------------------------------------------------------------------------------
/.vscode/launch.json:
--------------------------------------------------------------------------------
1 | {
2 | // Use IntelliSense to learn about possible attributes.
3 | // Hover to view descriptions of existing attributes.
4 | // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
5 | "version": "0.2.0",
6 | "configurations": [
7 | {
8 | "type": "node",
9 | "name": "vscode-jest-tests",
10 | "request": "launch",
11 | "program": "${workspaceFolder}/node_modules/jest/bin/jest",
12 | "args": ["--runInBand"],
13 | "cwd": "${workspaceFolder}",
14 | "console": "integratedTerminal",
15 | "internalConsoleOptions": "neverOpen"
16 | }
17 | ]
18 | }
19 |
--------------------------------------------------------------------------------
/.vscode/settings.json:
--------------------------------------------------------------------------------
1 | {
2 | "workbench.colorCustomizations": {
3 | "titleBar.activeBackground": "#0b87da",
4 | "titleBar.inactiveBackground": "#0b87da99",
5 | "titleBar.activeForeground": "#e7e7e7",
6 | "titleBar.inactiveForeground": "#e7e7e799",
7 | "activityBar.activeBackground": "#24a1f4",
8 | "activityBar.activeBorder": "#b60971",
9 | "activityBar.background": "#24a1f4",
10 | "activityBar.foreground": "#15202b",
11 | "activityBar.inactiveForeground": "#15202b99",
12 | "activityBarBadge.background": "#b60971",
13 | "activityBarBadge.foreground": "#e7e7e7",
14 | "statusBar.background": "#0b87da",
15 | "statusBar.border": "#0b87da",
16 | "statusBar.foreground": "#e7e7e7",
17 | "statusBarItem.hoverBackground": "#24a1f4",
18 | "titleBar.border": "#0b87da"
19 | },
20 | "peacock.color": "#0b87da"
21 | }
--------------------------------------------------------------------------------
/.vscode/tasks.json:
--------------------------------------------------------------------------------
1 | {
2 | "version": "0.1.0",
3 | "command": "npm",
4 | "isShellCommand": true,
5 | "args": [
6 | "run"
7 | ],
8 | "tasks": [
9 | {
10 | "taskName": "build",
11 | "args": [],
12 | "isTestCommand": false,
13 | "isBuildCommand": true
14 | }
15 | ]
16 | }
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # SPScript
2 |
3 | ---
4 |
5 | [](https://gitter.im/DroopyTersen/spscript?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
6 |
7 | ### Visit [https://spcript.com](https://spscript.com) for full documentation.
8 |
9 | SPScript is a collection of javascript helpers for the SharePoint Rest API. Some features include...
10 |
11 | - Easy querying of list data.
12 | - Add and Update list items in 1 line of code.
13 | - Easily utilize SharePoint search
14 | - Work with the Profile Service
15 | - Check permissions on sites and lists
16 | - Work with CustomActions
17 |
18 | ## Installation
19 |
20 | Add the SPScript `npm` package to your project
21 |
22 | _NPM_
23 |
24 | ```shell
25 | npm install spscript
26 | ```
27 |
28 | _Yarn_
29 |
30 | ```shell
31 | yarn add spscript
32 | ```
33 |
34 | ## Importing
35 |
36 | You can use SPScript in your Javascript/Typescript files with:
37 |
38 | ```javascript
39 | import SPScript from "spscript";
40 | ```
41 |
42 | **ProTip: Dynamically/Temporarily add SPScript to a Modern page with Dev Tools**
43 |
44 | You can enter the following into a browser console to dynamically load SPScript on a page.
45 |
46 | ```javascript
47 | let script = document.createElement("script");
48 | script.src = "https://unpkg.com/spscript@beta/dist/spscript.browser.js";
49 | document.head.appendChild(script);
50 | ```
51 |
52 | ## SPScript Context
53 |
54 | Almost everything in SPScript is based off an SPScript `Context` class.
55 |
56 | - An SPScript **Context** is tied to specific SharePoint site.
57 | - You get a **Context** by calling `SPScript.createContext(siteUrl)`.
58 |
59 | > You get a **Context** by calling `SPScript.createContext(siteUrl)`.
60 |
61 | _This line of code is the entry point to almost everything SPScript provides._
62 |
63 | ```javascript
64 | let ctx = SPScript.createContext(siteUrl);
65 | ```
66 |
67 | _Example Usage: Get the News Pages of the specified site._
68 |
69 | ```javascript
70 | import SPScript from "spscript";
71 |
72 | const getPublishedNews = async function (siteUrl) {
73 | let ctx = SPScript.createContext(siteUrl);
74 | let pages = await ctx.lists("Site Pages").findItems("PromotedState", 2);
75 | console.log(pages); // This will show an Array of Page List Items
76 | return pages;
77 | };
78 | ```
79 |
80 | Throughout the docs you'll see a variable, `ctx`, representing an instance of an SPScript `Context`.
81 |
82 | ## Troubleshooting
83 |
84 | If you are using Typescript, you may have to use the syntax:
85 |
86 | ```javascript
87 | import * as SPScript from "spscript";
88 | ```
89 |
90 | If you don't like that, add `"allowSyntheticDefaultImports": true` to your `tsconfig.json`.
91 |
--------------------------------------------------------------------------------
/__tests__/Context.test.ts:
--------------------------------------------------------------------------------
1 | import SPScript from "../src/index";
2 | import { getContext } from "./testUtils";
3 |
4 | describe("SPScript.createContext(url, { headers: { FedAuthCookie }} )", () => {
5 | test("There is a FedAuth token", async () => {
6 | expect(process.env.AUTH_HEADERS).toBeTruthy();
7 | });
8 |
9 | test("The FedAuth token can be used to authenticate requests", async () => {
10 | let ctx = await getContext();
11 | let webInfo = await ctx.web.getInfo();
12 | expect(webInfo).toBeTruthy();
13 | expect(webInfo).toHaveProperty("Title");
14 | });
15 | });
16 |
17 | describe("Context Namespaces", function () {
18 | let ctx = null;
19 | beforeEach(() => {
20 | ctx = SPScript.createContext("blah blah");
21 | });
22 |
23 | it("Should create the primary object you use to interact with the site", function () {
24 | if (!ctx) throw new Error("Context is null");
25 | expect(ctx).toHaveProperty("webUrl");
26 | expect(ctx).toHaveProperty("executeRequest");
27 | expect(ctx).toHaveProperty("get");
28 | expect(ctx).toHaveProperty("post");
29 | expect(ctx).toHaveProperty("lists");
30 | expect(ctx).toHaveProperty("auth");
31 | });
32 | it("Should allow a url to be passed in", function () {
33 | var url = "http://blah.sharepoint.com";
34 | var context = SPScript.createContext(url);
35 | expect(context.webUrl).toBe(url);
36 | });
37 |
38 | describe("ctx.web", function () {
39 | test("Should have an SPScript Web object with site methods (getUser, getSubsites etc...)", function () {
40 | expect(ctx).toHaveProperty("web");
41 | expect(ctx.web).toHaveProperty("getUser");
42 | expect(ctx.web).toHaveProperty("getSubsites");
43 | });
44 | });
45 |
46 | describe("ctx.search", function () {
47 | it("Should have an SPScript Search object with search methods (query, people, sites etc...)", function () {
48 | expect(ctx).toHaveProperty("search");
49 | expect(ctx.search).toHaveProperty("query");
50 | expect(ctx.search).toHaveProperty("people");
51 | expect(ctx.search).toHaveProperty("sites");
52 | });
53 | });
54 |
55 | describe("ctx.profiles", function () {
56 | it("Should have an SPScript Profiles object with methods to hit the Profile Service (current, setProperty etc...)", function () {
57 | expect(ctx).toHaveProperty("profiles");
58 | expect(ctx.profiles).toHaveProperty("get");
59 | expect(ctx.profiles).toHaveProperty("setProperty");
60 | });
61 | });
62 |
63 | describe("ctx.auth", () => {
64 | it("Should have methods to get Request digest as well as get Graph Token", () => {
65 | expect(ctx).toHaveProperty("auth");
66 | expect(ctx.auth).toHaveProperty("getRequestDigest");
67 | expect(ctx.auth).toHaveProperty("ensureRequestDigest");
68 | expect(ctx.auth).toHaveProperty("getGraphToken");
69 | });
70 | });
71 |
72 | describe("ctx.lists", () => {
73 | it("Should be a method you can use to get an SPScript List object back by passing a list name", () => {
74 | expect(ctx).toHaveProperty("lists");
75 | expect(typeof ctx.lists).toBe("function");
76 | });
77 | });
78 | });
79 |
80 | describe("Context Methods", () => {
81 | let ctx = null;
82 | beforeAll(async () => {
83 | ctx = await getContext();
84 | });
85 |
86 | describe("ctx.lists(name)", function () {
87 | it("Should return an SPScript List instance", function () {
88 | var list = ctx.lists("My List");
89 | expect(list).toHaveProperty("listName");
90 | expect(list).toHaveProperty("getInfo");
91 | });
92 | });
93 |
94 | describe("ctx.get(url, [opts])", function () {
95 | var promise;
96 | beforeAll(function () {
97 | promise = ctx.get("/lists?$select=Title");
98 | });
99 | it("Should return a Promise", function () {
100 | if (!promise) throw new Error("Promise is null");
101 | expect(promise).toHaveProperty("then");
102 | });
103 | it("Should resolve to a JS object, not a JSON string", async function () {
104 | let data = await promise;
105 | expect(data).toHaveProperty("value");
106 | });
107 | it("Should return valid API results: ctx.get('/lists')", async () => {
108 | let data = await promise;
109 | expect(data).toHaveProperty("value");
110 | expect(data.value).toBeInstanceOf(Array);
111 | });
112 | it("Should use less verbose OData header", async () => {
113 | let data = await ctx.get("/thememanager/GetTenantThemingOptions");
114 | expect(data).toHaveProperty("themePreviews");
115 | expect(data.themePreviews).toHaveProperty("length");
116 | });
117 | });
118 |
119 | // TODO: look into JEST mocking of executeRequest
120 | describe("ctx.post(url, [body], [opts]", function () {
121 | it("Should resolve to a JS object, not a JSON string", async () => {
122 | let data = await ctx.post(
123 | "/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.GetSiteDesigns"
124 | );
125 | expect(data).toBeTruthy();
126 | });
127 | });
128 | });
129 |
--------------------------------------------------------------------------------
/__tests__/CustomActions.test.ts:
--------------------------------------------------------------------------------
1 | import { getContext } from "./testUtils";
2 | import Context from "../src/Context";
3 |
4 | describe("Custom Actions", () => {
5 | // var scriptBlock = {
6 | // Name: "spscript-test",
7 | // Location: "ScriptLink",
8 | // ScriptBlock: "console.log('deployed from spscript tests');",
9 | // };
10 |
11 | let topNav = {
12 | title: "TopNav",
13 | componentId: "f4d63423-0e94-4a77-bf11-c668b09e3e63",
14 | properties: { menuSiteUrl: "https://skylinespark.com/sites/devshowcase" },
15 | };
16 |
17 | describe("customActions.activateExtension()", () => {
18 | let ctx: Context = null;
19 | beforeAll(async () => {
20 | ctx = await getContext();
21 | });
22 |
23 | it("Should add a Custom Action with the given name", async () => {
24 | await ctx.customActions.activateExtension(
25 | topNav.title,
26 | topNav.componentId,
27 | topNav.properties
28 | );
29 | let addedAction = await ctx.customActions.get(topNav.title);
30 | expect(addedAction).toBeTruthy;
31 | expect(addedAction).toHaveProperty("Name");
32 | expect(addedAction.Name).toBe(topNav.title);
33 | });
34 |
35 | it("Should not duplicate the CustomAction if added multiple times", async () => {
36 | await ctx.customActions.activateExtension(
37 | topNav.title,
38 | topNav.componentId,
39 | topNav.properties
40 | );
41 | await ctx.customActions.activateExtension(
42 | topNav.title,
43 | topNav.componentId,
44 | topNav.properties
45 | );
46 | let all = await ctx.customActions.get();
47 | expect(all.filter((ca) => ca.Name === topNav.title).length).toBe(1);
48 | });
49 |
50 | it("Should support extra CustomAction properties", async () => {
51 | let overrides = { Sequence: 0, Description: "Custom Global Navigation" };
52 | await ctx.customActions.activateExtension(
53 | topNav.title,
54 | topNav.componentId,
55 | topNav.properties,
56 | overrides
57 | );
58 |
59 | let addedAction = await ctx.customActions.get(topNav.title);
60 | expect(addedAction.Sequence).toBe(overrides.Sequence);
61 | expect(addedAction.Description).toBe(overrides.Description);
62 | });
63 | });
64 | });
65 |
--------------------------------------------------------------------------------
/__tests__/List.test.ts:
--------------------------------------------------------------------------------
1 | import { getContext } from "./testUtils";
2 |
3 | describe("List", () => {
4 | let list = null;
5 | beforeAll(async () => {
6 | let ctx = await getContext();
7 | list = ctx.lists("TestList");
8 | });
9 |
10 | // describe("list.addItem()", () => {
11 | // it("Should create a list item", async () => {
12 | // let newitem = await list.addItem({ Title: "new item", MyStatus: "Green" });
13 | // expect(newitem).toHaveProperty("Title");
14 | // });
15 | // afterAll(async () => {
16 | // let items = await list.getItems();
17 | // return Promise.all(items.map((item) => list.deleteItem(item.Id)));
18 | // });
19 | // });
20 |
21 | describe("list.info()", function () {
22 | it("Should return a promise that resolves to list info", async function () {
23 | let listInfo = await list.getInfo();
24 | expect(listInfo).toBeTruthy();
25 | expect(listInfo).toHaveProperty("Title");
26 | expect(listInfo).toHaveProperty("ItemCount");
27 | expect(listInfo).toHaveProperty("ListItemEntityTypeFullName");
28 | });
29 | });
30 |
31 | describe("list.getItems()", () => {
32 | var items = null;
33 | beforeAll(async function () {
34 | items = await list.getItems();
35 | });
36 |
37 | it("Should return a promise that resolves to an array of items", function () {
38 | expect(items).toBeTruthy;
39 | expect(items).toHaveProperty("length");
40 | });
41 |
42 | it("Should return all the items in the list", async () => {
43 | let info = await list.getInfo();
44 | expect(items.length).toEqual(info.ItemCount);
45 | });
46 | });
47 |
48 | describe("list.getItems(odata)", () => {
49 | var items = null;
50 | var odata = "$filter=MyStatus eq 'Green'";
51 | beforeAll(async function () {
52 | items = await list.getItems(odata);
53 | });
54 |
55 | it("Should return a promise that resolves to an array of items", function () {
56 | expect(items).toBeTruthy();
57 | expect(items).toHaveProperty("length");
58 | });
59 |
60 | it("Should return only items that match the OData params", function () {
61 | items.forEach(function (item) {
62 | expect(item).toHaveProperty("MyStatus");
63 | expect(item.MyStatus).toBe("Green");
64 | });
65 | });
66 | });
67 |
68 | describe("list.getItemById(id)", function () {
69 | var item = null;
70 | var validId = -1;
71 | beforeAll(function (done) {
72 | list
73 | .getItems()
74 | .then(function (allItems) {
75 | validId = allItems[0].Id;
76 | return validId;
77 | })
78 | .then(function (id) {
79 | return list.getItemById(id);
80 | })
81 | .then(function (result) {
82 | item = result;
83 | done();
84 | });
85 | });
86 | it("Should return a promise that resolves to a single item", function () {
87 | expect(item).toBeTruthy();
88 | expect(item).toHaveProperty("Title");
89 | });
90 | it("Should resolve an item with a matching ID", function () {
91 | expect(item).toHaveProperty("Id");
92 | expect(item.Id).toBe(validId);
93 | });
94 | it("Should be able to return attachments using the optional odata query", async () => {
95 | let item = await list.getItemById(validId, "$expand=AttachmentFiles");
96 | expect(item).toHaveProperty("AttachmentFiles");
97 | expect(item.AttachmentFiles).toHaveProperty("length");
98 | });
99 | });
100 |
101 | describe("list.findItems(key, value)", function () {
102 | var matches = null;
103 | beforeAll(async function () {
104 | matches = await list.findItems("MyStatus", "Green");
105 | });
106 |
107 | it("Should return a promise that resolves to an array of list items", function () {
108 | expect(matches).toHaveProperty("length");
109 | expect(matches.length).toBeGreaterThan(0);
110 | });
111 | it("Should only bring back items the match the key value query", function () {
112 | matches.forEach(function (item) {
113 | expect(item).toHaveProperty("MyStatus");
114 | expect(item.MyStatus).toBe("Green");
115 | });
116 | });
117 | });
118 |
119 | describe("list.findItem(key, value)", function () {
120 | var match = null;
121 | beforeAll(async function () {
122 | match = await list.findItem("MyStatus", "Green");
123 | });
124 | it("Should only bring back an item if it matches the key value query", function () {
125 | expect(match).toBeTruthy();
126 | expect(match).toHaveProperty("MyStatus");
127 | expect(match.MyStatus).toBe("Green");
128 | });
129 | });
130 |
131 | describe("list.addItem()", function () {
132 | var newItem = {
133 | Title: "Test Created Item",
134 | MyStatus: "Red",
135 | };
136 | var insertedItem = null;
137 | beforeAll(async function () {
138 | insertedItem = await list.addItem(newItem);
139 | });
140 | it("Should return a promise that resolves with the new list item", function () {
141 | expect(insertedItem).toBeTruthy();
142 | expect(insertedItem).toHaveProperty("Id");
143 | });
144 | it("Should save the item right away so it can be queried.", async function () {
145 | let foundItem = await list.getItemById(insertedItem.Id);
146 | expect(foundItem).toHaveProperty("Title");
147 | expect(foundItem.Title).toBe(newItem.Title);
148 | });
149 | // it("Should throw an error if a invalid field is set", async function () {
150 | // let invalidItem = {
151 | // ...newItem,
152 | // InvalidColumn: "test",
153 | // };
154 | // try {
155 | // list.addItem(invalidItem);
156 | // expect("This").toBe("should have failed.");
157 | // } catch (err) {
158 | // return;
159 | // }
160 | // });
161 | });
162 |
163 | describe("list.deleteItem(id)", function () {
164 | var itemToDelete = null;
165 | beforeAll(async function () {
166 | await list.getItems("$orderby=Id").then(function (items) {
167 | itemToDelete = items[items.length - 1];
168 | return list.deleteItem(itemToDelete.Id);
169 | });
170 | });
171 | it("Should delete that item", function (done) {
172 | list
173 | .getItemById(itemToDelete.Id)
174 | .then(function () {
175 | throw "Should have failed because item has been deleted";
176 | })
177 | .catch(function () {
178 | done();
179 | });
180 | });
181 | it("Should reject the promise if the item id can not be found", function (done) {
182 | list
183 | .deleteItem(99999999)
184 | .then(function () {
185 | throw "Should have failed because id doesnt exist";
186 | })
187 | .catch(function () {
188 | done();
189 | });
190 | });
191 | });
192 |
193 | describe("list.updateItem()", function () {
194 | var itemToUpdate = null;
195 | var updates = {
196 | Title: "Updated Title",
197 | };
198 | beforeAll(async function () {
199 | let items = await list.getItems("$orderby=Id desc");
200 | itemToUpdate = items[items.length - 1];
201 | });
202 | it("Should update only the properties that were passed", async function () {
203 | let updateResult = await list.updateItem(itemToUpdate.Id, updates);
204 | let target = await list.getItemById(itemToUpdate.Id);
205 | expect(target).toHaveProperty("Title");
206 | expect(target.Title).toBe(updates.Title);
207 | });
208 | });
209 |
210 | describe("list.getItemsByCaml()", () => {
211 | let items = null;
212 | const caml = ``;
213 | beforeAll(async () => {
214 | items = await list.getItemsByCaml(caml);
215 | });
216 | it("Should return an array of list items", () => {
217 | expect(items).toHaveProperty("length");
218 | });
219 | });
220 |
221 | describe("list.getItemsByView()", () => {
222 | let items = null;
223 | beforeAll(async () => {
224 | items = await list.getItemsByView("Green Status");
225 | });
226 | it("Should return an array of list items that match the View query", () => {
227 | expect(items).toHaveProperty("length");
228 | items.forEach((item) => {
229 | expect(item).toHaveProperty("MyStatus");
230 | expect(item.MyStatus).toBe("Green");
231 | });
232 | });
233 | });
234 | });
235 |
--------------------------------------------------------------------------------
/__tests__/MMS.test.ts:
--------------------------------------------------------------------------------
1 | import { getContext } from "./testUtils";
2 |
3 | const termGroup = "_Skyline";
4 | const termset = "Departments";
5 | describe("MMS", () => {
6 | let ctx = null;
7 | describe("getTermset()", () => {
8 | let terms = null;
9 | beforeAll(async () => {
10 | ctx = await getContext();
11 | terms = await ctx.mms.getTermset(termGroup, termset);
12 | });
13 | it("Should return an array of (flat) MMS terms", () => {
14 | expect(terms).toHaveProperty("length");
15 | expect(terms.length).toBeGreaterThan(0);
16 | expect(terms[0]).toHaveProperty("path");
17 | expect(terms[0]).toHaveProperty("name");
18 | expect(terms[0]).toHaveProperty("id");
19 | expect(terms[0]).toHaveProperty("termSetName");
20 | expect(terms[0]).toHaveProperty("description");
21 | });
22 | it("Should return Term sorted by path", () => {
23 | expect(terms).toHaveProperty("length");
24 | expect(terms.length).toBeGreaterThan(1);
25 | expect(terms[0].path < terms[1].path).toBe(true);
26 | });
27 | });
28 |
29 | describe("getTermTree()", () => {
30 | let termTree = null;
31 | beforeAll(async () => {
32 | ctx = await getContext();
33 | termTree = await ctx.mms.getTermTree(termGroup, termset);
34 | });
35 | it("Should with the flattened MMS terms", () => {
36 | expect(termTree).toHaveProperty("flatTerms");
37 | expect(termTree.flatTerms.length).toBeGreaterThan(2);
38 | expect(termTree.flatTerms[0]).toHaveProperty("path");
39 | expect(termTree.flatTerms[0]).toHaveProperty("name");
40 | expect(termTree.flatTerms[0].path < termTree.flatTerms[1].path).toBe(true);
41 | });
42 |
43 | describe("termTree.getTermByName(name)", () => {
44 | it("Should return the correct term", () => {
45 | let target = termTree.flatTerms[termTree.flatTerms.length - 1];
46 | expect(target).toHaveProperty("name");
47 | expect(target).toHaveProperty("id");
48 | let result = termTree.getTermByName(target.name);
49 | expect(result).toHaveProperty("id");
50 | expect(result.id).toBe(target.id);
51 | });
52 | it("Should return null for an invalid term", () => {
53 | let result = termTree.getTermByName("BOOGA BOOGA");
54 | expect(result).toBe(null);
55 | });
56 | });
57 |
58 | describe("termTree.getTermById(termGuid)", () => {
59 | it("Should return the correct term", () => {
60 | let target = termTree.flatTerms[termTree.flatTerms.length - 1];
61 | expect(target).toHaveProperty("id");
62 | let result = termTree.getTermById(target.id);
63 | expect(result).toHaveProperty("id");
64 | expect(result.id).toBe(target.id);
65 | });
66 | it("Should return null for an invalid term", () => {
67 | let result = termTree.getTermById("BOOGA BOOGA");
68 | expect(result).toBe(null);
69 | });
70 | });
71 |
72 | describe("termTree.getTermByPath(path)", () => {
73 | it("Should return the correct term", () => {
74 | let target = termTree.flatTerms[termTree.flatTerms.length - 1];
75 | expect(target).toHaveProperty("path");
76 | let result = termTree.getTermByPath(target.path);
77 | expect(result).toHaveProperty("id");
78 | expect(result.id).toBe(target.id);
79 | });
80 | it("Should return null for an invalid term", () => {
81 | let result = termTree.getTermByPath("BOOGA BOOGA");
82 | expect(result).toBe(null);
83 | });
84 | });
85 | });
86 | });
87 |
--------------------------------------------------------------------------------
/__tests__/Profiles.test.ts:
--------------------------------------------------------------------------------
1 | import SPScript from "../src/index";
2 | import { getContext } from "./testUtils";
3 |
4 | describe("ctx.profiles", () => {
5 | describe("ctx.profiles.current()", function () {
6 | it("Should resolve to the current user's profile", async function () {
7 | try {
8 | let ctx = await getContext();
9 | let profile = await ctx.profiles.current();
10 | expect(profile).toHaveProperty("AccountName");
11 | expect(profile).toHaveProperty("Email");
12 | expect(profile.Email).toBeTruthy();
13 | expect(profile.Email.toLowerCase()).toBe(process.env.SP_USER.toLowerCase());
14 | expect(profile).toHaveProperty("PreferredName");
15 | } catch (err) {
16 | console.error("ERROR", err);
17 | }
18 | });
19 | });
20 |
21 | describe("ctx.profiles.get()", () => {
22 | it("Should resolve to the current user's profile if no email address is provided", async function () {
23 | try {
24 | let ctx = await getContext();
25 | let profile = await ctx.profiles.get();
26 | expect(profile).toHaveProperty("AccountName");
27 | expect(profile).toHaveProperty("Email");
28 | expect(profile.Email).toBeTruthy();
29 | expect(profile.Email.toLowerCase()).toBe(process.env.SP_USER.toLowerCase());
30 | expect(profile).toHaveProperty("PreferredName");
31 | } catch (err) {
32 | console.error("ERROR", err);
33 | }
34 | });
35 | });
36 |
37 | describe("ctx.profiles.get(email)", () => {
38 | it("Should resolve to the profile of the user tied to the given email address", async () => {
39 | try {
40 | const EMAIL = "wspiering@skylinespark.onmicrosoft.com";
41 | let ctx = await getContext();
42 | let profile = await ctx.profiles.get(EMAIL);
43 | expect(profile).toHaveProperty("AccountName");
44 | expect(profile).toHaveProperty("Email");
45 | expect(profile.Email).toBeTruthy();
46 | expect(profile.Email.toLowerCase()).toBe(EMAIL.toLowerCase());
47 | expect(profile).toHaveProperty("PreferredName");
48 | } catch (err) {
49 | console.error("ERROR", err);
50 | }
51 | });
52 | it("Should reject the Promise for an invalid email", async () => {
53 | try {
54 | const EMAIL = "INVALIDg@skylinespark.onmicrosoft.com";
55 | let ctx = await getContext();
56 | return await expect(ctx.profiles.get(EMAIL)).rejects.toThrowError();
57 | } catch (err) {
58 | console.error("ERROR", err);
59 | }
60 | });
61 | });
62 |
63 | describe("ctx.profiles.setProperty(key, value)", () => {
64 | it("Should update the current user's profile", async () => {
65 | try {
66 | const aboutMeValue = "Hi there. I was updated with SPScript v5";
67 | let ctx = await getContext();
68 | await ctx.profiles.setProperty("AboutMe", aboutMeValue);
69 | let profile = await ctx.profiles.current();
70 | expect(profile).toHaveProperty("AboutMe");
71 | expect(profile["AboutMe"]).toBe(aboutMeValue);
72 | } catch (err) {
73 | console.error("ERROR", err);
74 | }
75 | });
76 | });
77 |
78 | describe.skip("ctx.profiles.setProperty(key, value, email)", () => {
79 | const EMAIL = "wspiering@skylinespark.onmicrosoft.com";
80 | it("Should update the targeted user's profile", async () => {
81 | const aboutMeValue = "Hi there. I was updated with SPScript #2";
82 | let ctx = await getContext();
83 | await ctx.profiles.setProperty("AboutMe", aboutMeValue, EMAIL);
84 | let profile = await ctx.profiles.get(EMAIL);
85 | expect(profile).toHaveProperty("AboutMe");
86 | expect(profile["AboutMe"]).toBe(aboutMeValue);
87 | });
88 | });
89 | });
90 |
--------------------------------------------------------------------------------
/__tests__/Search.test.ts:
--------------------------------------------------------------------------------
1 | import { getContext } from "./testUtils";
2 | import Context from "../src/Context";
3 |
4 | describe("Search", () => {
5 | let ctx: Context = null;
6 | beforeAll(async () => {
7 | ctx = await getContext();
8 | });
9 | describe("search.query(searchText)", () => {
10 | it("Should return a Promise that resolves to a SearchResults object", async () => {
11 | let result = await ctx.search.query("Andrew");
12 | expect(result).toBeTruthy();
13 | expect(result).toHaveProperty("resultsCount");
14 | expect(result).toHaveProperty("totalResults");
15 | expect(result).toHaveProperty("items");
16 | expect(result).toHaveProperty("refiners");
17 | expect(result.items).toHaveProperty("length");
18 | });
19 | });
20 |
21 | describe("ctx.search.query(queryText, queryOptions)", function () {
22 | it("Should obey the extra query options that were passed", async function () {
23 | var queryText = "andrew";
24 | var options = {
25 | rowlimit: 1,
26 | };
27 | let result = await ctx.search.query(queryText, options);
28 | expect(result).toBeTruthy();
29 | expect(result).toHaveProperty("resultsCount");
30 | expect(result).toHaveProperty("totalResults");
31 | expect(result).toHaveProperty("items");
32 | expect(result).toHaveProperty("refiners");
33 | expect(result.items).toHaveProperty("length");
34 | expect(result.items.length).toBe(1);
35 | });
36 | });
37 |
38 | describe("ctx.search.query(queryText, queryOptions) - w/ Refiners", function () {
39 | it("Should return SearchResults that include a refiners Array", async () => {
40 | var refinerName = "FileType";
41 | var queryText = "andrew";
42 | var options = {
43 | refiners: `${refinerName}`,
44 | };
45 | let result = await ctx.search.query(queryText, options);
46 | expect(result).toBeTruthy();
47 | expect(result).toHaveProperty("resultsCount");
48 | expect(result).toHaveProperty("totalResults");
49 | expect(result).toHaveProperty("items");
50 | expect(result).toHaveProperty("refiners");
51 | expect(result.items).toHaveProperty("length");
52 | expect(result.refiners).toHaveProperty("length");
53 | expect(result.refiners.length).toBeGreaterThan(0);
54 | var firstRefiner = result.refiners[0];
55 | expect(firstRefiner).toHaveProperty("RefinerName");
56 | expect(firstRefiner).toHaveProperty("RefinerOptions");
57 | expect(firstRefiner.RefinerName).toBe(refinerName);
58 | });
59 | });
60 |
61 | describe("ctx.search.people(queryText)", function () {
62 | it("Should only return search results that are people", async () => {
63 | let result = await ctx.search.people("Andrew");
64 | expect(result).toHaveProperty("items");
65 | expect(result.items).toHaveProperty("length");
66 | expect(result.items.length).toBeGreaterThan(0);
67 | result.items.forEach((item) => {
68 | expect(item).toHaveProperty("AccountName");
69 | expect(item).toHaveProperty("PreferredName");
70 | expect(item).toHaveProperty("AboutMe");
71 | expect(item).toHaveProperty("WorkEmail");
72 | expect(item).toHaveProperty("PictureURL");
73 | });
74 | });
75 | });
76 |
77 | describe("ctx.search.sites(queryText, scope)", function () {
78 | it("Should only return search results that are sites", async () => {
79 | let result = await ctx.search.sites("");
80 | expect(result).toHaveProperty("items");
81 | expect(result.items).toHaveProperty("length");
82 | expect(result.items.length).toBeGreaterThan(0);
83 | result.items.forEach((item) => {
84 | expect(item).toHaveProperty("Path");
85 | expect(item).toHaveProperty("contentclass");
86 | expect(item.contentclass).toBe("STS_Web");
87 | });
88 | });
89 | });
90 | });
91 |
--------------------------------------------------------------------------------
/__tests__/Securable.test.ts:
--------------------------------------------------------------------------------
1 | import { getContext } from "./testUtils";
2 | import Context from "../src/Context";
3 |
4 | describe("Securable (web and List)", () => {
5 | let ctx: Context;
6 | beforeAll(async () => {
7 | ctx = await getContext();
8 | });
9 |
10 | describe("web.permissions.check()", () => {
11 | it("Should check the permissions of the current user", async () => {
12 | let permissions = await ctx.web.permissions.check();
13 | expect(permissions).toBeTruthy();
14 | expect(permissions).toHaveProperty("length");
15 | expect(permissions.length).toBeGreaterThan(0);
16 | // console.log("ME: ", permissions);
17 | });
18 | it("Should check the permissions of the of the specified user", async () => {
19 | let permissions = await ctx.web.permissions.check("apetersen@skylinespark.onmicrosoft.com");
20 | expect(permissions).toBeTruthy();
21 | expect(permissions).toHaveProperty("length");
22 | expect(permissions.length).toBeGreaterThan(0);
23 | // console.log("Sarah", permissions);
24 | });
25 | });
26 |
27 | describe("web.permissions.getRoleAssignments()", () => {
28 | it("Should return an array of {member, roles} objects", async () => {
29 | let roleAssignments = await ctx.web.permissions.getRoleAssignments();
30 | expect(roleAssignments).toHaveProperty("length");
31 | expect(roleAssignments.length).toBeGreaterThan(0);
32 |
33 | expect(roleAssignments[0]).toHaveProperty("member");
34 | expect(roleAssignments[0]).toHaveProperty("roles");
35 | expect(roleAssignments[0].member).toHaveProperty("name");
36 | expect(roleAssignments[0].member).toHaveProperty("login");
37 | expect(roleAssignments[0].member).toHaveProperty("id");
38 |
39 | expect(roleAssignments[0].roles).toHaveProperty("length");
40 | expect(roleAssignments[0].roles.length).toBeGreaterThan(0);
41 |
42 | expect(roleAssignments[0].roles[0]).toHaveProperty("name");
43 | });
44 | });
45 |
46 | describe("list.permissions.check()", () => {
47 | it("Should check the permissions of the current user", async () => {
48 | let permissions = await ctx.lists("Site Pages").permissions.check();
49 | expect(permissions).toBeTruthy();
50 | expect(permissions).toHaveProperty("length");
51 | expect(permissions.length).toBeGreaterThan(0);
52 | // console.log("ME: ", permissions);
53 | });
54 | it("Should check the permissions of the of the specified user", async () => {
55 | let permissions = await ctx.web.permissions.check("apetersen@skylinespark.onmicrosoft.com");
56 | expect(permissions).toBeTruthy();
57 | expect(permissions).toHaveProperty("length");
58 | expect(permissions.length).toBeGreaterThan(0);
59 | // console.log("Sarah", permissions);
60 | });
61 | });
62 |
63 | describe("list.permissions.getRoleAssignments()", () => {
64 | it("Should return an array of {member, roles} objects", async () => {
65 | let roleAssignments = await ctx.lists("Site Pages").permissions.getRoleAssignments();
66 | expect(roleAssignments).toHaveProperty("length");
67 | expect(roleAssignments.length).toBeGreaterThan(0);
68 |
69 | expect(roleAssignments[0]).toHaveProperty("member");
70 | expect(roleAssignments[0]).toHaveProperty("roles");
71 | expect(roleAssignments[0].member).toHaveProperty("name");
72 | expect(roleAssignments[0].member).toHaveProperty("login");
73 | expect(roleAssignments[0].member).toHaveProperty("id");
74 |
75 | expect(roleAssignments[0].roles).toHaveProperty("length");
76 | expect(roleAssignments[0].roles.length).toBeGreaterThan(0);
77 |
78 | expect(roleAssignments[0].roles[0]).toHaveProperty("name");
79 | });
80 | });
81 | });
82 |
--------------------------------------------------------------------------------
/__tests__/Web.test.ts:
--------------------------------------------------------------------------------
1 | import { getContext } from "./testUtils";
2 | import Context from "../src/Context";
3 |
4 | describe("ctx.web", () => {
5 | let ctx: Context;
6 | beforeAll(async () => {
7 | ctx = await getContext();
8 | });
9 | describe("ctx.web.getInfo()", function () {
10 | it("Should return a promise that resolves to web info", async () => {
11 | let webInfo = await ctx.web.getInfo();
12 | expect(webInfo).toHaveProperty("Url");
13 | expect(webInfo).toHaveProperty("Title");
14 | });
15 | });
16 |
17 | describe("ctx.web.getSubsites()", function () {
18 | it("Should return a promise that resolves to an array of subsite web infos.", async () => {
19 | let subsites = await ctx.web.getSubsites();
20 | console.log("subsites", subsites);
21 | expect(subsites).toBeInstanceOf(Array);
22 | });
23 | });
24 |
25 | describe("ctx.web.getUser()", function () {
26 | it("Should return a promise that resolves to a user", async () => {
27 | let user = await ctx.web.getUser();
28 | expect(user).toHaveProperty("Id");
29 | expect(user).toHaveProperty("LoginName");
30 | expect(user).toHaveProperty("Email");
31 | });
32 | it("Should return the current user if no email is given", async () => {
33 | let user = await ctx.web.getUser();
34 | expect(user.Email).toBe(process.env.SP_USER);
35 | });
36 | });
37 |
38 | describe("ctx.web.getUser(email)", function () {
39 | const EMAIL = "wspiering@skylinespark.onmicrosoft.com";
40 | it("Should return a promise that resolves to a user", async () => {
41 | let user = await ctx.web.getUser(EMAIL);
42 | expect(user).toHaveProperty("Id");
43 | expect(user).toHaveProperty("LoginName");
44 | expect(user).toHaveProperty("Email");
45 | });
46 | it("Should return the current user if no email is given", async () => {
47 | let user = await ctx.web.getUser(EMAIL);
48 | expect(user.Email).toBe(EMAIL);
49 | });
50 | });
51 |
52 | describe("ctx.web.getFile(serverRelativeFilepath)", () => {
53 | it("Should return a promise that resolves to a file object", async () => {
54 | let fileUrl = "/sites/spscript/sitepages/home.aspx";
55 | let file = await ctx.web.getFile(fileUrl);
56 | expect(file).toBeTruthy();
57 | expect(file).toHaveProperty("Name");
58 | expect(file).toHaveProperty("ETag");
59 | expect(file).toHaveProperty("UIVersionLabel");
60 | expect(file).toHaveProperty("Exists");
61 | });
62 | });
63 |
64 | describe("ctx.web.copyFile(serverRelativeSourceUrl, serverRelativeDestUrl)", function () {
65 | let sourceUrl = "/sites/spscript/shared documents/testfile.txt";
66 | let filename = "testfile-" + Date.now() + ".txt";
67 | let destinationUrl = "/sites/spscript/shared documents/" + filename;
68 | it("Should return a promise, and once resolved, the new (copied) file should be retrievable.", async () => {
69 | let sourceFile = await ctx.web.getFile(sourceUrl);
70 | expect(sourceFile).toBeTruthy();
71 | await ctx.web.copyFile(sourceUrl, destinationUrl);
72 | let newFile = await ctx.web.getFile(destinationUrl);
73 | expect(newFile).toBeTruthy();
74 | expect(newFile).toHaveProperty("Name");
75 | expect(newFile.Name).toBe(filename);
76 | });
77 | });
78 | });
79 |
--------------------------------------------------------------------------------
/__tests__/namespace.test.ts:
--------------------------------------------------------------------------------
1 | import SPScript from "../src/index";
2 | require("dotenv").config();
3 |
4 | describe("SPScript Namespace", () => {
5 | test("Should have a 'SPScript.createContext()' method", function() {
6 | expect(SPScript).toHaveProperty("createContext");
7 | expect(typeof SPScript.createContext).toBe("function");
8 | });
9 | test("Should have a 'SPScript.utils' namespace", function() {
10 | expect(SPScript).toHaveProperty("utils");
11 | });
12 | });
13 |
--------------------------------------------------------------------------------
/__tests__/queryString.test.ts:
--------------------------------------------------------------------------------
1 | import { fromObj, toObj } from "../src/utils/queryString";
2 |
3 | describe("Query String Utils", () => {
4 | describe("fromObj(obj)", () => {
5 | it("Should turn a basic object into a querystring", () => {
6 | let obj = {
7 | foo: "one",
8 | bar: 2,
9 | };
10 | let qs = fromObj(obj);
11 | expect(qs).toBe("foo=one&bar=2");
12 | });
13 | it("Should automatically run encodeURIComponent", () => {
14 | let obj = {
15 | foo: "thing one",
16 | bar: 2,
17 | };
18 |
19 | let qs = fromObj(obj);
20 | expect(qs).toBe("foo=thing%20one&bar=2");
21 | });
22 |
23 | it("Should allow passing a flag to wrap values with single quotes (used by search service calls).", () => {
24 | let obj = {
25 | foo: "thing one",
26 | bar: 2,
27 | };
28 |
29 | let qs = fromObj(obj, true);
30 | expect(qs).toBe("foo='thing%20one'&bar='2'");
31 | });
32 | it("SHould handle a null object", () => {
33 | let qs = fromObj(null);
34 | expect(qs).toBe("");
35 | });
36 | it("SHould handle a undefined object", () => {
37 | let qs = fromObj(undefined);
38 | expect(qs).toBe("");
39 | });
40 | });
41 |
42 | describe("toObj", () => {
43 | it("Should handle a basic object", () => {
44 | let str = "foo=one&bar=2";
45 | let obj = toObj(str);
46 | expect(obj).toHaveProperty("foo");
47 | expect(obj).toHaveProperty("bar");
48 | expect(obj.foo).toBe("one");
49 | expect(obj.bar).toBe("2");
50 | });
51 | it("Should handle decoding the values", () => {
52 | let str = "foo=thing%20one&bar=2";
53 | let obj = toObj(str);
54 | expect(obj).toHaveProperty("foo");
55 | expect(obj).toHaveProperty("bar");
56 | expect(obj.foo).toBe("thing one");
57 | expect(obj.bar).toBe("2");
58 | });
59 | it("Should handle a ? at the beginning of the string", () => {
60 | let str = "?foo=thing%20one&bar=2";
61 | let obj = toObj(str);
62 | expect(obj).toHaveProperty("foo");
63 | expect(obj).toHaveProperty("bar");
64 | expect(obj.foo).toBe("thing one");
65 | expect(obj.bar).toBe("2");
66 | });
67 | it("Should handle an empty string", () => {
68 | let obj = toObj("");
69 | expect(obj).toBeTruthy();
70 | });
71 | it("Should handle just a '?'", () => {
72 | let obj = toObj("");
73 | expect(obj).toBeTruthy();
74 | });
75 | });
76 | });
77 |
--------------------------------------------------------------------------------
/__tests__/testUtils.ts:
--------------------------------------------------------------------------------
1 | import * as SPScript from "../src/index";
2 | import "isomorphic-fetch";
3 | require("dotenv").config();
4 |
5 | let siteUrl = process.env.SITE_URL;
6 |
7 | export const getContext = async () => {
8 | return SPScript.createContext(siteUrl, { headers: JSON.parse(process.env.AUTH_HEADERS) });
9 | };
10 |
--------------------------------------------------------------------------------
/docs/.nojekyll:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/DroopyTersen/spscript/282c6bfaff0e217cbdbeed6baf47ee0cd56c1749/docs/.nojekyll
--------------------------------------------------------------------------------
/docs/arbitrary-requests.md:
--------------------------------------------------------------------------------
1 | # Arbitrary API Requests
2 |
3 | If SPScript doesn't have a method that specifically solves your needs, you can always use the base request helpers, `ctx.get` and `ctx.post`. These methods expect you to pass an endpoint path relative to `/_api`.
4 |
5 | > **IMPORTANT!** These methods expect you to pass an endpoint path relative to `/_api`.
6 |
7 | For example, given the API url, `https://TENANT.sharepoint.com/sites/YOURSITE/_api/web/lists/getByTitle('Site%20Pages')/items`, you'd pass `/web/lists/getByTitle('Site%20Pages')/items`.
8 |
9 | ## get
10 |
11 | Takes an API path and perform the REST API `GET` request.
12 |
13 | - `ctx.get(apiPath)`
14 | - `ctx.get(apiPath, reqOpts)`
15 |
16 | _Get all Company Themes_
17 |
18 | ```javascript
19 | let data = await ctx.get("/thememanager/GetTenantThemingOptions");
20 | let themes = data.themePreviews;
21 | ```
22 |
23 | ## post
24 |
25 | - `ctx.post(apiPath, payload)`
26 | - `ctx.post(apiPath, payload, verb)`
27 |
28 | Takes an API path and a payload, and performs a `POST` request that includes the necessary headers and RequestDigest. If you pass a `verb`, it will place that in the `X-HTTP-Method` header.
29 |
30 | ```javascript
31 | let endpoint =
32 | "/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.ApplySiteDesign";
33 | let payload = { siteDesignId: siteDesign.Id, webUrl: siteUrl };
34 | await ctx.post(endpoint, payload);
35 | ```
36 |
37 | **\_post**
38 |
39 | - `ctx._post(apiPath, payload, reqOptions)`
40 |
41 | There is also a`ctx.post`which does the same thing as`authorizedPost`except that it doesn't handle ensuring the RequestDigest is included in the headers. It is rare that you want to make a`POST`without the`digest`. The only reason you'd reach for this method is if you want full control over the request headers.
42 |
43 | ## More Examples
44 |
45 | _Applying a Site Design by name_
46 |
47 | ```javascript
48 | async function getSiteDesign(siteUrl, siteDesignName) {
49 | const ctx = SPScript.createContext(siteUrl);
50 | // GetSiteDesigns actually requires a POST
51 | let data = await ctx.post(
52 | "/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.GetSiteDesigns"
53 | );
54 | let siteDesigns = data.value;
55 | return siteDesigns.find((sd) => sd.Title === siteDesignName);
56 | }
57 |
58 | async function applySiteDesign(siteUrl, siteDesignName) {
59 | // Take the name and try to find a Site Design with that Title
60 | let siteDesign = await getSiteDesign(siteUrl, siteDesignName);
61 | if (!siteDesign) throw new Error("Couldn't find a site design with the name, " + siteDesignName);
62 | let ctx = SPScript.createContext(siteUrl);
63 |
64 | let endpoint =
65 | "/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.ApplySiteDesign";
66 | let payload = { siteDesignId: siteDesign.Id, webUrl: siteUrl };
67 | await ctx.post(endpoint, payload);
68 | }
69 | ```
70 |
71 | ## Source Code
72 |
73 | Github Source: [/src/context/Context.ts](https://github.com/DroopyTersen/spscript/blob/master/src/context/Context.ts#L71)
74 |
--------------------------------------------------------------------------------
/docs/coverpage.md:
--------------------------------------------------------------------------------
1 | # SPScript
2 |
3 | > Making the SharePoint REST API easy
4 |
5 | - Easy querying of list items
6 | - Add and Update list items with a single line of code
7 | - No more pulling out hair with working with Search endpoints
8 | - Much more...
9 |
10 | [Get Started](introduction)
11 | [GitHub](https://github.com/droopytersen/spscript)
12 |
--------------------------------------------------------------------------------
/docs/getting-started.md:
--------------------------------------------------------------------------------
1 | # Getting Started
2 |
3 | ## Installation
4 |
5 | Add the SPScript `npm` package to your project
6 |
7 | _NPM_
8 |
9 | ```shell
10 | npm install spscript
11 | ```
12 |
13 | _Yarn_
14 |
15 | ```shell
16 | yarn add spscript
17 | ```
18 |
19 | ## Importing
20 |
21 | You can use SPScript in your Javascript/Typescript files with:
22 |
23 | ```javascript
24 | import SPScript from "spscript";
25 | ```
26 |
27 | **ProTip: Dynamically/Temporarily add SPScript to a Modern page with Dev Tools**
28 |
29 | You can enter the following into a browser console to dynamically load SPScript on a page.
30 |
31 | ```javascript
32 | let script = document.createElement("script");
33 | script.src = "https://unpkg.com/spscript@beta/dist/spscript.browser.js";
34 | document.head.appendChild(script);
35 | ```
36 |
37 | ## SPScript Context
38 |
39 | Almost everything in SPScript is based off an SPScript `Context` class.
40 |
41 | - An SPScript **Context** is tied to specific SharePoint site.
42 | - You get a **Context** by calling `SPScript.createContext(siteUrl)`.
43 |
44 | > You get a **Context** by calling `SPScript.createContext(siteUrl)`.
45 |
46 | _This line of code is the entry point to almost everything SPScript provides._
47 |
48 | ```javascript
49 | let ctx = SPScript.createContext(siteUrl);
50 | ```
51 |
52 | _Example Usage: Get the News Pages of the specified site._
53 |
54 | ```javascript
55 | import SPScript from "spscript";
56 |
57 | const getPublishedNews = async function (siteUrl) {
58 | let ctx = SPScript.createContext(siteUrl);
59 | let pages = await ctx.lists("Site Pages").findItems("PromotedState", 2);
60 | console.log(pages); // This will show an Array of Page List Items
61 | return pages;
62 | };
63 | ```
64 |
65 | Throughout the docs you'll see a variable, `ctx`, representing an instance of an SPScript `Context`.
66 |
67 | ## Troubleshooting
68 |
69 | If you are using Typescript, you may have to use the syntax:
70 |
71 | ```javascript
72 | import * as SPScript from "spscript";
73 | ```
74 |
75 | If you don't like that, add `"allowSyntheticDefaultImports": true` to your `tsconfig.json`.
76 |
--------------------------------------------------------------------------------
/docs/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | spscript - ShareP0oint Rest Api Wrappers
6 |
7 |
8 |
12 |
16 |
28 |
29 |
30 |
31 |
73 |
74 |
75 |
76 |
77 |
78 |
79 |
80 |
81 |
82 |
83 |
84 |
85 |
86 |
87 |
--------------------------------------------------------------------------------
/docs/introduction.md:
--------------------------------------------------------------------------------
1 | # SPScript
2 |
3 | SPScript is a JavaScript library meant to simplify working with the SharePoint REST API.
4 |
5 | - Easy querying of list items
6 | - Add and Update list items with a single line of code
7 | - No more pulling out hair with working with SharePoint Search endpoints
8 | - Profile service helpers
9 | - Generic `GET` and `POST` helpers to simplify calling arbitrary endpoints
10 | - Full intellisense in VSCode
11 | - Works server-side in Node.js
12 |
13 | For example, lets say you wanted to get all of the "Active" items in the "Tasks" list and set them to "Canceled", then add a new item.
14 |
15 | ```javascript
16 | // Create an SPScript Context targeting your site
17 | let ctx = SPScript.createContext("https://TENANT.shareoint.com/sites/YOURSITE");
18 | let tasksList = ctx.lists("Tasks");
19 |
20 | // Find all items in the "Tasks" list with a "Status" of "Active"
21 | let activeTasks = await tasksList.findItems("Status", "Active");
22 |
23 | // Loop through each task and update its Status
24 | for (task of activeTasks) {
25 | await tasksList.updateItem(task.Id, { Status: "Canceled" });
26 | }
27 |
28 | //Add a new "Active" task
29 | let newTask = await tasksList.addItem({
30 | Title: "Hello from SPScript",
31 | Status: "Active"
32 | });
33 | ```
34 |
35 | **PnPJS Comparison**
36 |
37 | > _"Wait, isn't this what [PnPJS](https://pnp.github.io/pnpjs/) does too?"_
38 |
39 | Pretty much. But, PnPJS comes with an almost 200kB hit to your bundle size. SPScript is less than 30kB. That being said, PnPJS does WAAAY more than SPScript.
40 |
41 | - If you are just trying to query some List Items or use the Search Service, then SPScript could be a way to improve performance.
42 | - If you are trying to develop an advanced client-side provisioning application, go with [PnPJS](https://pnp.github.io/pnpjs/).
43 |
--------------------------------------------------------------------------------
/docs/list-operations.md:
--------------------------------------------------------------------------------
1 | # List Operations
2 |
3 | ## Setup
4 |
5 | Performing list operations you need to:
6 |
7 | 1. Create an SPScript Context
8 | 2. Get a list by Title
9 |
10 | These 2 steps are synchronous. They are really just building up the base REST API url for you.
11 |
12 | ```javascript
13 | // Create a Context and get a list by Title
14 | let ctx = SPScript.createContext("https://TENANT.sharepoint.com/sites/SITE");
15 | let list = ctx.lists("YOUR LIST TITLE");
16 |
17 | // This call is async, it actually makes a REST request
18 | let items = await list.getItems();
19 | ```
20 |
21 | ## getInfo
22 |
23 | - `getInfo() => ListProperties`
24 |
25 | Get the properties of the list. Stuff like `ItemCount`, `Hidden`, etc...
26 |
27 | ```javascript
28 | let info = await ctx.lists("Featured Links").getInfo();
29 | console.log("List Item Count", info.ItemCount);
30 | ```
31 |
32 | ## checkExists
33 |
34 | - `checkExists() => boolean`
35 |
36 | Check whether a specific list exists
37 |
38 | ```javascript
39 | let exists = await ctx.lists("Featured Links").checkExists();
40 | ```
41 |
42 | ## getItems
43 |
44 | - `getItems()`
45 | - `getItems(odata)`
46 |
47 | _Get all items in the "Shared Documents" Library_
48 |
49 | ```javascript
50 | let items = await ctx.lists("Shared Documents").getItems();
51 | ```
52 |
53 | You can also pass an optional OData string, giving you full control over your `$filter`, `$orderby`, `$select`, `$expand`, and `$top`.
54 |
55 | _Get the file names of the last 5 modified "Shared Documents"_
56 |
57 | ```javascript
58 | let items = await ctx
59 | .lists("Shared Documents")
60 | .getItems("$select=FileLeafRef&$orderby=Modified desc&$top=5");
61 | let filenames = items.map((item) => item.FileLeafRef);
62 | ```
63 |
64 | ## getItemById
65 |
66 | - `getItemById(id)`
67 | - `getItemById(id, odata)`
68 |
69 | If you know they ID of the SharePoint list item, you can get it directly with `getItemById`.
70 |
71 | ```javascript
72 | let item = await ctx.lists("Site Pages").getItemById(4);
73 | ```
74 |
75 | ## findItems
76 |
77 | - `findItems(fieldName, value)`
78 | - `findItems(fieldName, value, odata)`
79 |
80 | If you want to find all items that match a specified Field value, you can use `findItems`.
81 |
82 | _Find all pages with a Category of "New Hire"_
83 |
84 | ```javascript
85 | let newHireAnnouncements = await ctx.lists("Site Pages").findItems("Category", "New Hire");
86 | ```
87 |
88 | You can use the optional odata argument for more control (just don't use `$filter` because `findItems` is already taking care of that for you).
89 |
90 | _Find the 5 most recent "New Hire" pages_
91 |
92 | ```javascript
93 | let newHireAnnouncements = await ctx
94 | .lists("Site Pages")
95 | .findItems("Category", "New Hire", "$orderby=Modified desc&$top=5");
96 | ```
97 |
98 | ## findItem
99 |
100 | - `findItem(fieldName, value)`
101 | - `findItem(fieldName, value, odata)`
102 |
103 | The same as `findItems` except that it returns a single item (as an `Object`) instead of an `Array` of items.
104 |
105 | _Find the Blog post with a Title of "SPScript is Awesome!"_
106 |
107 | ```javascript
108 | let item = await ctx.lists("Site Pages").findItem("Title", "SPScript is Awesome!");
109 | ```
110 |
111 | ## getItemsByView
112 |
113 | - `getItemsByView(viewName)`
114 |
115 | Get items based on an existing List View. This way the user can configure the filtering and sorting.
116 |
117 | _Get tasks based on the "Prioritized" view_
118 |
119 | ```javascript
120 | let tasks = await ctx.lists("Tasks").getItemsByView("Prioritized Tasks");
121 | ```
122 |
123 | ## getItemsByCaml
124 |
125 | - `getItemsByCaml(caml)`
126 |
127 | Instead of OData, pass a CAML query. The parent node should be a ``. Something like:
128 |
129 | ```xml
130 |
131 |
132 | ...
133 |
134 |
135 | ```
136 |
137 | I've only found one scenario where I need this, querying by Calculated Fields. You can't do that via OData.
138 |
139 | ## Query Examples
140 |
141 | _Find all Events with a Category of "Birthday"_
142 |
143 |
144 |
145 | #### ** Easiest **
146 |
147 | **`findItems(fieldName, value)`**
148 |
149 | For when you want items based on a single field value.
150 |
151 | You can pass an optional OData string as a third argument to control things like `$orderby`, `$select`, `$expand`, and `$top`.
152 |
153 | ```javascript
154 | let ctx = SPScript.createContext("https://MYTENANT.sharepoint.com/sites/MYSITE");
155 | let items = await ctx.lists("Events").findItems("Category", "Birthday");
156 | ```
157 |
158 | #### ** Easy **
159 |
160 | **`getItems(odata)`**
161 |
162 | Takes an arbtrary OData string, giving you full control over your `$filter`, `$orderby`, `$select`, `$expand`, and `$top`.
163 |
164 | ```javascript
165 | let ctx = SPScript.createContext("https://MYTENANT.sharepoint.com/sites/MYSITE");
166 | let items = await ctx.lists("Events").getItems("$filter=Category eq 'Birthday'");
167 | ```
168 |
169 | #### ** Long-winded**
170 |
171 | **`ctx.get(apiUrl)`**
172 |
173 | You can always make a generic `GET` request using SPScript's helper to setup the proper headers.
174 |
175 | ```javascript
176 | let ctx = SPScript.createContext("https://MYTENANT.sharepoint.com/sites/MYSITE");
177 | let endpoint = "/web/lists/getByTitle('Events')/items?$filter=Category eq 'Birthday'";
178 | let data = await ctx.get(endpoint);
179 | let items = data.d.results;
180 | ```
181 |
182 |
183 |
184 | ## addItem
185 |
186 | - `addItem(newItem)`
187 |
188 | Allows you to pass a JavaScript object, where each property aligns with a SharePoint Field name on the target list. It is async and will give you back the new List Item which will include new properties like the SharePoint ID.
189 |
190 | ```javascript
191 | var itemToCreate = {
192 | Title: "My New Task",
193 | Status: "Not Started",
194 | RemainingHours: 12,
195 | };
196 | let listItem = await ctx.lists("Tasks").addItem(itemToCreate);
197 | ```
198 |
199 | If your `newItem` object has a property that **isn't** a Field on the List, the call will fail.
200 |
201 | ## updateItem
202 |
203 | - `updateItem(id, updates)`
204 |
205 | Allows you to pass a JavaScript object, where each property aligns with a SharePoint Field name on the target list.
206 |
207 | - Does a `MERGE` so you don't have to pass all the field values.
208 | - If your updates object has a property that **isn't** a Field on the List, the call will fail.
209 |
210 | ```javascript
211 | var updates = { Status: "Completed", RemainingHours: 0 };
212 | await ctx.lists("Tasks").updateItem(29, updates);
213 | ```
214 |
215 | ## deleteItem
216 |
217 | - `deleteItem(id)`
218 |
219 | Deletes the List Item with the specified Id.
220 |
221 | _Delete the Shared Documents item with an ID of 47_
222 |
223 | ```javascript
224 | await ctx.lists("Shared Documents").deleteItem(47);
225 | ```
226 |
227 | ## Source Code
228 |
229 | Github Source: [/src/list/List.ts](https://github.com/DroopyTersen/spscript/blob/master/src/list/List.ts)
230 |
--------------------------------------------------------------------------------
/docs/mms.md:
--------------------------------------------------------------------------------
1 | # Managed Metadata
2 |
3 | A helper for bringing back MMS terms. Dependency free and done in a single call. Wraps the `Client.svc` service because there is currently no Rest endpoing for MMS (it's supposedly coming...).
4 |
5 | ## getTermset
6 |
7 | Returns a flat list of the terms in the specified termset. Pass in the term group and the termset name.
8 |
9 | ```javascript
10 | let terms = ctx.mms.getTermset("Events Registration", "Event Types");
11 | ```
12 |
13 | ## getTermsetTree
14 |
15 | Returns a tree data structure representing the specified termset. Useful when conveying nested relationships with terms.
16 |
17 | ```javascript
18 | let termTree = ctx.mms.getTermTree("Inventory Tracking", "Locations");
19 | let term1 = termTree.getTermByName("Store 123");
20 | let term2 = termTree.getTermByPath("Stores/Midwest/Store 123");
21 | let term3 = termTree.getTermById("");
22 | ```
23 |
24 | **MMSTerm**
25 |
26 | ```javascript
27 | export interface MMSTerm {
28 | id: string;
29 | sortOrder: number;
30 | description: string;
31 | name: string;
32 | path: string;
33 | termSetName: string;
34 | properties: {
35 | [key: string]: string,
36 | };
37 | children: MMSTerm[];
38 | }
39 | ```
40 |
--------------------------------------------------------------------------------
/docs/modifying-listitems.md:
--------------------------------------------------------------------------------
1 | # Modifying List Items
2 |
3 | ## Setup
4 |
5 | If you need to modify list items, you need to:
6 |
7 | 1. Create an SPScript Context, `SPScript.createContext(siteUrl)`
8 | 2. Get a list by Title, `ctx.lists("LIST TITLE")`
9 |
10 | These 2 steps are synchronous,they are really just building up the base REST API url for you.
11 |
12 | ```javascript
13 | // Create a Context and get a list by Title
14 | let ctx = SPScript.createContext("https://TENANT.sharepoint.com/sites/SITE");
15 | let list = ctx.lists("YOUR LIST TITLE");
16 |
17 | // This call is async, it actually makes a REST request
18 | let newItem = await list.addItem({ Title: "New Thing" });
19 | ```
20 |
21 | ## Source Code
22 |
23 | Github Source: [/src/list/List.ts](https://github.com/DroopyTersen/spscript/blob/master/src/list/List.ts)
24 |
--------------------------------------------------------------------------------
/docs/nodejs.md:
--------------------------------------------------------------------------------
1 | # Serverside w/ Node.js
2 |
3 | ## Fetch Polyfill
4 |
5 | In order to work in Node.js, you need to import `isomorphic-fetch`.
6 |
7 | _Just add this line to the top of your Node.js main file_
8 |
9 | ```javascript
10 | require("isomorphic-fetch");
11 | ```
12 |
13 | This is due to some library design decisions I made:
14 |
15 | - I don't want to include an isomorphic "Request" library, SPScript is only 28kb, that could double the size.
16 | - I'm done monkeying with `XMLHttpRequest`, `fetch` is sooo much nicer to work with.
17 | - I don't want to assume SPScript's consumers will want me to include a `fetch` polyfill (for IE or Node).
18 | - If you need one, you'll know, and you'll already be polyfilling, you shouldn't want me to do that for you
19 |
20 | ## Cookie Auth (username, password)
21 |
22 | You can pass a `headers` property to the `ContextOptions` param in `createContext`.
23 |
24 | For example you could use [node-sp-auth](https://www.npmjs.com/package/node-sp-auth) to log in with username and password (only do this serverside), then pass the Fed Auth cookie you receive to SPScript:
25 |
26 | ```javascript
27 | // Use node-sp-auth to get a Fed Auth cookie.
28 | // This cookie can be include in the headers of REST calls to authorize them.
29 | const spauth = require("node-sp-auth");
30 |
31 | let auth = await spauth.getAuth(process.env.SITE_URL, {
32 | username: process.env.SP_USER,
33 | password: process.env.PASSWORD,
34 | });
35 | // Pass the auth headers to SPScript via the optional ContextOptions param
36 | let ctx = SPScript.createContext(siteUrl, { headers: auth.headers });
37 | let webInfo = await ctx.web.getInfo();
38 | console.log(webInfo);
39 | ```
40 |
41 | ## App Context (OAuth)
42 |
43 | You can also use the SharePoint App Registration process to login via "AppContext")
44 |
45 | 1. Register a SharePoint app using "\_layouts/15/appregnew.aspx ". **Make note of your `clientId` and `clientSecret`**
46 | 2. Grant your new app permissions using "\_layouts/15/appinv.aspx". You can use the xml snippet below to grant site collection admin access. **The key part is you set `AllowAppOnlyPolicy` to true\*\***.
47 |
48 | > The key part is you set `AllowAppOnlyPolicy` to true
49 |
50 | _Site Collection Admin Permissions for you App Context_
51 |
52 | ```xml
53 |
54 |
55 |
56 | ```
57 |
58 | 3. Pass the Client Id and Secret to `createContext`. All actions will be performed as the App.
59 |
60 | ```javascript
61 | const spauth = require("node-sp-auth");
62 |
63 | let auth = await spauth.getAuth(process.env.SITE_URL, {
64 | clientId: process.env.CLIENT_KEY,
65 | clientSecret: process.env.CLIENT_SECRET,
66 | });
67 | // Pass the auth headers to SPScript via the optional ContextOptions param
68 | let ctx = SPScript.createContext(siteUrl, { headers: auth.headers });
69 | let webInfo = await ctx.web.getInfo();
70 | console.log(webInfo);
71 | ```
72 |
--------------------------------------------------------------------------------
/docs/profiles.md:
--------------------------------------------------------------------------------
1 | # SharePoint Profiles
2 |
3 | The SharePoint Profile service automatically syncs predefined properties from Active Directory. You can access this information with SPScript
4 |
5 | - `ctx.profiles.get(email?:string)` - Get a profile by email, or the current user if no email given.
6 | - `ctx.profiles.setProperty(key, value)` - Update the current user's profile
7 |
8 | ## Get Profile
9 |
10 | ### Current User
11 |
12 | If you don't have anything to `profiles.get()` then it will use the current user.
13 |
14 | ```javascript
15 | let ctx = SPScript.createContext();
16 | let profile = await ctx.profiles.get();
17 | ```
18 |
19 | ### By Email
20 |
21 | You can passing an email address to `profiles.get(email)` to retrieve a specific user's profile.
22 |
23 | ```javascript
24 | let ctx = SPScript.createContext();
25 | let profile = await ctx.profiles.get("andrew@droopy.onmicrosoft.com);
26 | ```
27 |
28 | ## Update Property
29 |
30 | ```javascript
31 | let ctx = SPScript.createContext();
32 | await ctx.profiles.setProperty("AboutMe", "I was updated by SPScript");
33 | ```
34 |
--------------------------------------------------------------------------------
/docs/search.md:
--------------------------------------------------------------------------------
1 | # Querying the SP Search Service
2 |
3 | ## Introduction
4 |
5 | The SharePoint Search REST API responses are notoriously difficult to work with. To get the items you'd have to say `data.PrimaryQueryResult.RelevantResults.Table.Rows`. But you're not done yet! Each Row is a `{}` with a `Cells` array which contains key value pairs of the item's managed properties and values. It's a huge mess...
6 |
7 | _This is about the shortest way you could parse the Search Rest API response._
8 |
9 | ```javascript
10 | let items = data.PrimaryQueryResult.RelevantResults.Table.Rows.map((row) => {
11 | return row.Cells.reduce((obj, cell) => {
12 | obj[cell.Key] = cell.Value;
13 | }, {});
14 | });
15 | ```
16 |
17 | With SPScript you can query the Search Service with 1 line of code (and get clean objects back).
18 |
19 | ```javascript
20 | let searchResult = await ctx.search.query("SPScript");
21 | // searchResult.items will be an array of JS objects, one for each search result
22 | console.log(searchResult.items);
23 | ```
24 |
25 | ## Search Methods
26 |
27 | - `ctx.search.query(text)` - query the Search Service, async resolves to a `SearchResultResponse` (see below)
28 | - `ctx.search.query(text, queryOptions)` - query the Search Service and specify `QueryOptions`
29 | - `ctx.search.people(text)` - limits the search to just people
30 | - `ctx.search.people(text, queryOptions)` - limits the search to just people with specified `QueryOptions`
31 | - `ctx.search.sites(text)` - limits the search to just sites (STS_Web)
32 | - `ctx.search.sites(text, urlScope)`- limits the search to just sites (STS_Web) that are underneath the specified `scopeUrl`
33 | - `ctx.search.sites(text, urlScope, queryOptions)` - limits the search to just sites (STS_Web) that are underneath the specified `scopeUrl` with the specified `QueryOptions`
34 |
35 | The previous search methods all take query text as the first parameter. This text can be:
36 |
37 | - An arbitrary string - `"spscript is awesome"`
38 | - A Keyword Query (KQL) - `"Title:SPScript OR Path:https://andrew.sharepoint.com/sites/spscript"`
39 | - Both `"Author:Petersen come find me"`
40 |
41 | ## Search Response
42 |
43 | Each call to `ctx.search.query(searchText)` is `async` and will resolve to a `SearchResultResponse`.
44 |
45 | ```typescript
46 | interface SearchResultResponse {
47 | elapsedTime: string;
48 | suggestion: any;
49 | resultsCount: number;
50 | totalResults: number;
51 | totalResultsIncludingDuplicates: number;
52 | /** The actual search results that you care about */
53 | items: any[];
54 | refiners?: Refiner[];
55 | }
56 | ```
57 |
58 | ## Query Options
59 |
60 | You can also pass an optional second parameter to specify query options
61 |
62 | _Use QueryOptions to only bring back 5 results_
63 |
64 | ```javascript
65 | let searchResult = await ctx.search.query("SPScript", { rowlimit: 5 );
66 | console.log(searchResult.items);
67 |
68 | ```
69 |
70 | Interface
71 |
72 | ```typescript
73 | interface QueryOptions {
74 | sourceid?: string;
75 | startrow?: number;
76 | rowlimit?: number;
77 | selectproperties?: string[];
78 | refiners?: string[];
79 | refinementfilters?: string[];
80 | hiddencontstraints?: any;
81 | sortlist?: any;
82 | }
83 | ```
84 |
85 | Default Query Options
86 |
87 | ```javascript
88 | {
89 | sourceid:null,
90 | startrow:null,
91 | rowlimit:100,
92 | selectproperties:null,
93 | refiners:null,
94 | refinementfilters:null,
95 | hiddencontstraints:null,
96 | sortlist:null
97 | }
98 | ```
99 |
--------------------------------------------------------------------------------
/docs/sidebar.md:
--------------------------------------------------------------------------------
1 | - [Introduction](introduction)
2 | - [Getting Started](getting-started)
3 | - [List Operations](list-operations)
4 | - [GET / POST](arbitrary-requests)
5 | - [SharePoint Search](search)
6 | - [MMS](mms)
7 | - [SharePoint Profiles](profiles)
8 | - [Utilities](utilities)
9 | - [Serverside w/ Node.js](nodejs)
10 |
--------------------------------------------------------------------------------
/docs/utilities.md:
--------------------------------------------------------------------------------
1 | # Utility Functions
2 |
3 | ```javascript
4 | import { utils } from "spscript";
5 | ```
6 |
7 | ## getSiteUrl
8 |
9 | Returns the server relative url of the site at the provided url. It can do things like pull out the Site Url out of full document or page url. If you don't pass a url it will use the current page's url.
10 |
11 | It only really works for SharePoint Online because it assumes a managed path of `/sites` or `/teams`.
12 |
13 | ```javascript
14 | import { utils } from "spscript";
15 | let currentSiteUrl = utils.getSiteUrl();
16 | let documentSiteUrl = utils.getSiteUrl(documentUrl);
17 | ```
18 |
19 | ## getTenant
20 |
21 | Returns the tenant of the provided url. If not url is provided, it uses the current page's url.
22 |
23 | ```javascript
24 | import { utils } from "spscript";
25 |
26 | let tenant = utils.getTenant();
27 | ```
28 |
29 | ## getDelveLink
30 |
31 | Take an email address and returns the url to that user's Delve profile
32 |
33 | ```javascript
34 | import { utils } from "spscript";
35 |
36 | let delveProfileUrl = utils.getDelveLink("apetersen@droopy.onmicrosoft.com");
37 | ```
38 |
39 | ## getProfilePhoto
40 |
41 | Take an email address and returns the url that user's SharePoint profile photo
42 |
43 | ```
44 | let photoUrl = utils.getProfilePhoto("apetersen@droopy.onmicrosoft.com");
45 | ```
46 |
47 | ## HTTP Headers
48 |
49 | SPScript comes with some utilty functions to set some special SharePoint headers.
50 |
51 | ```javascript
52 | utils.getStandardHeaders((digest = ""));
53 | ```
54 |
55 | - Sets `Accept`, `Content-Type` to `application/json`
56 | - Sets `X-RequestDigest` if a digest was provided
57 |
58 | ```javascript
59 | utils.getUpdateHeaders(digest?:string)
60 | ```
61 |
62 | - Sets `Accept`, `Content-Type` to `application/json`
63 | - Sets `X-RequestDigest` if a digest was provided
64 | - Sets `X-HTTP-Method` to `MERGE`
65 | - Sets `If-Match` to `*`
66 |
67 | ```javascript
68 | utils.getDeleteHeaders(digest?:string)
69 | ```
70 |
71 | - Sets `Accept`, `Content-Type` to `application/json`
72 | - Sets `X-RequestDigest` if a digest was provided
73 | - Sets `X-HTTP-Method` to `DELETE`
74 | - Sets `If-Match` to `*`
75 |
76 | ## parseOData
77 |
78 | Helps parse the odata response to give you back what you actually want instead of something like `{ d: { results: [ ] }}`
79 |
80 | Checks for the following and automatically bubbles up what it finds as the return value.
81 |
82 | - `data.d.results`
83 | - `data.d`
84 | - `data.value`
85 |
86 | _Example Usage_
87 |
88 | ```javascript
89 | let currentUserGroups = await ctx.get("/web/currentuser/groups").then(utils.parseOData);
90 | ```
91 |
92 | ## parseJSON
93 |
94 | Wraps `JSON.parse` in a try/catch and returns `null` if the parse fails.
95 |
96 | ```javascript
97 | utils.parseJSON(jsonStr);
98 | ```
99 |
100 | ## Query String
101 |
102 | Helper functions to convert between a JS object, `{ active: 'BigDate', count: 4 }` to a a query string, `active=BigDate&count=4`, and back.
103 |
104 | - utils.qs.`toObj(string) => Object`
105 | - utils.qs.`fromObj(object, wrapInSingleQuotes = false) => string`
106 |
107 | _Example Usage_
108 |
109 | ```javascript
110 | let odata = {
111 | $top: 100,
112 | $select: "Title, Id",
113 | $orderBy: "Created desc",
114 | };
115 | let items = await ctx.lists("Site Pages").getItems(SPScript.utils.qs.fromObj(odata));
116 | ```
117 |
118 | ## waitForElement
119 |
120 | Function to handle waiting for DOM elements to available on a page.
121 |
122 | ```javascript
123 | let feedbackBtn = await utils.waitForElement("#feedback_btn");
124 | feedbackBtn.style.display = "none";
125 | ```
126 |
127 | ## Loaders
128 |
129 | Helpers to load external JavaScript and CSS files.
130 |
131 | ```javascript
132 | await utils.loadScript("https://domain.com/javascript.js");
133 | ```
134 |
135 | ```javascript
136 | await utils.loadCSS("https://domain.com/styles.css");
137 | ```
138 |
--------------------------------------------------------------------------------
/jest.config.js:
--------------------------------------------------------------------------------
1 | module.exports = {
2 | transform: {
3 | "^.+\\.tsx?$": "ts-jest",
4 | },
5 | testEnvironment: "node",
6 | testRegex: "(/__tests__/.*|(\\.|/)(test|spec))\\.(jsx?|tsx?)$",
7 | testPathIgnorePatterns: ["/lib/", "/node_modules/", "testUtils.ts"],
8 | moduleFileExtensions: ["ts", "tsx", "js", "jsx", "json", "node"],
9 | collectCoverage: false,
10 | collectCoverageFrom: ["src/**/*.{ts,tsx}", "!/node_modules/", "!/path/to/dir/"],
11 | };
12 |
--------------------------------------------------------------------------------
/legacy-tests/nodeauthtest.js:
--------------------------------------------------------------------------------
1 | let nodeauth = require("node-sp-auth");
2 | require("dotenv").config();
3 |
4 | var doIt = async () => {
5 | let auth = await nodeauth.getAuth(process.env.SITE_URL, {
6 | username: process.env.SP_USER,
7 | password: process.env.PASSWORD,
8 | online: true
9 | });
10 | console.log(auth);
11 | };
12 |
13 | doIt();
14 |
--------------------------------------------------------------------------------
/legacy-tests/test.browser.js:
--------------------------------------------------------------------------------
1 | require("babel-polyfill");
2 | mocha.setup("bdd");
3 | chai.should();
4 | var SPScript = require("../../dist/v3/spscript");
5 | require("./tests").run(SPScript);
6 |
7 | mocha.run();
8 |
--------------------------------------------------------------------------------
/legacy-tests/test.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
33 |
SPScript Tests
34 |
35 |
36 |
37 |