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 (free und Premiumvariante verfügbar, aber keine vollständige native Javascript Unterstützung)
- Visual Studio oder Visual Studio Code
- …
Git und Gradle installiert (in manchen IDE bereits ausreichend integriert)
Sencha Command installiert

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 lizensiert haben. Falls Sie noch keinen Zugriff haben, kontaktieren Sie unseren Support.

JRE (11 oder höher) installiert

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.

Template Modul mit Git oder IDE auschecken, anschließend ggf. git remote Repository ändern
```
git clone https://bitbucket.org/virtimo/bpc-fe-template.git
```
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
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 Ordner ./ext kopieren
3. ExtJS in Ordner ./ext linken
  - 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. Damit Ihr Modul dennoch Einstellungen dem BPC gegenüber mitteilt, fügen Sie die folgenden Dateien hinzu.

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, darf in der package.json nicht "skip.sass": 1 enthalten sein.

Erstellen eines neuen BPC Backend Moduls

Backend Template Modul mit Git oder IDE auschecken anschließend ggf. git remote Repository ändern
```
git clone https://bitbucket.org/virtimo/bpc-fe-template.git
```
Sie benötigen eine lokale Maven-Ref, falls Sie das Backend Modul lokal bauen möchten. Wenden Sie sich bitte an BPC Entwickler (Virtimo AG).
Gehen Sie zu src/main/java/de/virtimo/bpc/module/template und refactorieren Sie die Klassennamen und Packages-Namen zu Ihrem {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 in bpc-be-{MODULENAME}, und ändern Sie auch den name.
Öffnen Sie die pom.xml → maven-bundle-plugin und ändern Sie den Aktivator-Klassenname: überprüfen Sie folgende Zeile in der pom.xml <Bundle-Activator>de.virtimo.bpc.module.{MODULENAME}.{MODULENAME}Activator</Bundle-Activator>

Keywords: