Now Paging Maciej

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

    2.2.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/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/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/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/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

    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

    Keywords

    Install

    npm i elektron-v2

    DownloadsWeekly Downloads

    7

    Version

    2.2.0

    License

    MIT

    Unpacked Size

    160 kB

    Total Files

    130

    Last publish

    Collaborators

    • 2toleadjordan
    • mchip88
    • 2toleadmike