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 into a page in BPC as a module instance.
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 set up.

Prerequisites

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

Sencha Cmd can also be installed as follows:

$ npm install -g sencha-cmd

For more information, visit the npm website.

During installation, make sure that the command ` sencha ` is available via the ` PATH` environment variable.

Sencha ExtJS Framework or Sencha ExtJS SDK installed 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.

The following repository serves as a template for new frontend modules:
```
https://bitbucket.org/virtimo/bpc-fe-template
```
Create a new Git repository for your new project at bpc-fe-MODULEID.

To gain access to the repository, please contact our support team.
Rename the local directory packages/local/bpc-fe-template to packages/local/bpc-fe-MODULEID
In the directory packages/local/bpc-fe-MODULEID and the file gradle.properties, replace the string template with MODULEID
Deploy ExtJS to the workspace (root directory of the local directory) using one of the following methods
1. If you have access to Virtimo NPM, 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, run 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 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-MODULEID/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

The following steps explain how to create a minimal BPC backend module.

The following repository serves as a template for new backend modules:
```
https://bitbucket.org/virtimo/bpc-be-template
```
Create a new Git repository for your new project at bpc-be-MODULEID.

To gain access to the repository, please contact our support team.
If you want to build the backend module locally, you will need some BPC-specific Maven dependencies. Please contact the BPC developers (Virtimo AG).
Go to src/main/java/de/virtimo/bpc/module/template and change the class names and package names to match your {MODULENAME}. We recommend using the refactoring feature of an IDE for this.
Check to make sure all classes, variables, etc., are named correctly.
The following changes are required in the file pom.xml:
1. Change the entry artifactId to bpc-be-{MODULENAME}.
2. Change the entry name from Template (Backend) to your module name.
3. In the plugin configuration for the maven-bundle-plugin plugin, the entry Bundle-Activator must be updated to match the new class name. Depending on whether you used a refactoring feature, this may have been done automatically.

Keywords: