Ein Plugin in den Workbench integrieren

Sie bauen in diesem Tutorial ein vollständiges, lauffähiges Plugin, das ein Abzeichen in die Aktivitätsleiste, eine Ansicht in die Seitenleiste und einen Befehl in die Befehlsleiste des Workbench einhängt — über ein einziges Ereignis, ohne eine Zeile in wkfluentui zu ändern.

Das fertige Ergebnis liegt als installierbares Referenzpaket im Baum: lib/plugins/wkfluentuicontracttest/. Dieses Tutorial baut dasselbe Paket unter dem Namen wkexample von Hand nach.

wkcore wird für dieses Tutorial nicht gebraucht. Der Workbench-Contract läuft über ein reines DokuWiki-Ereignis; das Dienstregister kommt erst ins Spiel, wenn Sie Objekte an andere Pakete reichen wollen (API-Referenz).

Erzeugen Sie das Plugin-Verzeichnis und sein Manifest. Ohne plugin.info.txt lädt DokuWiki das Paket nicht.

lib/plugins/wkexample/
├── plugin.info.txt
├── action.php
├── admin.php
└── lang/
    └── en/
        └── lang.php

plugin.info.txt:

base   wkexample
author Ihr Name
email  ihre.adresse@example.com
date   2026-08-23
name   Example Contribution
desc   Registers one activity-bar badge, one sidebar view and one command through Workbench Plugin Contract v1.
url    https://example.com/wkexample

Das Feld date ist kein Schmuck: Erweiterungsmanager und dokuwiki.org vergleichen genau diesen Wert, um zu entscheiden, ob ein Update vorliegt. Setzen Sie ihn auf den Tag, an dem das Paket sich tatsächlich geändert hat.

Die action-Komponente ist der einzige Ort, an dem Ihr Plugin dem Workbench begegnet. Legen Sie action.php an:

<?php
 
use dokuwiki\Extension\ActionPlugin;
use dokuwiki\Extension\EventHandler;
use dokuwiki\Extension\Event;
 
class action_plugin_wkexample extends ActionPlugin
{
    public function register(EventHandler $controller)
    {
        $controller->register_hook(
            'WKFLUENTUI_REGISTER_CONTRIBUTIONS',
            'BEFORE',
            $this,
            'registerContributions'
        );
    }
 
    public function registerContributions(Event $event)
    {
        // Schritt 3 füllt diese Methode.
    }
}

Der Ereignisname steht hier ausgeschrieben und nicht als Klassenkonstante von wkfluentui. Das ist Absicht: register() läuft bei jeder Anfrage, auch wenn wkfluentui nicht installiert ist. Eine Klassenkonstante eines fehlenden Pakets zu nennen, nähme Ihrem Plugin die gesamte Hakenregistrierung mit.

Ein Beitrag ist ein einfaches Array. Pflicht sind nur owner und id; alles andere hat eine Vorgabe, die nichts verändert. Füllen Sie registerContributions():

    public function registerContributions(Event $event)
    {
        // Ein Abzeichen auf dem eigenen Eintrag der Aktivitätsleiste.
        $event->data['contributions'][] = [
            'owner' => 'wkexample',
            'id'    => 'badge',
            'badge' => [
                'count' => 3,
                'tone'  => 'warning',
                'label' => $this->getLang('badge_label'),
            ],
        ];
 
        // Eine Ansicht in der Seitenleiste des eigenen Bildschirms.
        $event->data['contributions'][] = [
            'owner'  => 'wkexample',
            'id'     => 'sidebar',
            'kind'   => 'view',
            'region' => 'sidebar',
            'label'  => $this->getLang('view_title'),
            'html'   => '<p>' . hsc($this->getLang('view_body')) . '</p>',
        ];
 
        // Ein Befehl in der Befehlsleiste und der Befehlspalette.
        $event->data['contributions'][] = [
            'owner'  => 'wkexample',
            'id'     => 'command',
            'kind'   => 'action',
            'region' => 'commandPalette',
            'label'  => $this->getLang('command_label'),
            'href'   => DOKU_BASE . 'lib/plugins/wkexample/plugin.info.txt',
        ];
    }

Drei Regeln, die hier bereits wirken:

• id wird namensraumiert. Aus wkexample und badge wird intern wkexample:badge. Schreiben Sie das Präfix nie selbst.
• Ein kind verlangt eine region. Ein Beitrag mit Inhalt, aber ohne gültige Region wird verworfen — nicht als Lücke gezeichnet.
• Ein Abzeichen mit count von 0 oder weniger erscheint nicht. „Nichts zu melden„ ist keine Null, die man anzeigt.

