DataGrid: Grundlagen

Der zentrale Baustein für viele gleichartige Datensätze: eine panel-füllende, umbruchfeste Tabelle mit Sortierung, Zeilenauswahl und Massenaktionen.

dataGrid() zeichnet aus Spalten und Zeilen eine Tabelle, die ihre Fläche füllt: der Spaltenkopf bleibt stehen, nur die Datenzeilen rollen. Diese Seite beschreibt den Grundkontrakt – Spalten, Zeilen, Spaltenfolge und Breiten.

Zurück: Demo-Übersicht

Status: [Live].

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).

Die Spalten stehen in dieser Reihenfolge, damit jede Liste des Hauses gleich gelesen wird:

1. Aufklapper (inspector), falls vorhanden
2. Auswahl-Kästchen (selection => 'multi')
3. Primärspalte – das Feld, das die Zeile benennt (primary, Standard: erste Spalte)
4. Zeilenmenü (rowMenu) – das Kebab steht hinter dem Namen, zu dem es gehört
5. die Fachspalten

Die Kopfzeile ist eine Zeile. Eine Datenzelle kürzt (max-width: 0 plus text-overflow), die Spaltenbreite bestimmt damit die Kopfzelle – und die bricht nicht um. Passen die Spalten nicht nebeneinander, nimmt die Tabelle ihre natürliche Breite und der Rest läuft waagerecht; Kopf und Daten bewegen sich dabei gemeinsam, weil beide im selben Kasten liegen. Ohne diese Regel verteilt der Browser die vorhandene Breite und setzt die Überschriften bei genug Spalten Buchstabe für Buchstabe untereinander – gemessen bei 37 Spalten: 270 px Kopfzeile gegenüber 28 px heute.

Wer eine Spalte schmaler zieht, sieht eine gekürzte Überschrift mit title – dieselbe Zusage wie in der Datenzelle.

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 (Katalog der Stufe 2)
• SQLite Data Studio: Admin-Oberfläche – Erstkonsument (SQL-Workbench)