BPC Modul entwickeln

Manchmal kann es notwendig sein, ein eigenes Modul für BPC zu entwickeln. Ein BPC Modul kann dabei unterschiedliche Verwendungszwecke haben.

Ein vollständiges eigenes Modul mit in Java geschriebenen Funktionen und eigener Schnittstelle
Ein Modul mit eigener Oberfläche, dass als Modul Instanz auf einer Seite im BPC eingebunden werden kann.
Ein Widget für ein Dashboard
Ein Plugin als Erweiterung von bestehenden Basiskomponenten

Nur wenn Java Code benötigt oder aber eigene Rest-Schnittstellen aufgebaut werden sollen, ist es notwendig ein Backend Modul zu entwickeln.

Grundvoraussetzung

IDE (Javascript, Unterstützung hilfreich aber nicht notwendig)
- JetBrains WebStorm (kostenpflichtig)
- JetBrains IntelliJ IDEA (kostenlos, aber keine vollständige native Javascript Unterstützung)
- JetBrains IntelliJ IDEA Ultimate (kostenpflichtig)
- Visual Studio oder Visual Studio Code
- …
Java 21 oder höher ist installiert
Git, Maven und Gradle sind installiert (in manchen IDEs bereits ausreichend integriert)

Sencha Cmd ist installiert

Sencha Cmd kann auch wie folgt installiert werden:

$ npm install -g sencha-cmd

Für weitere Informationen besuchen Sie die npm Seite

Bei der Installation darauf achten, dass der Befehl “sencha” in den Umgebungsvariablen aufgenommen ist.

Sencha ExtJs Framework oder Sencha ExtJs SDK lokal vorhanden

Sie erhalten von uns Zugriff auf das Sencha ExtJS SDK, wenn Sie es für individuelle Modulentwicklung lizenziert haben. Falls Sie noch keinen Zugriff haben, kontaktieren Sie unseren Support.

Erstellen eines neuen BPC Frontend Moduls

Die folgenden Schritte erläutern, wie Sie zu einem minimalen BPC Frontend Modul kommen. Bitte ersetzen Sie im Folgenden MODULEID durch ein selbstgewählten String. Dieser sollte kleingeschrieben sein und möglichst eindeutig.

Das Frontend Template Modul mit Git oder IDE auschecken.
```
git clone https://bitbucket.org/virtimo/bpc-fe-template.git
cd bpc-fe-template
rm -rf .git
```
Anschließend das Verzeichnis bpc-fe-template nach bpc-fe-MODULID umbenennen und als neues Git Repository pushen.
Das lokale Verzeichnis packages/local/bpc-fe-template umbenennen in packages/local/bpc-fe-MODULID
Im Verzeichnis packages/local/bpc-fe-MODULID und der Datei gradle.properties den String template durch MODULID ersetzen
ExtJS im Workspace (Hauptverzeichnis des lokalen Verzeichnisses) auf eine der folgenden Weisen bereitstellen
1. Bei Zugriff auf das Virtimo NPM, npm install ausführen
2. ExtJS in den Ordner ./ext kopieren
3. ExtJS als Ordner ./ext verlinken
  - Entfernen der ext Datei mit git rm ext
  - unter Linux: das ExtJs Verzeichnis verlinken
    
    ln -s /PFAD/ZU/ext ext
  - unter WINDOWS: das BpcCommon Verzeichnis verlinken
    
    Funktioniert nur mit Administratorrechten, dazu CMD als Admin starten
    
    mklink /D ext PFAD\ZU\ext
Installieren des BpcCommon Pakets auf eine der folgenden Weisen
- Sie können die BpcCommon.pkg aus Download - Virtimo Fileserver lokal installieren (siehe auch Sencha CMD)
- Sie können unser Sencha Repo lokal hinzufügen
  sencha repo add virtimo https://connect.virtimo.net/sencha-repo/
- Sie können unser Repository https://bitbucket.org/virtimo/bpc-fe-corecommon auschecken und in Ihrem packages Ordner verlinken
  - unter Linux: das BpcCommon Verzeichnis auschecken und verlinken
    
    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
  - unter WINDOWS: das BpcCommon Verzeichnis auschecken verlinken
    
    Funktioniert nur mit Administratorrechten, dazu CMD als Admin starten
    
    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
Frontend Modul bauen mit dem Befehl ./gradlew
- unter Linux:
  ./gradlew
- unter WINDOWS:
  gradlew

Folgend noch ein paar Hinweise

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

Diese Datei ist die Hauptkomponente des Moduls. Diese wird beim Anzeigen des Moduls instanziiert.

/**
 * 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();
    }
});

Datei gradle.properties

Die Parameter in dieser Datei sind essenziell zum Bauen des Moduls. Passen Sie z.B. die Namen und Version nach Ihren Bedürfnissen an.

Erstellen eines reinen Frontend-Moduls

Sollten Sie kein Backend Modul bereitstellen wollen, dann können Sie dieses auch weglassen. Dafür sind am Frontend Modul ein paar Erweiterungen vorzunehmen.

Setzen Sie bitte in der Datei gradle.properties dass Attribut bundleType auf fe-only. Ansonsten wird Ihr Modul nur in Anwesenheit eines Backend Moduls geladen werden.

In der Regel werden Modul-Einstellungen vom Backend Modul vorgegeben (siehe Backend Modul-Einstellungen). Damit Ihr Modul dennoch Einstellungen dem BPC gegenüber mitteilt, fügen Sie die folgenden Dateien hinzu (siehe Frontend Modul-Einstellungen).

ressources/defaults/default_instance_settings.json

Diese Datei beschreibt die möglichen Einstellungen an Ihren Modul Instanzen.

{
  "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

Diese Datei beschreibt allgemeine Moduleinstellungen.

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

Laden von CSS aus BPC Modulen

Das BPC lädt in der Regel keine weiteren CSS Dateien aus den Modulen. Um dieses Verhalten zu ändern, setzen Sie bitte in Ihrer BpcInterface Klasse im Attribut config den Wert css:true. Nun wird das BPC Versuchen aus Ihrem Modul die CSS Datei ihres Packages zu laden.

Um das Erzeugen der CSS Dateien beim Bauen des Packages zu aktivieren, setzen Sie bitte den Wert des Attributs skip.sass auf 0 und fügen Sie theme-triton als Abhängigkeit in packages/local/bpc-fe-MODULID/package.json hinzu:

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

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

Erstellen eines neuen BPC Backend Moduls

Backend Template Modul mit Git oder IDE auschecken.
```
git clone https://bitbucket.org/virtimo/bpc-be-template.git
cd bpc-be-template
rm -rf .git
```
Anschließend das Verzeichnis bpc-be-template nach bpc-be-MODULID umbenennen und als neues Git Repository pushen.
Falls Sie das Backend Modul lokal bauen möchten, benötigen Sie ein paar BPC Maven Dependencies. Wenden Sie sich bitte an die BPC Entwickler (Virtimo AG).
Gehen Sie zu src/main/java/de/virtimo/bpc/module/template und refactorieren Sie die Klassen- und Package-Namen für Ihr {MODULENAME}. Hierfür können Sie die Refactor-Funktion Ihres IDEs nutzen.
Überprüfen Sie, ob alle Klassen und Variablen usw. die richtige Benennung haben.
Öffnen Sie die pom.xml und ändern Sie die artifactId zu bpc-be-{MODULENAME}.
Öffnen Sie die pom.xml und passen den Wert in name an.
Öffnen Sie die pom.xml → maven-bundle-plugin und ändern Sie den Klassenname des Bundle-Activator. Dazu passen Sie folgende Zeile <Bundle-Activator>de.virtimo.bpc.module.{MODULENAME}.{MODULENAME}Activator</Bundle-Activator> entsprechend an.

Keywords: