Elektron 2.0

Welcome to the Elektron V2 library.

This library contains multiple modules dedicated to SharePoint Framework solutions

Elektron

The Elektron module provides a static method called setup() to configure Elektron within a global context.

import { Elektron } from 'elektron-v2';

This setup() method takes 1 parameter object with the following properties

| Property | Type | Default | Description | | ------------------- | ---------- | ----------------------------------------------- | ------------------------------------------------ | | spfxContext | required | N/A | The current SPFx context | | listProviderOptions | optional | See listProviderOptions | Options to use for the ListConfigurationHelper |

The following example will configure Elektron to use the cascading behavior to load solution configuration values from multiple sources (central site collection, current site collection and current web) excluding the root site collection when using the ListConfigurationHelper.

// Typically executed within OnInit() as this must run each page load.
Elektron.setup({
    spfxContext: this.context,
    listProviderOptions: {
        scope: ListConfigurationScopes.Cascaded,
        cascadingOptions: {
            isEnabled: true,
            excludeRoot: true,
        },
    },
});

When using the Cascaded configuration scope, exclusion options excludeRoot & excludeCentral will not prevent the configuration from being loaded if the current site is the root or the central site.

Context Module

The Context module provides information related to the current SPFx context. It must be registered by providing the current SPFx page context (this.context) using either the Elektron setup() method or directly from SPFxContext.register()

import { SPFxContext } from 'elektron-v2/dist/context';
/// ...
const currentWebUrl = SPFxContext.instance.pageContext.web.absoluteUrl;
const currentSiteUrl = SPFxContext.instance.pageContext.site.absoluteUrl;

Configuration

Configuration allows pulling values from the configuration lists in the strategy defined via setup(). Always register the current page context using setup() method from the Elektron module prior to using.

import { ListConfigurationHelper as Config } from 'elektron-v2/dist/configuration';
/// ...
const configValue = await Config.getValue('control', 'config key');
const configValueWithDefault = await Config.getValue('control', 'config key', 'default value');

Caching

This module leverages the PnPjs caching library

Use the PnPCachingService class to manage items in the browser cache.

The constructor takes 2 parameters:

| Parameter | Type | Default | Description | | ------------ | ---------- | ---------- | ----------------------------------------------------------- | | cacheOptions | required | N/A | Options used for caching. See cacheOptions | | prefix | optional | elektron | The prefix to use when building the cache key |

cacheOptions

| Property | Type | Default | Description | | -------- | ---------- | ------- | --------------------------------------------------------------------- | | store | required | N/A | Choose between local or session storage | | time | required | N/A | Time to store for. Measurement units are declared in unit property. | | unit | required | N/A | Year, Quarter, Month, Week, Day, Hour, Minute, Second | | region | optional | empty | The region to use when building the cache key |

Example

import { CachingUnits, PnPCachingService } from 'elektron-v2/dist/caching';
// ...
// Instantiate the service with desired options
const cacheService = new PnPCachingService({ store: 'local', unit: CachingUnits.Minutes, time: 1 });
// Then consume where needed
const cachedValue = cacheService.get('cache key');

Keys and CacheUtility

Cache keys generated by the PnPCachingService class will be formatted like this:

prefix_region_key (or prefix__key if no region is provided)

The CacheUtility class provides a method to clear all keys generated by Elektron from the local or session storage

import { CacheUtility } from 'elektron-v2/dist/caching';
// removes all cached items from local storage where keys start with prefix_
const regionKey = CacheUtility.clear('local', 'prefix');
// ...
// removes all cached items from the session storage where keys start with prefix_region
const regionKey = CacheUtility.clear('session', 'prefix', 'region');

Setup Parameters Reference

listProviderOptions

