Skip to content

Plugins schreiben

Claude edited this page Nov 19, 2026 · 2 revisions

English: Writing plugins

Plugins für YaBS schreiben

Plugins ergänzen YaBS um Befehle, Suchergebnisse, Einstellungsseiten, Tabs, Markierungen in Datensatz-Ansichten und Reaktionen – in Groovy (eine einzelne Datei, ohne Build) oder in Java (ein Jar). Beide bekommen dieselbe Schnittstelle: den ExtensionContext.

  • Plugins liegen im Ordner plugins im YaBS-Ordner (Einstellungen › Plugin-Manager › Ordner öffnen).
  • Einstellungen › Plugin-Manager zeigt alle Plugins mit ihrem Zustand. Dort lassen sich Plugins aktivieren, deaktivieren, neu laden, bearbeiten und entfernen; oben unter Plugin hinzufügen stehen gleichrangig Neues Groovy-Plugin…, Groovy-Plugin importieren… und Java-Plugin importieren…; eine .jar- / .groovy-Datei kann man auch auf die Seite ziehen.
  • Befehle von Plugins erscheinen im Menü Plugins und in Alles durchsuchen (Umschalt Umschalt).
  • YaBS lädt die Plugins nach dem Start im Hintergrund; die Statuszeile zeigt den Fortschritt (Plugins werden geladen (2/5): …). Das Fenster ist währenddessen bedienbar.
  • Ein fehlerhaftes Plugin wird mit seiner Fehlermeldung als fehlgeschlagen markiert; YaBS und die anderen Plugins laufen weiter.
  • Alles, was ein Plugin hinzufügt, wird beim Stoppen (deaktivieren, neu laden, entfernen) wieder entfernt – ein Plugin kann also ohne Neustart von YaBS entwickelt und neu geladen werden.
  • Jedes Plugin hat eine ID. Zwei Plugins mit derselben ID laufen nie gleichzeitig. Wird ein Jar installiert, dessen Plugin die ID eines Plugins aus einer anderen Datei hat (z. B. die Java-Version eines Groovy-Skripts), ersetzt es dieses Plugin; die alte Datei bleibt als <Name>.replaced erhalten.

Ein Plugin in Groovy – 30 Sekunden

Einstellungen › Plugin-Manager › Neues Groovy-Plugin… legt ein lauffähiges Plugin aus einer Vorlage an und öffnet es im Plugin-Editor von YaBS: Groovy-Hervorhebung, Zeilennummern, Beispiel einfügen (Befehl, Suchergebnisse, Reaktion auf neue Datensätze, Einstellungsseite, eigener Tab, Record-Modifier, gespeicherte Werte, Hintergrundarbeit), Prüfen (F5) zeigt die Zeile eines Fehlers, Speichern und starten (Strg+S) lädt das Plugin sofort neu. Bearbeiten öffnet vorhandene Groovy-Plugins dort; Anderer Editor öffnet die Datei im eigenen Editor. Bei großen Skripten (ab etwa 60.000 Zeichen) schaltet der Editor die Hervorhebung ab, damit das Tippen schnell bleibt – sehr große Plugins schreibt man besser in Java.

Oder plugins/hallo.groovy selbst anlegen:

// @name Hallo
// @description Sagt Hallo und bemerkt neue Rechnungen
// @version 1.0
// @author Sie
// @minYabsVersion 2.0.10

// ein Befehl: Menü "Plugins" und Alles durchsuchen
yabs.addCommand('Hallo sagen', 'Ein erster Befehl', {
    yabs.notify('Hallo aus Groovy!')
})

// auf neue Datensätze reagieren (und erzeugte Dateien, geänderte und gelöschte Datensätze)
yabs.onActivity({ entry ->
    if (entry.kind == mpv5.handler.Activity.Kind.CREATED && entry.detail == 'Rechnung') {
        yabs.notify('Neue Rechnung: ' + entry.text)
    }
})

// Ergebnisse in Alles durchsuchen
yabs.addSearchProvider({ text ->
    text == 'wetter' ? [new mpv5.plugin.api.SearchResult('Wetter öffnen', 'wttr.in', {
        java.awt.Desktop.desktop.browse(new URI('https://wttr.in'))
    })] : []
})

// läuft, wenn das Plugin stoppt (dasselbe wie yabs.onStop { ... })
onStop = { }

