Develop BPC module

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

A complete module with functions written in Java and its own interface
A module with its own 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 basic components

It is only necessary to develop a backend module if Java code is required or if you want to create your own residual interfaces.

Basic requirement

IDE (Javascript, support helpful but not necessary)
- JetBrains WebStorm (chargeable)
- JetBrains IntelliJ IDEA (free, but no full native Javascript support)
- JetBrains IntelliJ IDEA Ultimate (chargeable)
- Visual Studio or Visual Studio Code
- …
Java 21 or higher is installed
Git, Maven and Gradle are installed (already sufficiently integrated in 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 page

When installing, make sure that the "sencha" command is included in the environment variables.

Sencha ExtJs Framework or Sencha ExtJs SDK available locally

You will receive access to the Sencha ExtJS SDK from us if you have licensed it for individual module development. If you do not yet have access, please contact our Support.

Creating a new BPC frontend module

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

Check out the frontend template module with Git or 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
In the directory packages/local/bpc-fe-MODULID and the file gradle.properties replace the string template with MODULID
Deploy ExtJS in the workspace (root directory of the local directory) in one of the following ways
1. When accessing the Virtimo NPM, execute npm install
2. Copy ExtJS to the folder ./ext
3. Link ExtJS as folder ./ext
  - Remove the ext file with git rm ext
  - under Linux: link the ExtJs directory
    
    ln -s /PFAD/ZU/ext ext
  - under WINDOWS: link the BpcCommon directory
    
    Only works with administrator rights, start CMD as admin
    
    mklink /D ext PFAD\ZU\ext

Install the BpcCommon package in one of the following ways

You can install the BpcCommon.pkg from Download - Virtimo Fileserver locally (see also Sencha CMD)

You can add our Sencha repo locally

sencha repo add virtimo https://connect.virtimo.net/sencha-repo/

You can add our repository https://bitbucket.org/virtimo/bpc-fe-corecommon and link it in your packages folder

under Linux: check out and link the BpcCommon directory

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

under WINDOWS: check out the BpcCommon directory link

Only works with administrator rights, start CMD as admin

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 frontend module with the command ./gradlew
- under Linux:
  ./gradlew
- under WINDOWS:
  gradlew

The following 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, adjust the name and version according to your needs.

Creating a pure frontend module

If you do not want to provide a backend module, you can also omit it. A few extensions must be made to the frontend module.

Please set the attribute bundleType to fe-only in the file gradle.properties. Otherwise, your module will only be loaded in the presence of a backend module.

As a rule, module settings are specified by the backend module (see Backend module settings). To ensure that 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

The BPC usually does not load any further CSS files from the modules. To change this behavior, please set the value css:true in the attribute config in your BpcInterface class. Now the BPC will try to load the CSS file of your package from your module.

To activate the creation of CSS files when building the package, please set the value of the attribute skip.sass 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"
]

Create a new BPC backend module

Check out backend template module with Git or 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 will 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 the refactor function of your IDE for this.
Check that all classes and variables etc. have the correct names.
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: