Developing a BPC Module

Sometimes it may be necessary to develop your own module for BPC. A BPC module can serve various purposes.

A complete custom module with functions written in Java and its own interface
A module with its own user interface that can be integrated as a module instance on a page in BPC.
A widget for a dashboard
A plugin as an extension of existing base components

A backend module needs to be developed only if Java code is required or if custom REST interfaces need to be built.

Prerequisites

:link-with-underscores:_ https://docs.sencha.com/cmd/guides/cmd_packages/cmd_creating_packages.html#cmd_packages—cmd_creating_packages-adding_packages

IDE (JavaScript; support is helpful but not required)
- JetBrains WebStorm (paid)
- JetBrains IntelliJ IDEA (free, but does not offer full native JavaScript support)
- JetBrains IntelliJ IDEA Ultimate (paid)
- Visual Studio or Visual Studio Code
- …
Java 17 or higher is installed
Git, Maven, and Gradle are installed (already sufficiently integrated into some IDEs)

Sencha Cmd is installed

Sencha Cmd can also be installed as follows:

$ npm install -g sencha-cmd

For more information, visit the npm website at

During installation, make sure the “sencha” command is added to the environment variables.

Sencha ExtJS Framework or Sencha ExtJS SDK available locally

We will grant you access to the Sencha ExtJS SDK if you have licensed it for custom module development. If you do not yet have access, please contact our support team.

Creating a New BPC Frontend Module

The following steps explain how to create a minimal BPC frontend module. Please replace MODULEID in the following with a string of your choice. This should be in lowercase and as unique as possible.

Check out the frontend template module using Git or an IDE.
```
git clone https://bitbucket.org/virtimo/bpc-fe-template.git
cd bpc-fe-template
rm -rf .git
```
Then rename the directory bpc-fe-template to bpc-fe-MODULID and push it as a new Git repository.
Rename the local directory packages/local/bpc-fe-template to packages/local/bpc-fe-MODULID
1. In the directory packages/local/bpc-fe-MODULID and the file gradle.properties, replace the string template with MODULID.
Set up ExtJS in the workspace (root directory of the local directory) using one of the following methods:
1. If you have access to Virtimo NPM, run npm install
2. Copy ExtJS to the folder ./ext
3. Link ExtJS as a folder ./ext
  - Remove the ext file using git rm ext
  - On Linux: link the ExtJS directory
    
    ln -s /PFAD/ZU/ext ext
  - On Windows: Link the BpcCommon directory
    
    Works only with administrator privileges; to do this, start CMD as an administrator
    
    mklink /D ext PFAD\ZU\ext
Install the BpcCommon package using one of the following methods
- You can install BpcCommon.pkg locally from Download - Virtimo File Server (see also {link-with-underscores}[Sencha CMD])
- You can add our Sencha repo locally
  sencha repo add virtimo https://connect.virtimo.net/sencha-repo/
- You can check out our repository https://bitbucket.org/Virtimo/BPC-fe-corecommon and link it in your packages folder
  - On Linux: check out the BPCCommon directory and link it
    
    cd .. git clone git@bitbucket.org:virtimo/bpc-fe-corecommon.git mkdir -p bpc-fe-MODULID/packages/remote cd bpc-fe-MODULID/packages/remote ln -s ../../../bpc-fe-corecommon/packages/local/BpcCommon BpcCommon
  - On Windows: Check out the BpcCommon directory and create a link to it
    
    This only works with administrator privileges; to do this, start CMD as an administrator
    
    cd .. git clone git@bitbucket.org:virtimo/bpc-fe-corecommon.git mkdir -p bpc-fe-MODULID/packages/remote cd bpc-fe-MODULID/packages/remote mklink /D BpcCommon ../../../bpc-fe-corecommon/packages/local/BpcCommon
Build the frontend module using the command ./gradlew
- On Linux:
  ./gradlew
- On Windows:
  gradlew

Here are a few more notes

File packages/local/bpc-fe-MODULID/src/view/Main.js

This file is the main component of the module. It is instantiated when the module is displayed.

/**
 * Main BPC module view component. This component will be instanciated by bpc core if the module or an instance of it
 * have to be shown (by user interaction in the navigation or via code e.g. BPC.Api.showModule("MODULEID"))
 */
