elektron-v2 v2.7.0

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

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:

cacheOptions

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

listProviderOptions.cascadingOptions

listProviderOptions.cacheOptions

listProviderOptions.retryOptions

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