pCon.basket - Plugin Development
    Preparing search index...

    pCon.basket - Plugin Development

    API Version 3.4.0 (Basket 2.17.0)
    Date 2026-09-15


    This documentation is intended for programmers who want to extend or replace features of the pCon.basket web application. The focus of this documentation is to help developers understand the basic concepts behind pCon.basket plugins.

    The pCon.basket is a plugin based web application. Every major part of it is a plugin and can be replaced or extended. Plugins are devided into categories to fulfill a different purpose. Plugin categories are interfaces that can be implemented to extend or replace parts of the pCon.basket web application. These interfaces are documented in the plugin SDK. To illustrate how to implement some of these plugin categorie an example plugin is provided as part of the plugin SDK. These examples can be found in the /src/plugins/ directory of the example plugin source code.

    The following diagram shows how plugins implementing different plugin categories are accessed by the user. The application is always accessed via an activity. An activity can be anything from creating a new project or opening a project to view a report and usally starts the ProjectEditor plugin.

    When the application is loaded, Activity plugins that are registered with the plugin manager will be accessible through the basket dashboard. Once an activity has been chosen the activity plugin is loaded. Activity plugins can then load other plugins. These can be either the ProjectEditor plugin or any other category. The project editor will then load further plugins if necessary. Only plugins with the Authentication and Authorization categories are loaded at the start of the application. All other plugin categories will be loaded on demand.

    pCon.basket is a client side web application running in a web browser. Therefore JavaScript and webpack has to be used to develop a plugin. If JavaScript is used directly or any other language which can be transpiled to JavaScript is up to the developer. To simplify the development process it is recommended to use TypeScript. The provided plugin SDK has type definitions of all interfaces that are required when implementing a pCon.basket plugin. For the GUI it is recommended to use React because the SDK also provides some react helper components but using other UI-frameworks is also possible. The basket itself is developed using the fluentui/react component library.

    Each plugin is located in its own directory. The name of the directory is free to choose. Inside the plugin directory are the two mandatory files plugin.json and plugin.js. The plugin.json is a manifest used for the plugin registration. The plugin.js file contains the javascript logic of the plugin. Other than that each plugin directory can contain further files (e.g. assets)

    <plugin_directory>
      ├─ plugin.json
      ├─ plugin.js
      └─ ... additional plugin related files and folders
    

    The plugin.json is a required manifest of the plugin and defines which plugin categories are implemented by this plugin. The content of the manifest will be loaded immediately at the start of the application. The plugin.js will be loaded on-demand.

    Structure of the manifest (optional fields are marked with ?):

    {
    /**
    * Object with major and minor version of the required plugin API.
    * e.g.: { "major": 1, "minor": 0 }
    * This version is used by the pCon.basket application to verify plugin compatability.
    * To be compatible the major version has to match exactly and the minor version
    * has to be less than or equal to the API of pCon.basket.
    * A plugin will be ignored if its requiredApiVersion is not comptatible.
    */
    "requiredApiVersion": {
    "major": number,
    "minor": number
    },
    /**
    * Custom version string of the plugin e.g. "1.0.0"
    * Note: The version is also used to control the browser cache and therefore
    * should be changed with every plugin release.
    */
    "version": string,
    /** vendor of the plugin e.g. "EasternGraphics GmbH" */
    "vendor": string,
    /** Array of plugin category implementations contained in this plugin */
    "plugins": [
    {
    /** unique name of the plugin implementation */
    "name": string,
    /** plugin category for this plugin, see SDK for list of available categories */
    "category": string,
    /** subCategory of the plugin if the `category` supports it */
    "subCategory"?: string,
    /**
    * If true this plugin will be handled as a default plugin.
    * If multiple plugins exist for the same plugin category default plugins have lower priority.
    * This is only relevant for plugin categories that support only a single
    * implementation at runtime (e.g. `Catalog`).
    */
    "isDefault"?: boolean,
    /**
    * Required user context type. If defined and the context is not available the plugin will be ignored.
    * `*` can be used to accept every conext.
    * (e.g. `pCon.login`).
    */
    "requiredUserContext"?: string | null,
    /**
    * Defines the order of plugins with the same plugin category.
    * The higher the value, the higher the priority of the plugin for the sorting.
    * The default value is -100.
    * Note: Not all plugin categories support this.
    */
    "sortWeight"?: number,
    /**
    * Name of the icon to use. See section 2.4 for details.
    * It depends on the plugin category if an icon is supported.
    */
    "iconName"?: string,
    /**
    * Url of the icon to use. If an icon url is defined the `iconName` will be ignored.
    * It depends on the plugin category if an icon is supported.
    */
    "iconUrl"?: string,
    /** If the plugin category supports it, a multilingual title can be defined. */
    "title"?: {
    "en"?: string,
    "de"?: string,
    /* ... more translations */
    },
    /** If the plugin category supports it, a multilingual description can be defined. */
    "description"?: {
    "en"?: string,
    "de"?: string,
    /* ... more translations */
    }
    },
    /* ... further category definitions */
    ]
    }

    The plugin.js contains the bundled plugin code and will be loaded on-demand by the pCon.basket. The plugin.js can contain implementations of multiple plugin categories. For each category the corresponding plugin interface has to be implemented. After the plugin was been loaded each plugin category implementation has to be registered at the plugin manager. The registerPlugin method can be used for this purpose. The global egr.wbkApp instance which is available to all plugins at runtime can be used to access the plugin manager.

    egr.wbkApp.pluginManager.registerPlugin(new MyPluginImplementation());
    

    The are several interfaces in the plugin API where an icon can be defined (e.g. for tabs or buttons). Icons can usally be defined in two ways. By defining an url to a custom icon or by using a name of a predefined icon. pCon.basket includes an open source icon library named Material Design Icons. The complete list of available icons can be found here: https://pictogrammers.com/library/mdi/ The names of the icons in this list have to be prefixed with mdi- in order to be used with pCon.basket e.g. mdi-account

    The SDK is a collection of type definitions for use with typescript. The type definition files also include an API documentation. Developers can use this documentation as a reference when implementing a plugin.

    plugin-sdk
      ├─ wbk-core
      │    ├─ plugins    <- plugin category interfaces
      │    ├─ types
      │    └─ ...
      ├─ wbk-sharedlib
      └─ egr-wcf-<version>.tgz
    

    The wbk-core directory contains the interface definitions of the pCon.basket plugin API. For example the interfaces for the different plugin categories can be found under wbk-core/plugins.

    The wbk-sharedlib is an installable npm package. It contains a list of dependencies which are commonly used by plugins and an Webpack DLL. The purpose of the wbk-sharedlib is to reduce the bundle size of plugins and to ensure that every plugin uses the same version of a bundled library. Every plugin is an independent bundle of javascript code and libraries. Typically webpack would bundle all of the plugin dependencies inside the plugin. That would mean that every plugin using for example react would bundle its own copy of react. This means that the size of every plugin would be very big. Dependencies part of wbk-sharedlib will not be bundled inside the plugin because they already bundled in the wbk-sharedlib.

    wbk-sharedlib has to be added as an dependency in the package.json of the plugin and the webpack DllPlugin has to be configured inside the webpack.config.js. The example plugin can be used as an example for this.

    wbk-sharedlib comes in two versions a relase/production build and a debug/development build. For debugging issues with 3rd party libraries it is recommended to use the development build. By default pCon.basket only loads the release build of wbk-sharedlib at runtime. To change this the debug mode of pCon.basket can be enabled. This can be done with the debug=true url parameter. Example:

    https://www.example-basket.com/?debug=true
    

    W-CF stands for Web Configuration Framework. It provides all core functions which are necessary to communicate with the EAIWS or configure articles. It is provided as an NPM module @easterngraphics/wcf and it is referenced by wbk-sharedlib.

    Module summary:

    • bsk - wrapper for the EAIWS basket functionality
    • cf - tools and functions for article configuration
    • core - core of W-CF framework
    • eaiws - SOAP-API javascript wrapper for EAIWS
    • pl - tools & functions for space planning
    • utils - utility functions

    More details about these modules can be found in the W-CF documentation.

    Plugins are located in the plugins directory inside the root of the pCon.basket.

    pCon.basket root
      ├─ ...
      ├─ plugins
      │   ├─ plugin_1
      │   │    ├─ plugin.json
      │   │    ├─ plugin.js
      │   │    └─ ... additional files and folders
      │   ├─ plugin_2
      │   │    ├─ plugin.json
      │   │    ├─ plugin.js
      │   │    └─ ... additional files and folders
      │   ├─ plugins.json
      │   └─ updatePlugins.js
      └─ ...
    

    The plugins.json file contained within the plugins directory is a combined manifest of all the registered plugins. This file is used to initialize installed plugins when the application loads. The updatePlugins.js script update this file. Plugins which are not defined in the plugins.json file are ignored when the application is loaded.

    Intalling a plugin manually can be done with the following steps:

    1. Copy the plugin directory into plugins/ (e.g.: plugins/<example_plugin>).
    2. Run updatePlugins.js script:
      1. To run updatePlugins.js move into the plugins/ directory.
      2. Make sure to have nodejs installed and run the node updatePlugins.js command within the directory.
      3. This will generate a new plugins.json file.
    3. Refresh the application.

    The example plugin demonstrates how this can be automated. The grunt build task of the plugin is doing all the necessary steps.

    This can be due to multiple reasons:

    • The plugins.json may be cached by your browser. Try clearing your browser cache.
    • registerPlugin wasn't called at runtime to register the plugin instance at the plugin manager
    • updatePlugins.js was not executed.

    This could be a caching issue. This can happen if you don't update the plugin version with every build. Either clear your browser cache or update your plugin version. It also helps to keep the browser developer window open with disabled cacheing while devoloping plugins.

    The Changelog can be found here: Changelog


    © EasternGraphics GmbH | Albert-Einstein-Straße 1 | 98693 Ilmenau | GERMANY

    This work (whether as text, file, book or in other form) is copyright. All rights are reserved by EasternGraphics GmbH. Translation, reproduction or distribution of the whole or parts thereof is permitted only with the prior agreement in writing of EasternGraphics GmbH.

    EasternGraphics GmbH accepts no liability for the completeness, freedom from errors, topicality or continuity of this work or for its suitability to the intended purposes of the user. All liability except in the case of malicious intent, gross negligence or harm to life and limb is excluded.

    All names or descriptions contained in this work may be the trademarks of the relevant copyright owner and as such legally protected. The fact that such trademarks appear in this work entitles no-one to assume that they are for the free use of all and sundry.