Tutorial: Erste Admin-Oberfläche mit FluentUI bauen

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

Für wen: Entwickler, die noch kein Vorwissen über wkfluentui haben und ein eigenes DokuWiki-Admin-Modul (AdminPlugin) im Fluent-/ADS-Stil bauen wollen. Dieses Tutorial führt von Null zu einer funktionierenden Liste-Screen und einer Mehr-Regionen-Oberfläche — Schritt für Schritt, mit einem laufenden Beispiel. Es wiederholt keine Methodenverträge; jeder Schritt verlinkt auf die Helper-API-Referenz für Details.

Referenzbeispiel: Die Screens do=admin&page=wksqliteds (Plugin wksqliteds) sind die live umgesetzte Langfassung jedes Schritts hier — Bereich „Verbindungen„ (admin.php::renderConnList()) für Schritt 1–2, Bereich „Datenbank“ → Table Designer/Browse (dbadmin/DbAdmin.php::renderStructure()/ renderBrowse()) für Schritt 3–5. Quellcode: lib/plugins/wksqliteds/{admin.php, dbadmin/DbAdmin.php}.

Das eigene Plugin lädt den wkfluentui-Helfer wie jeden anderen DokuWiki-Helper:

/** @var helper_plugin_wkfluentui_widgets $widgets */
$widgets = plugin_load('helper', 'wkfluentui_widgets');

Kein Konstruktor-Argument, keine Konfiguration nötig — jede Methode ist eine reine Funktion ihrer Argumente (siehe FluentUI: Öffentliche Helper-API, Abschnitt „Eigenschaften„). CSS/JS lädt automatisch site-weit über lib/exe/css.php/lib/exe/js.php (siehe kernbegriffe) — kein manuelles Einbinden nötig.

Der einfachste Archetyp: eine Liste ohne Baum/Auxbar, gerahmt von .wkq-shell–flat (Modifikator-Klasse, kein eigener Helper-Aufruf — siehe FluentUI: Basic Layout (vertieft) für die vollständige Modifikator-Tabelle) und der Statusleiste unten:

echo '<div class="wkq-shell wkq-shell--flat">';
echo '<div class="wk-shell-content">';
 
echo '<h2>Meine Liste</h2>';
echo '<table class="inline" style="width:100%">…</table>';
 
echo '</div>'; // wk-shell-content
echo '<div class="wk-shell-statusbar"><span>3 Einträge</span><span></span></div>';
echo '</div>'; // wkq-shell

Live-Vorbild: wksqliteds/admin.php::renderConnList() (Bereich „Verbindungen“). Die Statusleiste ist hier ein reiner Zwei-<span>-Streifen ohne eigenen Helfer — bei mehreren Screens im selben Plugin lohnt sich eine private renderStatusbar($summary)-Methode wie dort, aber das ist Konvention, kein Pflicht-Baustein.

Verstreute Buttons durch toolbar() ersetzen — bringt role=„toolbar“ und Tastatur-Roving-Tabindex (scripts/toolbar.js) automatisch mit, ohne eigenes JS:

echo $widgets->toolbar([
    ['label' => 'Neu',     'element' => $widgets->button(
        ['label' => 'Neu', 'href' => '…', 'tone' => 'primary'])],
    ['label' => 'Löschen', 'element' => $widgets->button(
        ['label' => 'Löschen', 'type' => 'submit', 'tone' => 'danger']),
     'group' => 'danger'],
]);

Vollständiger Parametervertrag ($opts['ariaLabel'], Gruppierungsregeln, Beispiel mit drei Farbgruppen): toolbar → Grundlagen, Methode „toolbar()". Button-Farbsemantik (weiß/blau/rot): Styles-Contract (--wk-*).

Sobald der Screen eine Navigationsstruktur links und eine Arbeitsfläche rechts braucht, wechselt die Grid-Komposition von –flat zur vollen Vier-Regionen-Form (.wkq-shell ohne Modifikator bzw. mit –no-auxbar, siehe FluentUI: Basic Layout (vertieft)):

