sharepoint-utilities

A set of convenience methods for SharePoint.

Installing

npm install sharepoint-utilities

Usage

import {register} from 'sharepoint-utilities';
register().then(() => {
    SP.SOD.import(['sp.js']).then(() => {
        ...
    });
});

// or

import {importSod} from 'sharepoint-utilities';
importSod(['sp.js']).then(() => {
    ...
});

Browser Console Usage

// Only works in browser with support for ES6 modules:
import("https://dennispg.github.io/sharepoint-utilities/es6/index.js")
.then(m=>m.register(true));

Extensions

This package provides a set of extensions to SharePoint's JavaScript Object Model to make development slightly less tedious. These include collection methods similar to those available from lodash (https://lodash.com/docs).

Reference

Table of contents

• SP.SOD.import
• SP.ClientContext.executeQuery
• SP.List.get_queryResult
• SP.Guid.generateGuid
• IEnumerable<T>.each
• IEnumerable<T>.every
• IEnumerable<T>.find
• IEnumerable<T>.filter
• IEnumerable<T>.firstOrDefault
• IEnumerable<T>.forEach
• IEnumerable<T>.groupBy
• IEnumerable<T>.keyBy
• IEnumerable<T>.map
• IEnumerable<T>.reduce
• IEnumerable<T>.some
• IEnumerable<T>.toArray
• SP.UserCustomActionCollection.ensure
• SP.UserCustomActionCollection.remove
• SP.UserCustomActionCollection.removeByTitle
• SP.UserCustomActionCollection.removeByName
• SP.UserCustomActionCollection.removeById

SP.SOD.import

A wrapper around SharePoint's Script-On-Demand using Promises.

Parameters

• sod (string | string[]) Script or scripts to load from SharePoint

Example

// instead of:
SP.SOD.executeOrDelayUntilScriptLoaded(function() {
    <...>
}, 'sp.js');
LoadSodByKey('sp.js');

// use this:
SP.SOD.import('sp.js')
.then(function() {
    <...>
});

SP.ClientContext.executeQuery

A shorthand for context.executeQueryAsync except wrapped as a Promise object

Example

// instead of:
var context = new SP.ClientContext();
context.executeQueryAsync(
    Function.createDelegate(this, function(sender, args) {
        <...>
    }),
    Function.createDelegate(this, function(sender, args) {
        <...>
    })
);

// use this:
var context = new SP.ClientContext();
context.executeQuery()
.then(function(args) {
    <...>
});

SP.List.get_queryResult

Returns a collection of items from the list based on the specified query. A shorthand for SP.List.getItems with just the queryText and doesn't require a SP.CamlQuery to be constructed

Parameters

• queryText (string) The CAML query to call SP.List.getItems with.

Returns an SP.ListItemCollection

Example

// instead of:
var query = new SP.CamlQuery();
query.set_viewXml('<View><Query><Where><Eq><FieldRef Name="Title"/><Value Type="Text">Hello world!</Value></Eq></Where></Query></View>');
var items = list.getItems(query);

/// use this:
var items = list.get_queryResult('<View><Query><Where><Eq><FieldRef Name="Title"/><Value Type="Text">Hello world!</Value></Eq></Where></Query></View>');

SP.Guid.generateGuid

Example

let guid = SP.Guid.generateGuid();

IEnumerable.each

Execute a callback for every element in the matched set. (use jQuery style callback signature)

Example

// instead of:
let items = list.getItems();
var enumerator = items.getEnumerator();
while(enumerator.moveNext()) {
    var item = enumerator.get_current();
    console.log(item.get_title());
}

// use this:
let items = list.getItems();
items.each(function(i, item) {
    console.log(item.get_title());
});

IEnumerable.every

Tests whether every element in the collection passes the test implemented by the provided function.

Example

let items = list.getItems();
items.every(item => item.get_item('Title') == "") == false;

IEnumerable.find

Finds the first element in the collection which passes the test implemented by the provided function, or null if not found.

Example

let items = list.getItems();
var found_item = items.find(item => item.get_item('Title') == "");

IEnumerable.filter

Iterates over elements of collection, returning an array of all elements predicate returns truthy for. The predicate is invoked with three arguments: (value, index|key, collection).

See

lodash filter function documentation

Example

let items = list.getItems();

items.filter(item => item.get_item('Title') == "")
// => all list items with empty Title field

items.filter({ "Title": "", "Author": web.get_currentUser() });
// => all list items where Title is empty and the item was created by the current user

items.filter('IsActive');
// => all items where IsActive field is truthy (non-null, not false, not 0)

IEnumerable.firstOrDefault

Returns the first element in the collection or null if none

Example

let items = list.getItems();
var item = items.firstOrDefault();
if(item != null)
    console.log('Got the first item in the collection.')
else
    console.log('The collection was empty.')

IEnumerable.forEach

Execute a callback for every element in the matched set. (uses array.forEach style callback signature)

Example

// instead of:
let items = list.getItems();
var enumerator = items.getEnumerator();
while(enumerator.moveNext()) {
    var item = enumerator.get_current();
    console.log(item.get_title());
}

// use this:
let items = list.getItems();
items.each(function(item, i) {
    console.log(item.get_title());
});

IEnumerable.groupBy

Creates an object composed of keys generated from the results of running each element of collection thru iteratee. The order of grouped values is determined by the order they occur in collection. The corresponding value of each key is an array of elements responsible for generating the key. The iteratee is invoked with one argument: (value).

Example

let items = list.getItems();
var groups = items.groupBy(function(item) {
    return item.get_item('ContentType');
});
// => { 'Document': [item1, item2], 'Page': [item3, item4] }

IEnumerable.keyBy

Creates an object composed of keys generated from the results of running each element of collection thru iteratee. The corresponding value of each key is the last element responsible for generating the key. The iteratee is invoked with one argument: (value).

Example

let items = list.getItems();
var groups = items.keyBy(function(item) {
    return item.get_item('ContentType');
});
// => { 'Document': item1, 'Page': item2 }

IEnumerable.map

Creates an array of values by running each element in collection through iteratee.

Example

// instead of:
let items = list.getItems();
var transformed = [];
var enumerator = items.getEnumerator();
while(enumerator.moveNext()) {
    var item = enumerator.get_current();
    transformed.push({ title: item.get_title() });
}

// use this:
let items = list.getItems();
var transformed = items.map(function(item, i) {
    return { title: item.get_title() };
});

IEnumerable.reduce

Reduces collection to a value which is the accumulated result of running each element in collection thru iteratee, where each successive invocation is supplied the return value of the previous. If accumulator is not given, the first element of collection is used as the initial value. The iteratee is invoked with four arguments: (accumulator, value, index|key, collection).

Example

let items = list.getItems();
var total_sum = items.reduce(function(sum, item) {
    return sum + item.get_item('Total');
}, 0)

IEnumerable.some

Tests whether at least one element in the collection passes the test implemented by the provided function.

Example

let items = list.getItems();
if (items.some((item, i, items) => item.get_item('Title') == ""))
    console.log('Found an empty title.');

IEnumerable.toArray

Converts a collection to regular Array

Example

let items = list.getItems();
let item_array = items.toArray();

SP.UserCustomActionCollection.ensure

Adds a SP.UserCustomAction object to the collection. If an object with the same name or title already, it is overwritten instead of creating a duplicate.

IMPORTANT NOTE: This operation triggers a SP.ClientContext.executeQuery operation.

Example

var web = context.get_web();
var actions = web.get_userCustomActions();
actions.ensure({
    title: "ExampleCustomAction",
    scriptSrc: "~sitecollection/Style Library/custom_script.js",
    location: "ScriptLink",
    sequence: 1
})
.then(id => {
    console.log(`ScriptLink custom action with ID:${id} as added successfully.`);
});

SP.UserCustomActionCollection.remove

Deletes all SP.UserCustomAction objects from the collection where the provided selector function returns true.

SP.UserCustomActionCollection.removeByTitle

Deletes all SP.UserCustomAction object from the collection with matching title value.

Example

var web = context.get_web();
var actions = web.get_userCustomActions();
actions.removeByTitle("ExampleCustomAction");

SP.UserCustomActionCollection.removeByName

Deletes all SP.UserCustomAction object from the collection with matching name value.

SP.UserCustomActionCollection.removeById

Deletes all SP.UserCustomAction object from the collection with matching ID value.