Uma-services NPM

uma-services

UMAknow services (and helper functions) to reuse in various On-Premise SharePoint components

Webstorm Configuration

In Tools/File Watchers add Babel with:
Program $ProjectFileDir$\node_modules.bin\babel
Arguments src --out-dir dist --source-maps --ignore dist
Output paths to refresh $FilePathRelativeToProjectRoot$ dist\$FileNameWithoutExtension$.js:dist\$FileNameWithoutExtension$.js.map

Library contents

Assumptions

The application is created with create-react-app
The sp-rest-proxy package is used for proxying calls to SharePoint in debug mode

ConfigInfo

This class is used in App.js and provides a means to access parameters defined in an external file.
The file is loaded at runtime.
Before App.js is called by index.js the following setup is necessary at the beginning of index.js file :

const proxyServer = require('../src/config/server');

window._spPageContextInfo = typeof window._spPageContextInfo !== "undefined" ? window._spPageContextInfo : {
    'webServerRelativeUrl': proxyServer.webServerRelativeUrl,
    'webAbsoluteUrl': Utils.combine(proxyServer.domain, proxyServer.webServerRelativeUrl),
    'siteAbsoluteUrl': proxyServer.siteAbsoluteUrl,
    'userId': proxyServer.userId,
    'redefined': true
};

The server.json file shall contain the following parameters (configured according to your environment):

Note: JSON files do not accept comments, the following ones are here for clarity

{
  "configPath": "./src/config/private.json",
  "port": 8080,                                          //default proxy port used by sp-rest-proxy
  "staticRoot": "./build",
  "configFilePath": "umaConfig/projects-dashboard.txt",  //or whatever the name of the config file is
  "domain": "http://<domain>",
  "userId": 812,                                         //or whatever the name of the user testing the app is
  "webServerRelativeUrl": "<relative path to web site where app is>",
  "siteServerRelativeUrl": "<relative path to site collection root where app is>"
}

The following code should be called in the constructor of the App class

    constructor(props) {
        super(props);
        this.state = {
            siteConfig: undefined
        };
        //Get configuration information from local file
        this.configInfo = new ConfigInfo(configFilePath, parametersList, new DevUtils(proxyServer));
        this.configInfo.load().then(() => {
            if (!this.configInfo.areParametersOk()) {
                console.error(this.configInfo.getParametersStatus());
            }
            this.setState({
                siteConfig: this.configInfo
            });
        }).catch((e) => {
            console.log(e);
            this.setState({
                siteConfig: null
            });
        });
    }

DevUtils

This class provides dev functions to convert a URL so that the call goes through the proxy if we're in dev mode.
An instance of this class must be provided at construction time of ConfigInfo.

checkUrlForDev

Returns the correct URL for the proxy to make the proper call.

revertToProdUrl

Reverts a proxy-compliant URL to the production-like URL. Can be useful to display the correct URL in dev mode.

SpSingleton

SpSingleton provides THE way to setup sp (for SharePoint queries) and always use the same properly configured sp reference.

!! Do not import sp or Web from @pnp/js anymore !! use SpSingleton

Utils library

A general utility library with various static functions.

visualTextLength

Returns the width in pixels of a string, given given the CSS characteristics of the html

getFittingSubstring

Returns the portion of the string that fits a certain width, given the CSS characteristics of the html

getJSONParams

This allows to get parameters hidden in the page in the form of a JSON string.
The html code looks like this:
<span class="{paramClassname}">{"news-time-span": "current-news"}</span>
It is recommended to style this class with display:hidden

olderThanToday

Returns true if given date is older than the day's date.
Today is local time today.

olderThanNbYearsAgo

Returns true if given date is older than the given number of years.

validateNumber

Returns true if number is a number, otherwise NaN

getAbbreviatedNumber

Returns a string that represents a number but with the multiplier symbol (i.e K for thousands, M for millions, etc.)

combine

Combines strings into a "/" separated string to form a path. Removes redundant slashes unless provided by one of the elements.

processPromises

Allows to resolve an array of promises. All promises will resolve, not reject.
(otherwise one rejected promise rejects the whole array)
Returned values:

errors: an array with the description of the failure
results: an array with the request resulting data

getFileWeb

When provided with a full file url, this utility will return an object with the following fields:

path: the url of the SharePoint site containing the file
web: a PnP web object to the site containing the file

getDocIdRedirFile(path, searchProps)

When provided with a document ID path, this utility returns an object that defines the corresponding file. Additional properties can be requested in the searchProps array

Forms library

A set of components to reconstruct SharePoint form fields:

single line
multi-line
number
choice
multi-choice
managed metadata
lookup
people picker with search (type letters to see results)
people picker with dropdown
date picker
files link: user needs to enter url followed by Enter key

Forms Setup

Each field must be defined as follows:

this.FormFieldsDefinitions = [
    {
        label: 'NCR #',
        key: 'NCR #',
        type: 'SingleLine',
        SPinternalName: 'Title',
        onChange: null,
        mandatory: false,
        visible: true,
        value: '',
        restrictedToEditorsGroup: false,
        readOnly: true,
        canExport: SPFieldContent.CAN_EXPORT,
        canImport: SPFieldContent.NO_IMPORT
    }, {...}]

The form is "linked" to the list using the following code:

    this.formFields = new FormFields(listUrl, listName);   //"link" the list and the form
    
    FormFields.buildFields(this.FormFieldsDefinitions, this.formFields);  //build the fields for the form

The FormFields provides all necessary methods to access an item's properties, update the item, etc.

NavMenu and MenuItem classes

Both classes are used to create a navigation tree to be used with the Nav component of Office UI Fabric (https://developer.microsoft.com/en-us/fabric#/components/nav)

Example

    //create the menu    
    this.Menu = new NavMenu();
    //add a couple of root links
    this.Menu.addRootItem('Parent1', 'http://www.google.com', 'Parent1')
    this.Menu.addRootItem('Parent2', 'url parent 2', 'Parent2')

    //add a couple of sub-menu items
    let newItem = new MenuItem('Child2', 'url child 2', 'Child2');
    this.Menu.addToMenu('Parent2', newItem);
    newItem = new MenuItem('Child12', 'url child12', 'Child12');
    this.Menu.addToMenu('Parent1', newItem);