Speichern und im Plugin-Manager Neu laden klicken – fertig.

  • Die Kommentarzeilen oben (// @name, @description, @version, @author, @id, @minYabsVersion) beschreiben das Plugin; die ID ist ohne Angabe groovy.<Dateiname>.
  • Das Skript läuft beim Start des Plugins; yabs ist der ExtensionContext, plugin das Plugin selbst. Closures funktionieren überall, wo die Schnittstelle eine Funktion erwartet.
  • Ein Skript kann auch ein Objekt zurückgeben (return), das YabsExtension implementiert – dann ist dieses Objekt das Plugin.

Ein Plugin in Java

  1. mpv5.plugin.api.YabsExtension implementieren:
package com.example;

import mpv5.plugin.api.ExtensionContext;
import mpv5.plugin.api.YabsExtension;

public class Hallo implements YabsExtension {
    public String id()             { return "com.example.hallo"; }
    public String name()           { return "Hallo"; }
    public String description()    { return "Sagt Hallo"; }
    public String minYabsVersion() { return "2.0.10"; }

    public void start(ExtensionContext ctx) {
        ctx.addCommand("Hallo sagen", "Ein erster Befehl", () -> ctx.notify("Hallo!"));
        ctx.onStop(() -> { /* schließen, was das Plugin selbst geöffnet hat */ });
    }
}
  1. Die Klasse in META-INF/services/mpv5.plugin.api.YabsExtension eintragen (eine Klasse pro Zeile – ein Jar kann mehrere Plugins enthalten):
com.example.Hallo
  1. Gegen openyabs.jar (und bei Bedarf lib/*) kompilieren, ein Jar bauen, in plugins legen oder im Plugin-Manager installieren.

Ein minimales build.gradle:

plugins { id 'java' }
dependencies { compileOnly files('/pfad/zu/openyabs/openyabs.jar') }
java { toolchain { languageVersion = JavaLanguageVersion.of(21) } }

Groovy und Java im Vergleich

Groovy Java
Die Schnittstelle yabs (der ExtensionContext) das ctx, das start bekommt
ID, Name, Beschreibung, Version, Autor // @id, // @name, // @description, // @version, // @author id(), name(), description(), version(), author()
Mindestversion von YaBS // @minYabsVersion 2.0.10 minYabsVersion()
Start das Skript läuft start(ctx)
Stopp onStop = { … } oder yabs.onStop { … } stop() oder ctx.onStop(() -> …)
Funktionen Closures { x -> … } Lambdas x -> …
Weitergabe eine .groovy-Datei ein .jar mit META-INF/services/mpv5.plugin.api.YabsExtension

Was der Kontext bietet

Beiträge (werden beim Stoppen des Plugins wieder entfernt)

Methode Was sie tut
addCommand(titel, beschreibung, aktion) ein Befehl im Menü Plugins und in Alles durchsuchen (läuft im Swing-Thread)
addSearchProvider(text -> List<SearchResult>) Ergebnisse in Alles durchsuchen (läuft im Hintergrund; schnell halten). new SearchResult(titel, detail, () -> …)
addSettingsPage(titel, beschreibung, () -> JComponent) eine Seite in den Einstellungen (Gruppe Plugins), über die Suche der Einstellungen zu finden
onActivity(entry -> …) erfährt von angelegten / geänderten / gelöschten Datensätzen, erzeugten Dateien (PDF, ODT, E-Rechnungen) und Meldungen – siehe Activity.Entry: kind, text, detail, file, context, id (Swing-Thread)
addRecordModifier(DatabaseObjectModifier) wirkt beim Speichern, Anlegen und Löschen von Datensätzen mit: modifyOnSave, modifyOnDelete (ChangeNotApprovedException werfen, um die Änderung zu verhindern), executeAfterCreate, executeAfterSave, modifyOnExplode, modifyOnResolve
onView(ansicht -> …) erfährt, wenn eine Datensatz-Ansicht (DataPanel) geöffnet wird oder einen anderen Datensatz zeigt, auch für Ansichten, die beim Start des Plugins schon offen sind – siehe Datensatz-Ansichten unten
onStop(() -> …) läuft, wenn das Plugin stoppt, deaktiviert, neu geladen wird oder nicht starten kann

Aktionen und Hilfen

Methode Was sie tut
openTab(titel, komponente) öffnet einen Tab im Hauptfenster
notify(meldung) eine Meldung in der Statuszeile und der Aktivitätenliste
popup(meldung) / error(meldung) ein Benachrichtigungsfenster (und die Aktivitätenliste)
notify(meldung, datensatz) ein Benachrichtigungsfenster zu einem Datensatz, mit dem Datensatz protokolliert (ein Klick öffnet ihn)
select(sql) führt ein SELECT auf der YaBS-Datenbank aus, liefert Object[][] (nie null)
execute(sql) führt eine Anweisung aus (CREATE TABLE, INSERT, UPDATE …)
ui(() -> …) führt Code im Swing-Thread aus (sofort, wenn schon dort)
background(arbeit, danach) erledigt Arbeit im Hintergrund und macht mit dem Ergebnis im Swing-Thread weiter; Fehler werden gemeldet
currentView() die Datensatz-Ansicht im ausgewählten Tab, oder null
refreshView(datensatz) zeigt den Datensatz im ausgewählten Tab neu an, wenn dieser ihn zeigt (z. B. nachdem das Plugin ihn geändert hat)
openFile(datei) öffnet eine Datei mit ihrem Programm (PDFs: der PDF-Betrachter aus Einstellungen › Externe Programme)
settings() Einstellungen des Plugins (Schlüssel/Wert), auf diesem Rechner gespeichert: get, set, getBoolean, setBoolean
dataFolder() ein Ordner für eigene Dateien des Plugins
yabsVersion() die Version von YaBS

select und execute nehmen einfaches SQL: Eingaben von Benutzern nur maskiert (' verdoppelt) in eine Abfrage übernehmen, oder die normalen YaBS-Klassen verwenden.

Datensatz-Ansichten

In onView kann ein Plugin die Ansicht (mpv5.ui.panels.DataPanel) markieren; YaBS entfernt diese Markierungen, bevor es die Plugins erneut aufruft:

Methode der Ansicht Was sie tut
getDataOwner() der gezeigte Datensatz (Item, Contact, Product, Expense, Revenue …)
setPluginBadge(komponente) eine kleine Markierung im Kopf der Ansicht, neben dem Status
setPluginBanner(komponente) ein Banner unter der Befehlsleiste, z. B. mit Schaltflächen
setContentLocked(true) sperrt die Inhaltsfelder und Positionen (Zahlungsstatus, Mahnungen, Export bleiben bedienbar)
setLockedDocument(datei) für einen gesperrten Datensatz: Drucken, PDF, Vorschau und E-Rechnung öffnen diese archivierte Datei, statt eine neue zu erzeugen
setDataOwner(datensatz, true) zeigt einen Datensatz (neu) an
yabs.onView({ ansicht ->
    def r = ansicht.getDataOwner()
    if (r instanceof mpv5.db.objects.Item && r.__getIntstatus() == mpv5.db.objects.Item.STATUS_PAID) {
        ansicht.setPluginBadge(new javax.swing.JLabel('bezahlt'))
    }
})

Threads

start, stop, Befehle, onActivity, onView und der zweite Teil von background laufen im Swing-Thread – kurz halten und für länger dauernde Datenbankarbeit background verwenden. Suchanbieter laufen im Hintergrund. stop() / onStop braucht ein Plugin nur für das, was es selbst angelegt hat (Threads, Timer, Verbindungen) – alles über den Kontext Registrierte entfernt YaBS.

Datensätze, Kontexte und Abfragen sind die normalen YaBS-Klassen (mpv5.db.common.DatabaseObject, Context, QueryHandler, …); die Groovy-Konsole (Einstellungen › GroovyConsole) eignet sich gut zum Ausprobieren.

Beispiele

  • Das Aktivitätsjournal (Quelltext) gehört zu YaBS: Es schreibt erzeugte Dateien und Datensätze in ein CSV-Journal, macht das Journal in Alles durchsuchen findbar und bietet einen Befehl und eine Einstellungsseite. Es lässt sich wie jedes andere Plugin deaktivieren.
  • Das GoBD-Plugin (Quelltext, Dokumentation) ist ein großes Java-Plugin: Record-Modifier, onActivity, onView mit Badges, Bannern und Sperren, Befehle, eine Einstellungsseite, ein Tab, Suchergebnisse, eigene Datenbanktabellen und ein Timer. Es liegt YaBS als plugins/gobd-compliance.jar bei.

Klassische Plugins

Plugins älterer YaBS-Versionen (eine Klasse plugin.Main, die mpv5.pluginhandling.YabsPlugin implementiert, in der Datenbank gespeichert) funktionieren weiterhin; sie stehen unten im Plugin-Manager unter Klassische Plugins (Datenbank) (mit Anzeigen aufklappen).

Clone this wiki locally