Ext.define('MODULNAME.view.Main', {
    extend: 'Ext.panel.Panel',

    layout: 'fit',
    //header: false,

    viewModel: {
        data: {
            name: undefined
        }
    },

    bind: {
        title: "Mein Name ist {name.value}" //bind title to name value
    },

    initComponent: function () {

        //call parent constructor
        this.callParent();
    }
});

File gradle.properties

The parameters in this file are essential for building the module. For example, customize the names and version according to your needs.

Creating a Pure Frontend Module

If you do not want to provide a backend module, you can omit it. To do this, a few extensions need to be made to the frontend module.

Please set the ` bundleType ` attribute to ` fe-only` in the file ` gradle.properties `. Otherwise, your module will only be loaded if a backend module is present.

Typically, module settings are specified by the backend module (see Backend Module Settings). To ensure your module still communicates settings to the BPC, add the following files (see Frontend Module Settings).

ressources/defaults/default_instance_settings.json

This file describes the possible settings for your module instances.

{
  "module": {
    "module_name": {
      "value": "MODULNAME",
      "type": "text",
      "_writeableByRoles": [
        "bpcadmin"
      ],
      "_readableByRoles": [
        "bpcadmin",
        "bpcuser"
      ],
      "_label": "CORE_SETTING_LABEL_MODULE_NAME"
    },
    "module_iconCls": {
      "value": "x-fal fa-calendar-edit",
      "type": "icon",
      "_writeableByRoles": [
        "bpcadmin"
      ],
      "_readableByRoles": [
        "bpcadmin",
        "bpcuser"
      ],
      "_label": "CORE_SETTING_LABEL_MODULE_ICONCLS"
    },
    "moduleHeader_description": {
      "value": "",
      "type": "text",
      "_writeableByRoles": [
        "bpcadmin"
      ],
      "_readableByRoles": [
        "bpcadmin",
        "bpcuser"
      ],
      "_label": "CORE_SETTING_LABEL_MODULEHEADER_DESCRIPTION"
    }
  }
}

resources/defaults/default_module_settings.json

This file describes general module settings.

{
  "module": {
    "module_iconCls": {
      "value": "x-fal fa-calendar-edit",
      "type": "icon",
      "_writeableByRoles": [
        "bpcadmin"
      ],
      "_readableByRoles": [
        "bpcadmin",
        "bpcuser"
      ],
      "_label": "CORE_SETTING_LABEL_MODULE_ICONCLS"
    }
  }
}

Loading CSS from BPC Modules

By default, the BPC does not load any additional CSS files from the modules. To change this behavior, please set the value of the ` config ` attribute in your BpcInterface class to ` css:true`. Now, the BPC will attempt to load the CSS file for your package from your module.

To enable the generation of CSS files when building the package, please set the value of the skip.sass attribute to 0 and add theme-triton as a dependency in packages/local/bpc-fe-MODULID/package.json:

"properties": {
  "skip.slice": 1,
  "skip.pkg": 1,
  "skip.sass": 0
},

"requires": [
  "theme-triton",
  "BpcCommon@x.x.x-x.x.xxx"
]

Creating a New BPC Backend Module

Check out the backend template module using Git or an IDE.
```
git clone https://bitbucket.org/virtimo/bpc-be-template.git
cd bpc-be-template
rm -rf .git
```
Then rename the directory bpc-be-template to bpc-be-MODULID and push it as a new Git repository.
If you want to build the backend module locally, you’ll need a few BPC Maven dependencies. Please contact the BPC developers (Virtimo AG).
Go to src/main/java/de/virtimo/bpc/module/template and refactor the class and package names for your {MODULENAME}. You can use your IDE’s refactor function for this.
Check to make sure all classes, variables, etc., are named correctly.
Open pom.xml and change artifactId to bpc-be-{MODULENAME}.
Open pom.xml and adjust the value in name.
Open pom.xml → maven-bundle-plugin and change the class name of the Bundle Activator. To do this, adjust the following line <Bundle-Activator>de.virtimo.bpc.module.{MODULENAME}.{MODULENAME}Activator</Bundle-Activator> accordingly.

Keywords: