Extension-Entwicklung: Erste Schritte

Dieses Kapitel zeigt, wie Sie eine eigene Extension für das ProcessCube® Studio entwickeln.

Voraussetzungen

Node.js ≥ 18.15.0
npm (im Lieferumfang von Node.js)
TypeScript-Grundkenntnisse
React-Grundkenntnisse (für UI-Komponenten)
ProcessCube® Studio (Insiders oder Stable)

Extension-Projekt aufsetzen

Projektverzeichnis erstellen


mkdir meine-extension
cd meine-extension
npm init -y

Abhängigkeiten installieren


npm install @5minds/processcube_studio_sdk react react-dom
npm install -D typescript @types/react webpack webpack-cli esbuild-loader fork-ts-checker-webpack-plugin

TypeScript-Konfiguration

Erstellen Sie eine tsconfig.json:


{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "declaration": false,
    "outDir": "out",
    "rootDir": ".",
    "baseUrl": "."
  },
  "include": ["*.ts", "*.tsx", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules", "out"]
}

Webpack-Konfiguration

Erstellen Sie eine webpack.config.js:


const path = require('path');
const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');
 
module.exports = {
  mode: 'production',
  target: 'electron-renderer',
  entry: './index.ts',
  output: {
    filename: 'index.js',
    path: path.resolve(__dirname, 'out'),
    libraryTarget: 'commonjs2',
  },
  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.jsx'],
  },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        loader: 'esbuild-loader',
        options: { target: 'es2020' },
      },
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader'],
      },
    ],
  },
  plugins: [new ForkTsCheckerWebpackPlugin()],
  externals: {
    react: 'commonjs2 react',
    'react-dom': 'commonjs2 react-dom',
    '@5minds/processcube_studio_sdk': 'commonjs2 @5minds/processcube_studio_sdk',
  },
};

package.json anpassen


{
  "name": "meine-extension",
  "version": "1.0.0",
  "main": "out/index.js",
  "engines": {
    "studio": "^1.0.0"
  },
  "scripts": {
    "build": "webpack-cli"
  }
}

Entry-Point erstellen

Erstellen Sie die Datei index.ts:


import { Studio } from '@5minds/processcube_studio_sdk';
 
export function onLoad(studio: Studio): void {
  // Hier registriert sich Ihre Extension
  console.log('Meine Extension wurde geladen!');
}

Extension bauen


npm run build

Projektstruktur

Nach dem Setup sollte Ihr Projekt so aussehen:

- index.ts
- package.json
- tsconfig.json
- webpack.config.js
- - index.js

Extension testen

Starten Sie das Studio mit dem Flag --extension-development-dir und dem Pfad zu Ihrer Extension:

macOS


/Applications/ProcessCube\ Studio\ \(Insiders\).app/Contents/MacOS/ProcessCube\ Studio\ \(Insiders\) \
  --extension-development-dir "${PWD}"

Verwenden Sie für die Entwicklung die Insiders-Version des Studios. Sie enthält die neuesten Features und API-Änderungen.

Die `onLoad`-Funktion

Jede Extension muss eine onLoad-Funktion exportieren. Sie ist der Einstiegspunkt und erhält die Studio-Instanz als Parameter:


import { Studio } from '@5minds/processcube_studio_sdk';
 
export function onLoad(studio: Studio): void {
  // Commands registrieren
  studio.commands.register('meineExtension.sagHallo', () => {
    studio.notifications.open('Hallo von meiner Extension!');
  });
 
  // Menüs erweitern
  studio.menus.registerMenuModifier('std/activity-bar/settings', (menu) => {
    return studio.menus.appendToMenu(menu, [
      { type: 'divider' },
      {
        type: 'command',
        id: 'mein-menuepunkt',
        label: 'Sage Hallo',
        command: 'meineExtension.sagHallo',
      },
    ]);
  });
}

Was kann eine Extension registrieren?

Registrierung	API	Beschreibung
Commands	`studio.commands`	Ausführbare Aktionen, auch über Command Palette
Menüs	`studio.menus`	Kontextmenüs und Menü-Modifikatoren
Menu Bar	`studio.menuBar`	Einträge in der Menüleiste
Editoren	`studio.editors`	Eigene Dokumenttypen mit Model + Renderer
Panes	`studio.panes`	Seitenpanels (links, rechts, unten)
Activity Bar	`studio.activityBar`	Icons in der Seitenleiste
Status Bar	`studio.statusBar`	Einträge in der Statusleiste
Icons	`studio.icons`	Eigene Icons registrieren
Settings	`studio.settings`	Standardwerte für Einstellungen
Keybindings	`studio.keybindings`	Tastenkombinationen

Nächste Schritte

Folgen Sie den Tutorials, um die einzelnen Funktionsbereiche kennenzulernen:

Hello World — Ihr erstes Command mit Notification
Menüs erweitern — Menüpunkte hinzufügen
Activity Bar & Panes — Seitenleiste und Panels
Custom Editor — Eigenen Editor erstellen
Datei-Editor — Editor für Dateitypen
BPMN Custom Properties — BPMN-Elemente erweitern