Admin & Dashboard

MD Dashboard Layout: Was das Plugin kann und wie seine Widget-API funktioniert

Drag & Drop, Zonen, Benutzerlayouts und die neue Registry für Dashboard-Widgets aus anderen Bludit-Plugins.

4 Minuten Lesezeit

Mit MD Dashboard Layout 1.1.1 wird das Bludit-3.22.x-Dashboard nicht nur verschiebbar, sondern zu einer kleinen Widget-Plattform. Das Plugin stellt drei Drag-&-Drop-Zonen bereit, speichert die Anordnung pro Benutzer als JSON und bietet ab Version 1.1.0 eine Registry, über die andere Plugins eigene Dashboard-Karten anmelden können.

Das Ziel ist bewusst ähnlich zu WordPress: Ein zentrales Dashboard kümmert sich um Layout und Bedienung, während Fachplugins nur ihren eigenen Inhalt liefern. Ein Kontaktformular-Plugin könnte so „Neue Nachrichten“ registrieren, ein Backup-Plugin „Letzte Sicherung“ und ein Radio-Plugin „Jetzt läuft“ – ohne dass jedes Plugin das Dashboard-DOM selbst umbauen muss.

Was MD Dashboard Layout übernimmt

  • drei Widget-Zonen: Hauptbereich, Seitenbereich und breiter Bereich
  • Drag & Drop zwischen den Zonen und innerhalb einer Zone
  • Ein-/Ausblenden einzelner Widgets über „Ansicht“
  • Einklappen einer Dashboard-Karte
  • benutzerspezifische Speicherung als JSON unter bl-content/workspaces/md-dashboard-layout/layouts/
  • CSRF-geschütztes Speichern und Zurücksetzen des Layouts
  • Fallback für Bludit 3.22.x über adminBodyEnd(), weil der historische dashboard()-Hook von der neuen Dashboard-View nicht mehr aufgerufen wird
  • ab Version 1.1.0: eine öffentliche Widget-Registry für andere Plugins

Die Trennung der Verantwortlichkeiten

Das Dashboard-Plugin rendert Rahmen, Titelzeile, Drag-Handle, Einklapp-Button und Zonen. Ein fremdes Plugin muss dagegen nur Metadaten und den eigentlichen Widget-Inhalt liefern. Genau diese Trennung verhindert, dass mehrere Plugins konkurrierend dieselben Dashboard-Container per JavaScript manipulieren.

Wichtig in Bludit 3.22.x: Hilfsklassen verzögert laden

Bludit 3.22.0 ermittelt Plugin-Klassen über get_declared_classes(): Es merkt sich die bereits vorhandenen Klassen, inkludiert anschließend alle plugin.php-Dateien und behandelt danach jede neu hinzugekommene Klasse als Bludit-Plugin. Deshalb darf eine reine Hilfsklasse wie MDDashboardWidgetRegistry nicht direkt auf Dateiebene in plugin.php stehen. Bludit würde sonst versuchen, auch diese Hilfsklasse zu instanziieren und Plugin-Methoden wie directoryName() aufzurufen – ein PHP-Fatal-Error, der sowohl Frontend als auch Administration mit HTTP 500 lahmlegt.

MD Dashboard Layout 1.1.1 legt die Registry deshalb in lib/widget-registry.php ab und lädt sie erst aus pluginMDDashboardLayout::init(). Zu diesem Zeitpunkt hat Bludit seine Plugin-Klassenliste bereits eingefroren. Die Registry steht danach für beforeAdminLoad() anderer Plugins zur Verfügung, ohne selbst als Plugin missverstanden zu werden.

public function init()
{
    require_once __DIR__.DS.'lib'.DS.'widget-registry.php';

    $this->dbFields = array(
        'replaceCoreDashboard' => true,
        'showDropHints' => true
    );
}

Die Widget-Registry

MDDashboardWidgetRegistry::register('mein-widget', array(
    'title' => 'Mein Widget',
    'icon' => 'puzzle-piece',
    'defaultZone' => 'side',
    'priority' => 100,
    'roles' => array('admin', 'editor', 'author'),
    'description' => 'Kurze Beschreibung',
    'source' => __CLASS__,
    'renderer' => array($this, 'renderDashboardWidget')
));

Bedeutung der Felder

  • id: eindeutige technische Kennung. Erlaubt sind Kleinbuchstaben, Zahlen, Bindestrich und Unterstrich; die ID beginnt mit einem Buchstaben.
  • title: sichtbarer Titel der Dashboard-Karte.
  • icon: Font-Awesome-Klassenname ohne fa-, zum Beispiel bell, server oder puzzle-piece.
  • defaultZone: main, side oder bottom. Diese Zone wird nur verwendet, solange der Benutzer noch keine eigene Position gespeichert hat.
  • priority: Sortierhilfe für neue Widgets. Die persönliche Drag-&-Drop-Reihenfolge hat danach Vorrang.
  • roles: optionale Liste zulässiger Rollen. Eine leere Liste bedeutet keine zusätzliche Rollenbeschränkung durch die Registry.
  • description: technische Beschreibung für Verwaltung und Diagnose.
  • renderer: ein PHP-Callback, der den HTML-Inhalt des Widgets zurückgibt.
  • source: freiwillige Herkunftsangabe, typischerweise __CLASS__.

Was der Renderer bekommt

array(
    'id' => 'mein-widget',
    'username' => 'admin',
    'role' => 'admin',
    'adminUrl' => '/bludit/admin/',
    'siteUrl' => 'https://example.test/bludit/',
    'bluditVersion' => '3.22.0'
)

Der Renderer gibt nur den Body zurück. Er soll keinen eigenen äußeren Dashboard-Container mit Drag-Attributen bauen. Dadurch bleiben alle Widgets optisch und funktional unter Kontrolle von MD Dashboard Layout.

Warum die Registrierung pro Request erfolgt

Die Registry ist absichtlich nur im PHP-Arbeitsspeicher vorhanden. Ein Plugin registriert sein Widget bei jedem Admin-Aufruf, beispielsweise in beforeAdminLoad(). Persistiert wird nur das Benutzerlayout. Dadurch landen keine PHP-Callbacks in JSON-Dateien, und deaktivierte Plugins verschwinden automatisch aus der aktiven Widget-Liste.

Was passiert mit gespeicherten Layouts, wenn ein Widget verschwindet?

Beim Einlesen normalisiert MD Dashboard Layout die gespeicherten IDs gegen die aktuell verfügbaren Widgets. Nicht mehr vorhandene Widgets werden verworfen. Neue Widgets werden automatisch in ihrer Standardzone ergänzt. Dadurch überlebt ein Benutzerlayout sowohl Plugin-Deaktivierungen als auch spätere Erweiterungen.

Installation und Test

  • Ordner md-dashboard-layout nach bl-plugins/ kopieren oder das ZIP mit dem Tutorial-Plugin-Uploader installieren.
  • In Bludit unter Plugins „MD Dashboard Layout“ aktivieren.
  • Optional „MD Dashboard Beispiel-Widget“ aktivieren.
  • Dashboard öffnen. Das Beispiel-Widget sollte in der rechten Zone erscheinen.
  • Widget in eine andere Zone ziehen und Seite neu laden. Die Position muss erhalten bleiben.
  • Unter „Ansicht“ das Widget ausblenden, neu laden und anschließend wieder einschalten.
  • Das Beispielplugin deaktivieren. Sein Widget muss verschwinden, ohne dass das Dashboard einen Fehler erzeugt.

Dateien und Datenhaltung

bl-plugins/md-dashboard-layout/
├── plugin.php
├── metadata.json
├── languages/
├── css/dashboard.css
└── js/dashboard.js

bl-content/workspaces/md-dashboard-layout/
└── layouts/
    ├── admin.json
    └── weiterer-benutzer.json

Wichtig für Erweiterungsentwickler

Ein Widget ist kein Sicherheits-Sandbox. Ein aktiviertes Plugin kann ohnehin PHP ausführen. Die Registry sorgt für eine saubere Schnittstelle und Layout-Koordination, ersetzt aber keine Prüfung fremder Plugins. HTML-Ausgaben müssen weiterhin korrekt escaped werden, Berechtigungen gehören weiterhin ins jeweilige Fachplugin und schreibende Aktionen brauchen CSRF-Schutz.

Passende Downloads