DataGrid: Grundlagen

Zurück: Demo-Übersicht

Status: [Live], verifiziert gegen wkfluentui@a477094.

dataGrid() rendert eine panel-füllende, resize-feste Desktop-Tabelle mit optionaler Sortierung, Zeilenauswahl und Massenaktionen — der zentrale Baustein für „viele gleichartige Datensätze als Tabelle„ in dieser Bibliothek. Diese Seite dokumentiert den Basiskontrakt (Spalten, Zeilen, erzeugtes Markup, Tabellen-Optik, Spaltenbreiten-Persistenz); feature- spezifische Details (Sortierung, Selection, Massenaktionen, Filtering, Paging, Export, Accessibility) stehen auf den jeweiligen Unterseiten der Demo-Übersicht.

Zielgruppe: jedes DokuWiki-Plugin, das eine Liste gleichartiger Datensätze (Datenbank-Zeilen, Dateiliste, Konfigurationseinträge …) als Tabelle zeigen will, statt eine eigene Table-Rendering-Logik zu bauen.

• DokuWiki mit aktiviertem Plugin wkfluentui.
• helper_plugin_wkfluentui_widgets geladen über plugin_load('helper', 'wkfluentui_widgets') — nicht plugin_load('helper', 'wkfluentui') (liefert null, s. api → Abschnitt „Troubleshooting").
• Für sortUrl/bulkActions mit Server-Endpunkten: ein Formular-POST-Handler mit sectok-Prüfung auf Aufrufer-Seite (das Widget liefert nur Markup, keine Server-Logik).

Ein natives <table>, keine div-Nachbildung. Bewusste Architekturentscheidung: getrennte Head-/Body-Tabellen oder ein div-Raster desynchronisieren Spaltenbreiten ohne JavaScript; ein natives <table> hält Kopf und Body ausgerichtet und trägt korrekte implizite Tabellensemantik kostenlos. role=„grid“ (plus aria-multiselectable bei multi) wird nur gesetzt, sobald ein Auswahlmodell aktiv ist — eine reine Anzeige-Tabelle ohne Auswahl bleibt semantisch eine Tabelle, kein „Grid“-Widget.

Klartext vs. vertrauenswürdiges HTML: $rows-Zellwerte sind standardmäßig Klartext (hsc()-escaped durch das Widget); ein Wert der Form ['html' => string] rendert stattdessen unverändertes, bereits vom Aufrufer escaptes HTML — dieselbe Konvention wie überall in dieser API (s. api → Abschnitt „Konzepte", Escaping-Konvention).

Container-getriebenes Responsive: kein Viewport-Breakpoint, das Grid folgt der Breite seines Panels — Details: Adaptivity.

/** @var helper_plugin_wkfluentui_widgets $widgets */
$widgets = plugin_load('helper', 'wkfluentui_widgets');
 
$columns = [
    ['key' => 'id',     'label' => 'ID',     'align' => 'right', 'mono' => true, 'width' => '4rem'],
    ['key' => 'name',   'label' => 'Name'],
    ['key' => 'status', 'label' => 'Status', 'sortable' => false],
];
 
$rows = [
    ['id' => 1, 'name' => 'Firewall-Regel prüfen', 'status' => 'offen'],
    ['id' => 2, 'name' => 'Backup-Job verifizieren', 'status' => 'erledigt'],
];
 
echo $widgets->dataGrid($columns, $rows, [
    'ariaLabel' => 'Aufgabenliste',
    'empty'     => 'Keine Einträge.',
]);

Falsch: $rows als reines Werte-Array ohne Spalten-Keys übergeben ([1, 'Firewall-Regel prüfen', 'offen']). dataGrid() liest Zellwerte über $row[$col['key']] — ohne passende Keys bleiben alle Zellen leer, es gibt keine Fehlermeldung (s. Abschnitt 11, Troubleshooting).

public function dataGrid(array $columns, array $rows, array $opts = []): string

Zusammenfassung: Rendert eine Desktop-Datentabelle aus Spalten- Definitionen und Zeilen-Daten, optional mit Sortierung, Zeilenauswahl und Massenaktionen-Toolbar.

Rückgabewert: string — vollständiges HTML-Fragment (<div class="wk-datagrid">…</div>). Leerer String, wenn $columns leer ist (keine Tabelle ohne Spalten) — unabhängig davon, ob $rows Einträge enthält.

Liste von Assoziativ-Arrays key => Zellwert. Ein String wird als Klartext escaped; ['html' => string] rendert vertrauenswürdiges, Aufrufer-escaptes HTML ungeprüft.

<div class="wk-datagrid" data-wk-selection="…" data-wk-persist="…"> → optional <div class="wk-datagrid__bulkbar"> → ein natives <div class="wk-datagrid__body"><table>…</table></div> mit sticky <thead class="wk-datagrid__head">. Jede Kopfzelle trägt scope="col" (explizite Spaltenkopf-Semantik — konsistent zur Entscheidung, native Tabellensemantik statt eines ARIA-Nachbaus zu nutzen, s. Abschnitt 3).

Sortierbare, mehrfach auswählbare Tabelle mit Massenaktion (kombiniert Grundlagen + Sorting + Selection + Bulk-Actions):

$columns = [
    ['key' => 'id', 'label' => 'ID', 'align' => 'right', 'mono' => true, 'width' => '4rem'],
    ['key' => 'name', 'label' => 'Name'],
    ['key' => 'status', 'label' => 'Status'],
];
 
echo $widgets->dataGrid($columns, $rows, [
    'sort'        => ['name', 'asc'],
    'persistKey'  => 'aufgaben:liste',
    'selection'   => 'multi',
    'rowKey'      => 'id',
    'bulkActions' => [
        ['label' => 'Erledigt markieren', 'element' =>
            '<button type="submit" name="do" value="done" class="wk-btn">Erledigt markieren</button>'],
    ],
    'ariaLabel' => 'Aufgabenliste',
    'empty'     => 'Keine Aufgaben.',
]);

• Kein virtuelles Scrollen — siehe Data Paging and Scrolling.
• Keine editierbaren Zellen in dieser Ausbaustufe — siehe Data Editing (Massenaktionen), Abschnitt Grid-Editing.
• Kein Spalten-Header-Filter — siehe Filtering.
• Keine Mehrspalten-Sortierung — siehe Sorting → Einschränkungen.
• persistKey muss über Seitenaufrufe hinweg stabil und pro Grid-Instanz eindeutig sein — zwei Grids mit demselben persistKey teilen sich versehentlich denselben localStorage-Zustand.

• Vollständiger ARIA-/Tastatur-Überblick: Accessibility (konsolidiert, nicht hier dupliziert).
• Ohne JavaScript bleibt die Tabelle vollständig nutzbar; Sortierung erfordert bei No-JS sortUrl (serverseitiger Fallback), sonst bleiben Kopfzeilen unsortierbar-still.
• Browserkompatibilität: keine Anforderungen über CSS-Grid/Flexbox-Grundunterstützung hinaus (identisch zum Rest der Bibliothek).

Symptom: Zellen bleiben leer, obwohl $rows Daten enthält.

Ursache: $rows-Zeilenschlüssel stimmen nicht mit $columns[]['key'] überein (Tippfehler oder reines Werte-Array statt Assoziativ-Array).

Lösung: jeden $columns[]['key'] gegen die tatsächlichen array_keys() einer $rows-Zeile prüfen.

Symptom: Checkbox-Spalte fehlt trotz selection => 'multi'.

Ursache: rowKey fehlt in $opts — das Widget degradiert still auf none (s. Abschnitt 7, Fehlerverhalten).

Lösung: $opts['rowKey'] auf einen eindeutigen Spalten-Key setzen.

• Demo-Übersicht — alle Kategorien
• FluentUI: Öffentliche Helper-API — vollständiger Methodenvertrag aller Helper
• FluentUI: Basis-Widget-Katalog — DeclarativeTable (Tier-2-Katalog)
• SQLite Data Studio: Admin-Oberfläche — Erstkonsument (SQL-Workbench)