| Property | Type | Default | Description | | -------------- | ---------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | scope | required | Cascaded | Root reads only from the root site collection. CurrentWeb reads only from the current web CurrentSiteCollection reads only from the current site collection. Central reads from the central site defined by tenant property ROOT_CONFIG_SERVER_RELATIVE_URL or by providing centralSiteUrl Cascaded reads from current web, parent webs, root site, then central site Custom reads from the site provided by customSiteUrl | | cacheOptions | optional | { store: 'local', unit: CachingUnits.Hour, time: 12 } | See listProviderOptions.cacheOptions | | centralSiteUrl | optional | Reads from tenant property (ROOT_CONFIG_SERVER_RELATIVE_URL) | URL of the site to use for central configuration (overrides ROOT_CONFIG_SERVER_RELATIVE_URL tenant property). Used by Central and Cascaded list configuration provider scopes | | customSiteUrl | optional | N/A | URL of the site to use for a Custom list configuration provider | | retryOptions | optional | N/A | Options to use for retry. See listProviderOptions.retryOptions | | listUrl | optional | 'solutionconfig' | URL of the sharepoint list to load the configuration from. |

listProviderOptions.cascadingOptions

| Property | Type | Default | Description | | -------------- | ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | isEnabled | required | true | Set to true to enable cascading for a cascaded list configuration provider. | | excludeRoot | optional | false | Set to true to exclude the Root Site Collection from a cascaded list configuration provider. Does not exclude if current site is root site | | excludeCentral | optional | false | Set to true to exclude the Central Site Collection from a cascaded list configuration provider. Does not exclude if current site is central site |

listProviderOptions.cacheOptions

| Property | Type | Default | Description | | -------- | ---------- | --------------- | ------------------------------------------------------------------------------------------------- | | store | optional | local | Choose between local or session storage | | time | optional | 12 | Time to store list configuration in cache for. Measurement units are declared in unit property. | | unit | optional | Hour | Year, Quarter, Month, Week, Day, Hour, Minute, Second | | region | optional | configuration | The region to use when building the cache key for cached configuration items |

listProviderOptions.retryOptions

| Property | Type | Default | Description | | --------- | ---------- | ------- | --------------------------------------------------------------------------------- | | isEnabled | required | N/A | Defines if retry behavior is enabled. | | options | required | N/A | See pRetry options |

Tenant Properties Service

Use the TenantPropertiesService class to retrieve the value of a property stored in the Tenant property bag. Returns undefined and log a warning to the console if the property does not exist

Example

import { TenantPropertiesService } from 'elektron-v2/dist/services/tenant';
// ...
// Instantiate the service
const tenantPropertiesService = new TenantPropertiesService();
// Then use it to retrieve the value of the property from its key
const propertyValue = tenantPropertiesService.getTenantPropertyValue('key');

Contributing

Getting Started

Tools

• Latest current version of NodeJs
• We recommend using Visual Studio Code

Clone/Initialize the Repo

git clone https://2tolead.visualstudio.com/Elektron%202.0/_git/Elektron_V2

Install dependencies

npm install

Build

npm run build

Test

npm test

Jest Configuration

Jest is a very popular javascript testing framework. To use Jest within a TypeScript project, you must install the following packages from NPM.

npm install jest ts-jest @types/jest --save-dev

Use babel-jest and @babel/preset-env to run tests when importing ES6 modules

npm install babel-jest @babel/preset-env --save-dev

Then generate the jest.config.js file:

node ./node_modules/jest/bin/jest.js --init

In the generated file jest.config.js, add the following:

transform: {
    "^.+\\.js$": "babel-jest",
    "^.+\\.(ts)x?$": "ts-jest"
},
transformIgnorePatterns: [
    "/node_modules/?!(@pnp/sp)"
],

This tells Jest to compile .ts files before running the tests

The transformIgnorePatterns indicates that jest should transpile the @pnp/sp packages before running the tests since those are ES6 modules.

Documentation

Docs are generated using the typedoc-plugin-markdown package

Usage:

npm run docs

You are responsible for running this command before submitting a new Pull Request to this repo to make sure the documentation stays up to date !

Coding guidelines

• Use PascalCase for type names.
• Use "I" as a prefix for interface names.
• Use PascalCase for enum values.
• Use camelCase for function names.
• Use camelCase for property names and local variables.
• Do not use "_" as a prefix for private properties except if injected as constructor parameters or when using getters and setters.
• Use whole words in names when possible.

Inspired from: Coding Guidelines