elektron-v2
TypeScript icon, indicating that this package has built-in type declarations

2.7.0 • Public • Published

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.


Start by importing this package at the entry point of the SPFx component
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

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

Readme

Keywords

Package Sidebar

Install

npm i elektron-v2

Weekly Downloads

48

Version

2.7.0

License

MIT

Unpacked Size

166 kB

Total Files

130

Last publish

Collaborators

  • kk2tolead
  • 2toleadjordan
  • 2toleadmike