echo '<div class="wkq-shell">';
echo '<div class="wk-shell-sidebar">';
echo $widgets->tree([
    ['label' => 'connA', 'href' => '…', 'active' => true, 'children' => [
        ['label' => 'tabelle1', 'href' => '…'],
    ]],
]);
echo '</div>'; // wk-shell-sidebar
echo '<div class="wk-shell-content">…Arbeitsfläche…</div>';
echo '<div class="wk-shell-auxbar">…Eigenschaften…</div>';
echo '<div class="wk-shell-statusbar">…</div>';
echo '</div>'; // wkq-shell

tree() baut verschachtelbare <details>/<summary>-Knoten — komplett ohne JavaScript navigierbar (Tastatur/Screenreader eingeschlossen). Vollständiger Knoten-Datenvertrag (label/href/active/children): treeview → Grundlagen, Methode „tree()". Live-Vorbild: wksqliteds/dbadmin/DbAdmin.php::renderObjectTree() — ein einziger, über alle Datenbank-Screens geteilter Baum-Partial.

Die wk-shell-auxbar-Region aus Schritt 3 ist bewusst leer, bis der Screen eine Auswahl hat, die sie füllt. Das Muster erster Wurf (kein Live-JS nötig): ein Klick-Link setzt einen Auswahl-Parameter, der Screen liest ihn beim nächsten Rendern und füllt die Auxbar mit propertyGrid():

$sel = $INPUT->str('sel'); // z.B. "spalte1"
echo '<div class="wk-shell-auxbar">';
if ($sel !== '') {
    echo $widgets->propertyGrid([
        ['label' => 'Name', 'controlHtml' => '<code>' . hsc($sel) . '

'],

      ['label' => 'Typ',  'controlHtml' => 'TEXT'],
  ]);

} else {

  echo '<p style="color:#666">Auswahl treffen, um Eigenschaften zu sehen.</p>';

} echo '</div>'; </code>

Vollständiger Zeilen-Vertrag (label/controlHtml): property-grid → Grundlagen, Methode „propertyGrid()". Live-Vorbild (zwei komplette Umsetzungen, Spalten-/Index-/FK-Auswahl bzw. Zeilen-Auswahl): wksqliteds/dbadmin/DbAdmin.php::renderStructureAuxbar()/ renderBrowseAuxbar(). Ein Live-JS-Nachfolger ohne Seiten-Neuladen (ADS' onActiveCellChanged-Äquivalent) ist als Tier-2-Zielbild vorgemerkt, siehe FluentUI: Basis-Widget-Katalog.

Auf Mehr-Regionen-Screens zeigt die Statusleiste üblich den aktiven Kontext (Verbindungsname, Readonly-Hinweis) statt einer reinen Zählung wie in Schritt 1:

echo '<div class="wk-shell-statusbar">';
echo '<span>' . hsc($connName) . '</span>';
echo '<span>' . ($readonly ? 'Nur Lesen' : '') . '</span>';
echo '</div>';

Live-Vorbild: wksqliteds/dbadmin/DbAdmin.php::renderStatusbar(), inkl. der .wkq-statusbar-readonly-Modifikatorklasse für den Hinweis.

• Rezepte für einzelne Bausteine (statt des vollständigen Wegs oben): How-to: Einzelne Bausteine ergänzen.
• Normative Regeln für Admin-Oberflächen (Modul-Enumeration, Farbsemantik, Drawer-Konvention): FluentUI: Admin-Bereich (vertieft).
• Vollständige Methodenverträge: FluentUI: Öffentliche Helper-API.
• Design-Tokens (Farbe/Radius/Spacing): FluentUI: Design-Tokens.

Verifiziert gegen: wkfluentui@a477094, wk-dw-msqlite-plugin@240c064