Die vollständige Feldliste steht in der API-Referenz.

Wenn Ihr Beitrag eine Region belegt, die es auf einer älteren Installation vielleicht nicht gibt, fragen Sie vorher nach — mit einem Namen, nicht mit einer Versionsnummer. Ergänzen Sie am Anfang von registerContributions():

        $caps = plugin_load('helper', 'wkfluentui_capabilities');
        $hasPanel = $caps !== null && $caps->has('workbench.contribution.bottomPanel');
 
        if ($hasPanel) {
            $event->data['contributions'][] = [
                'owner'  => 'wkexample',
                'id'     => 'panel',
                'kind'   => 'view',
                'region' => 'bottomPanel',
                'label'  => $this->getLang('panel_title'),
                'html'   => '<p>' . hsc($this->getLang('panel_body')) . '</p>',
            ];
        }

plugin_load() steht hier innerhalb des Hakens und nicht in register(). Zum Zeitpunkt des Hakens ist bewiesen, dass wkfluentui läuft — sonst hätte es das Ereignis nicht gefeuert.

Die Aktivitätsleiste zeigt einen Eintrag je installiertem Admin-Plugin. Sie wird aus plugin_list('admin') gebaut, nicht aus dem Contract. Ein Abzeichen schmückt diesen Eintrag; ohne Eintrag gibt es nichts zu schmücken. Legen Sie deshalb admin.php an:

<?php
 
use dokuwiki\Extension\AdminPlugin;
 
class admin_plugin_wkexample extends AdminPlugin
{
    public function getMenuSort()
    {
        return 500;
    }
 
    public function forAdminOnly()
    {
        return true;
    }
 
    public function handle()
    {
        // Dieser Bildschirm hat kein eigenes Formular.
    }
 
    public function html()
    {
        echo '<h1>' . hsc($this->getLang('title')) . '</h1>';
        echo '<p>' . hsc($this->getLang('body')) . '</p>';
    }
}

Dasselbe gilt für die Region adminModule: auch sie setzt ein Admin-Plugin als owner voraus, weil der Modulverzeichnisdienst das tragende Objekt mit plugin_load('admin', $owner) auflöst.

Beschriftungen gehören nie in den Descriptor. lang/en/lang.php:

<?php
 
$lang['menu']          = 'Example Contribution';
$lang['title']         = 'Example Contribution';
$lang['body']          = 'Proof that a plugin contributes through one event.';
$lang['badge_label']   = '3 items need attention';
$lang['view_title']    = 'Example view';
$lang['view_body']     = 'A native Contract v1 sidebar view.';
$lang['command_label'] = 'Example command';
$lang['panel_title']   = 'Example panel';
$lang['panel_body']    = 'Only registered where the host declares the capability.';

Der Schlüssel menu ist der Name, unter dem DokuWiki den Bildschirm in der Verwaltung führt.

Aktivieren Sie das Plugin im Erweiterungsmanager und öffnen Sie ?do=admin&mode=fluentui. Sie sehen:

1. In der Aktivitätsleiste einen Eintrag Example Contribution, darauf ein Abzeichen mit der Zahl 3 in Warnton.
2. Nach dem Öffnen des Bildschirms in der Seitenleiste die Ansicht Example view.
3. In der Befehlsleiste den Befehl Example command; er öffnet plugin.info.txt.
4. Bei installierter Unterstützung zusätzlich das untere Panel Example panel.

Prüfen Sie zusätzlich den Rückweg: ?do=admin ohne mode=fluentui liefert unverändert die Verwaltung, die DokuWiki selbst ausliefert. Ihr Bildschirm ist auch dort erreichbar. Das ist kein Zufall, sondern eine Zusicherung der Suite — ein Fehler in der Schale sperrt niemanden aus seiner Administration aus.

Zum Entfernen deaktivieren oder löschen Sie das Plugin. Es gibt nichts aufzuräumen: Der Haken feuert nicht mehr, und mit der nächsten Anfrage enthält das Register keinen Eintrag dieses Eigentümers mehr.

• How-To: eine Aktion hinter einen zweiten Faktor stellen — wenn Ihr Befehl etwas Schützenswertes auslöst.
• API-Referenz — die vollständige Feldliste, permission gegen enabled, die Versionierungsregel, und das Dienstregister.
• Fehlerbehebung — wenn der Beitrag nicht erscheint.