Elektron Library for SPFx
npm install elektron-v2setup() to configure Elektron within a global context.
ts
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.
`ts
// 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.
$3
---
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()
`ts
import { SPFxContext } from 'elektron-v2/dist/context';
/// ...
const currentWebUrl = SPFxContext.instance.pageContext.web.absoluteUrl;
const currentSiteUrl = SPFxContext.instance.pageContext.site.absoluteUrl;
`
$3
---
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.
`ts
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');
`
$3
---
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
---
`ts
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
`ts
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');
`
$3
---
#### 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 |
$3
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
`ts
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
$3
- Latest current version of NodeJs
- We recommend using Visual Studio Code
$3
`cmd
git clone https://2tolead.visualstudio.com/Elektron%202.0/_git/Elektron_V2
`
$3
`cmd
npm install
`
$3
`cmd
npm run build
`
$3
`cmd
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.
`cmd
npm install jest ts-jest @types/jest --save-dev
`
Use babel-jest and @babel/preset-env to run tests when importing ES6 modules
`cmd
npm install babel-jest @babel/preset-env --save-dev
`
Then generate the jest.config.js file:
`cmd
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:
`cmd
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.