Repository navigation
Plugins schreiben
English: Writing plugins
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
pluginsim 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>.replacederhalten.
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 Angabegroovy.<Dateiname>. - Das Skript läuft beim Start des Plugins;
yabsist derExtensionContext,plugindas Plugin selbst. Closures funktionieren überall, wo die Schnittstelle eine Funktion erwartet. - Ein Skript kann auch ein Objekt zurückgeben (
return), dasYabsExtensionimplementiert – dann ist dieses Objekt das Plugin.
-
mpv5.plugin.api.YabsExtensionimplementieren:
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 */ });
}
}- Die Klasse in
META-INF/services/mpv5.plugin.api.YabsExtensioneintragen (eine Klasse pro Zeile – ein Jar kann mehrere Plugins enthalten):
com.example.Hallo
- Gegen
openyabs.jar(und bei Bedarflib/*) kompilieren, ein Jar bauen, inpluginslegen 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 | 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
|
| 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 |
| 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.
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'))
}
})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.
- 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,onViewmit Badges, Bannern und Sperren, Befehle, eine Einstellungsseite, ein Tab, Suchergebnisse, eigene Datenbanktabellen und ein Timer. Es liegt YaBS alsplugins/gobd-compliance.jarbei.
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).
![]()
Download installation packages here!
Deutsch
- Dokumentation (DE)
- Beschreibung
- Hinweise und Neuerungen
- Datenbank
- E-Rechnung
- Kleinunternehmer
- Datenschutz (DSGVO)
- Journal
- GoBD
- SEPA-Lastschrift
- Kontaktliste
- QR-Code
- Dateinamen
- Shopify
- Kasse und TSE
- Vorlagen
- Spaltendefinition
- Skripte
Plugins (DE)
- Plugins (Übersicht)
- DATEV-Export
- GoBD-Plugin
- Heilpraktiker-Plugin
- Kfz-Werkstatt-Plugin
- Vereinsverwaltung-Plugin
- ScriptOnSavePlugin
- Plugins schreiben
English
- Documentation (EN)
- Notes and changes
- Database
- Journal
- Small business VAT exemption
- Data protection (GDPR)
- SEPA direct debit
- Contact list
- QR code
- File name defaults
- Shopify
- Cash register and TSE
- Templates
- Scripts
Plugins (EN)