Toolbar: Grundlagen

1. Übersicht und Zweck

Status: [Live]. Quelle: lib/plugins/wkfluentui/helper/widgets.php, Methode toolbar() (Zeile 603).

toolbar() umschließt bereits vom Aufrufer gebautes Button-/Link-/ Select-HTML mit role=„toolbar“ und optionaler Gruppierung. Zielgruppe: jede Aktionsleiste (Modul-Command-Bar, Grid-Bulkbar, Formular-Buttons), die WAI-ARIA-konforme Tastaturnavigation ohne eigenen JavaScript-Code braucht.

2. Voraussetzungen

DokuWiki mit aktiviertem Plugin wkfluentui.
helper_plugin_wkfluentui_widgets geladen über plugin_load('helper', 'wkfluentui_widgets').
Die eigentlichen Buttons/Links liefert der Aufrufer fertig gerendert — toolbar() rendert selbst keine Controls.

3. Konzepte

Umschließende Semantik, kein Control-Rendering: toolbar() rendert nur den role=„toolbar“-Rahmen und die Gruppierung; jedes element ist bereits vom Aufrufer erzeugtes, vertrauenswürdiges HTML (dieselbe Konvention wie rowActions(), s. api → Abschnitt „Konzepte").

Fallback ist Live-Code, kein Downgrade: das nackte <div class="wkq-bt wk-toolbar">-Markup, das in wksqliteds bereits produktiv war, ist der No-JS-Fallback — toolbar() ergänzt nur role=„toolbar“ plus (progressiv) Tastaturnavigation, keine neue Markup-Grundform.

4. Erste Schritte

/** @var helper_plugin_wkfluentui_widgets $widgets */
$widgets = plugin_load('helper', 'wkfluentui_widgets');
 
echo $widgets->toolbar([
    ['label' => 'Neu',    'element' => '<button type="submit" name="do" value="new">Neu</button>', 'group' => 'main'],
    ['label' => 'Öffnen', 'element' => '<button type="submit" name="do" value="open">Öffnen</button>', 'group' => 'main'],
    ['label' => 'Löschen', 'element' => '<button type="submit" name="do" value="delete" class="wk-btn--danger">Löschen</button>', 'group' => 'danger'],
], ['ariaLabel' => 'Tabellen-Aktionen']);

Falsch: element als reinen Text statt fertiges HTML übergeben ('element' => 'Neu'). toolbar() escaped element nicht — ein Text ohne umschließendes Button-/Link-Tag rendert unsichtbar/nicht fokussierbar, statt als Aktion zu erscheinen.

5. Verwendung

Einsatz	Muster
Modulweite Command-Bar	`toolbar()` in der Command-Bar-Region — admin-layout → „Command-Bar als Shell-Region"
Grid-Auswahl-Toolbar (Bulkbar)	intern von `dataGrid()` aufgerufen — Data Editing (Massenaktionen)
Gruppierte Aktionen (weiß→blau→rot)	`group`-Werte in Reihenfolge der Contract-v3-Farbsemantik — Styles-Contract (--wk-*)

6. API-Referenz

Metadatum	Wert
Sprache	PHP
Namespace	`helper_plugin_wkfluentui_widgets`
Datei	`lib/plugins/wkfluentui/helper/widgets.php`
Sichtbarkeit	public
Stabilität	stabil (Tier 1)

public function toolbar(array $items, array $opts = []): string

Zusammenfassung: Umschließt Aufrufer-HTML mit <div role="toolbar"> und optionaler Gruppierung.

Rückgabewert: string. Leerer String bei leerem $items.

7. Parameter, Optionen und Zustände

Schlüssel	Typ	Pflicht	Bedeutung
`$items[]['label']`	string	Ja	nur für Kontext, nicht selbst gerendert — das sichtbare Label steckt im `element`
`$items[]['element']`	string	Ja	vertrauenswürdiges, vom Aufrufer bereits gebautes HTML — Aufrufer-escaped
`$items[]['group']`	string	Nein	Items mit gleichem Wert rendern zusammen in einer Gruppe; wechselnde Werte öffnen automatisch eine neue Gruppe
`$opts['ariaLabel']`	string	Nein	Beschriftung der gesamten Toolbar, Default `„Toolbar“`

Erzeugtes Markup

<div class="wk-toolbar" role="toolbar" aria-label="…"> → Items ohne group direkt als Kinder, Items mit group innerhalb eines <div class="wk-toolbar__group">.

Fehlerverhalten

Bedingung	Verhalten
`$items` leer	Rückgabe leerer String, kein Fehler
`element` ohne gültiges HTML-Tag	wird unverändert ausgegeben — kein Fehler, aber funktional nicht fokussierbar (s. Abschnitt 4, „Falsch„)

8. Vollständige Beispiele

echo $widgets->toolbar([
    ['label' => 'Export', 'element' => '<button type="submit" name="do" value="export" class="wk-btn--accent">Export</button>', 'group' => 'aktionen'],
    ['label' => 'Aktualisieren', 'element' => '<button type="submit" name="do" value="refresh">Aktualisieren</button>', 'group' => 'aktionen'],
], ['ariaLabel' => 'Modul-Aktionen']);

9. Einschränkungen und Randfälle

Overflow-Verhalten ist Opt-in über $opts['overflow'] — Details: Adaptivity.
Ribbon-Gruppen-Titel/Galerie-Größenvarianten über groupLabel/size/ribbonStyle — Details: Ribbon-Gruppen/Galerie.

10. Accessibility und Kompatibilität

Vollständiger Überblick: Accessibility (konsolidiert, nicht hier dupliziert).
Ohne JavaScript bleibt jede Aktion ein normal per Tab erreichbares Element — das WAI-ARIA-Roving-Tabindex-Muster ist reine Progressive Enhancement.

11. Troubleshooting

Symptom: Pfeiltasten-Navigation zwischen Toolbar-Items funktioniert nicht.

Ursache: scripts/toolbar.js wurde nicht geladen (z. B. weil der kanonische Ladeweg über script.js fehlt) oder die Toolbar hat weniger als zwei fokussierbare Kinder — das Skript aktiviert Roving-Tabindex nur ab zwei Elementen.

Lösung: Skript-Ladeweg prüfen (DOKUWIKI:include-Direktive in script.js, s. api → Abschnitt „Konzepte"); bei nur einem Item ist die fehlende Pfeiltasten-Navigation kein Bug — Tab erreicht das einzige Element ohnehin direkt.

12. Verwandte Themen

Demo-Übersicht — alle Kategorien
FluentUI: Öffentliche Helper-API — vollständiger Methodenvertrag
DataGrid: Data Editing (Massenaktionen) — Live-Konsument (Bulkbar)
Styles-Contract (--wk-*) — Farbsemantik der group-Reihenfolge