How-to: Einzelne Bausteine ergänzen

Zurück: FluentUI (Design-System-Bibliothek)

Wie ein einzelner FluentUI-Baustein in eine bestehende Admin-Oberfläche kommt – ein Rezept je Baustein, ohne den Weg von Null noch einmal zu gehen.

Für wen: Entwickler, die bereits eine bestehende Admin-Oberfläche haben (eigenes Plugin oder wksqliteds als Vorbild) und einen einzelnen Baustein ergänzen wollen, ohne den vollständigen Tutorial-Weg von Null zu wiederholen. Jedes Rezept ist zielorientiert und kurz; Methodenverträge stehen ausschließlich in FluentUI: Öffentliche Helper-API – dieses Rezept wiederholt sie nicht, sondern verlinkt darauf.

Ziel: verstreute Buttons oberhalb einer Liste/eines Grids durch eine tastaturzugängliche Command-Bar ersetzen.

1. Helfer laden (falls noch nicht geschehen): $widgets = plugin_load('helper', 'wkfluentui_widgets');.
2. Jeden Button als fertiges HTML-Fragment bauen (eigene Farbsemantik, siehe Styles-Contract (--wk-*)).
3. Fragmente in $widgets→toolbar($items, $opts) einreichen; Buttons mit gleichem group-Wert werden nebeneinander mit Trennlinie gruppiert (z. B. group' => 'danger' für Lösch-Aktionen ganz rechts).
4. Ergebnis direkt oberhalb der Liste/des Grids ausgeben – keine eigene CSS-Klasse nötig, toolbar() liefert bereits role=„toolbar“ + Tastaturnavigation (scripts/toolbar.js).

Vollständiger Parametervertrag: toolbar → Grundlagen, Methode „toolbar()“. Live-Vorbild: Table-Designer-Toolbar in wksqliteds/dbadmin/DbAdmin.php.

Ziel: eine rechte Auxiliary-Bar, die die Eigenschaften der aktuellen Baum-/ Grid-Auswahl zeigt (ADS-Muster „Properties-Panel“).

1. Region <div class=„wk-shell-auxbar“> im .wkq-shell-Grid reservieren (siehe FluentUI: Basic Layout (vertieft) für die Grid-Komposition).
2. Auswahl über einen eigenen Query-Parameter transportieren (erster Wurf: Klick-Link, kein Live-JS – bewährte Konvention, nicht neu erfinden). Achtung Namenskollision: keinen Parameternamen wählen, der bereits von DokuWikis eigenem Routing verwendet wird (do/page sind reserviert für do=admin&page=<plugin>; wksqliteds selbst wurde von genau dieser Kollision getroffen, siehe unten).
3. Auswahl serverseitig auflösen (Datensatz nachladen) und als $widgets→propertyGrid($rows) rendern; Fallback-Text, wenn nichts ausgewählt ist oder der referenzierte Datensatz nicht mehr existiert.

Vollständiger Zeilen-Vertrag: property-grid → Grundlagen, Methode „propertyGrid()“. Live-Vorbild (zwei komplette Umsetzungen): wksqliteds/dbadmin/DbAdmin.php::renderStructureAuxbar()/ renderBrowseAuxbar().

Ziel: mehrere Unteransichten desselben Datensatzes/Bereichs als Tab-Leiste anbieten (z. B. Spalten/Indizes/Fremdschlüssel/Trigger eines Table-Designer-Screens, oder Ergebnis/Meldungen eines Abfrage-Ergebnisses).

1. Jede Registerkarte als ['key' => string, 'label' => string, 'href' => string] modellieren – href trägt den vollständigen Ziel-Link inkl. aller nötigen Query-Parameter.
2. Bereits per url()/wl() HTML-kodierte Links (& statt &) nicht erneut durch hsc() schicken – führt zu Doppel-Escaping und damit zu kaputten Links (in wksqliteds zweimal aufgetreten; beide Male Symptom: Klick landet auf der generischen Startseite statt auf dem erwarteten Tab). Etablierte Konvention: eine private xyzUrl($raw = false)- Wrapper-Methode wie DbAdmin::rtabUrl()/dselUrl(), die bei Bedarf $raw = true an url() durchreicht.
3. $widgets→tabs($tabs, $active) aufrufen; $active vergleicht per String-Gleichheit gegen key.

Vollständiger Parametervertrag: tabcontrol → Grundlagen, Methode „tabs()“. Live-Vorbild: Results/Messages-Tabs im SQL-Workbench, wksqliteds/dbadmin/DbAdmin.php::renderResultsMessagesTabs().

• Query-Parameter-Namenskollision mit dem Routing: do=admins eigenes Routing belegt page (Plugin-Name). Ein eigener Listen-/Grid-Parameter gleichen Namens wird von url()s array_merge() übernommen und überschreibt lautlos die Routing-Angabe – jeder generierte Link auf dem Screen kickt dann auf die generische Admin-Übersicht statt auf den erwarteten Zustand. Gefunden und behoben in wksqlitedss Browse-Paginierung (Parameter umbenannt page → bpage) – bei jedem neuen Query-Parameter vorab gegen DokuWikis reservierte Namen (do, page, id, rev, sectok) prüfen.
• CSS-Compiler-Fallen (sitewide fatal): min()/calc() mit gemischten Einheiten und die Zeichenfolge */ im Kommentartext brechen die site-weite CSS-Kompilierung – siehe einschraenkungen_und_troubleshooting.
• CodeMirror-Textareas in Playwright-Tests: page.fill() erreicht die zugrundeliegende <textarea> nicht mehr, sobald CodeMirror sie ersetzt hat – page.evaluate() mit ta.nextSibling.CodeMirror.setValue(…) verwenden.

• Vollständiger Von-Null-Weg: Tutorial: Erste Admin-Oberfläche mit FluentUI bauen.
• Normative Regeln für Admin-Oberflächen: FluentUI: Admin-Bereich (vertieft).
• Vollständige Methodenverträge: FluentUI: Öffentliche Helper-API.