Vertical Grid: Grundlagen

Zurück: Demo-Übersicht

Status: vollständig [Live] — Grundraster, Gruppen/Sektionen, Readonly-Modus, Validierungszustand und required-Kennzeichnung sind umgesetzt (Quelle: lib/plugins/wkfluentui/helper/widgets.php, Methode propertyGrid()).

propertyGrid() stellt ein Objekt als zweispaltiges Label/Wert-Raster dar — Attribute als Zeilen, nicht als Spalten (Gegenstück zu dataGrid(), das viele Objekte als Zeilen zeigt). Zielgruppe: jedes Formular oder jeder Eigenschaften-Inspektor, der Label+Control-Paare braucht, ohne eine eigene Formular-Grid-CSS zu bauen.

• DokuWiki mit aktiviertem Plugin wkfluentui.
• helper_plugin_wkfluentui_widgets geladen über plugin_load('helper', 'wkfluentui_widgets').
• Controls (controlHtml) liefert der Aufrufer selbst — propertyGrid() rendert kein einziges Eingabefeld, nur den Rahmen darum (s. Eingabefelder für passende Control-Bausteine).

Zwei Rollen, ein Baustein: Formular-Raster (Eingabefelder mit Label-Spalte) und Eigenschaften-Inspektor (kontextsensitive Anzeige des ausgewählten Objekts, typisch in der Auxbar) nutzen dieselbe Methode — der Unterschied liegt nur in $opts['mode'] (Abschnitt 7).

Klartext vs. vertrauenswürdiges HTML: label wird per hsc() escaped; controlHtml ist bereits vom Aufrufer erzeugtes, vertrauenswürdiges HTML — dieselbe Konvention wie überall in dieser API (s. api → Abschnitt „Konzepte").

Rückwärtskompatibilität: propertyGrid($rows) ohne die später ergänzten Schlüssel (section/value/state/required) rendert byte-identisch zur ursprünglichen Ein-Parameter-Version.

/** @var helper_plugin_wkfluentui_widgets $widgets */
$widgets = plugin_load('helper', 'wkfluentui_widgets');
 
echo $widgets->propertyGrid([
    ['label' => 'Name', 'controlHtml' => '<input type="text" name="name" required>'],
    ['label' => 'Aktiv', 'controlHtml' => '<input type="checkbox" name="aktiv">'],
]);

Falsch: rohen Nutzereingabe-Text direkt als controlHtml übergeben ('controlHtml' => $_POST['x']). controlHtml wird ungeprüft ausgegeben — der Aufrufer trägt hier die volle XSS-Verantwortung (CWE-79).

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

Zusammenfassung: Rendert ein zweispaltiges Label/Control-Formularraster (CSS-Grid fit-content(22rem) minmax(0, 1fr)) aus Zeilen-Definitionen, optional gruppiert in kollabierbare Sektionen und/oder im Readonly-Anzeigemodus.

Rückgabewert: string — vollständiges HTML-Fragment (<div class="wk-property-grid">…</div>). Leerer String bei leerem $rows.

Zeilen mit gleichem section-Wert werden unter einer Sektions-Kopfzeile (volle Breite, halbfett mit dünnem Trenner — Optik der Fieldset-Legenden aus _admin-forms.css) gruppiert; die Kopfzeile ist per Klick/Enter kollabierbar (<details>-basiert, ohne JavaScript funktionsfähig). Zeilen ohne section rendern vor der ersten Sektion. Referenz: DevExpress-VerticalGrid-Kategorien, ADS Table-Designer-Gruppen.

propertyGrid($rows, ['mode' => 'display']): Zeilen ohne controlHtml akzeptieren value (Abschnitt oben); der Container trägt .wk-property-grid--display (kein Eingabe-Chrome, Werte selektierbar, Zeilen-Hover über --wk-admin-hover). Das ist der Standard für den Eigenschaften-Inspektor — Formular-Optik nur, wo tatsächlich editiert wird.

Formular mit zwei Sektionen, einer Pflichtfeld-Validierung und Persistenz des Sektions-Zustands:

echo $widgets->propertyGrid([
    ['section' => 'Verbindung', 'label' => 'Host', 'controlHtml' => '<input type="text" name="host" required>', 'required' => true],
    ['section' => 'Verbindung', 'label' => 'Port', 'controlHtml' => '<input type="number" name="port" value="3306">'],
    ['section' => 'Zugangsdaten', 'label' => 'Benutzer', 'controlHtml' => '<input type="text" name="user">'],
    ['section' => 'Zugangsdaten', 'label' => 'Passwort', 'controlHtml' => '<input type="password" name="pass">', 'state' => 'warning', 'stateText' => 'Wird verschlüsselt gespeichert.'],
], ['persistKey' => 'connect-dialog']);

• Kein Nachbau des DevExpress-Mehr-Datensatz-Vergleichsmodus (mehrere Objekte als Spalten) — bei Bedarf eigenständige Initiative; bis dahin: ein propertyGrid() je Objekt nebeneinander.
• Panel-Füll-Verhalten (Grid füllt Drawer/Auxbar, scrollt innen) — Details: Adaptivity.
• aria-describedby zwischen stateText und Control entsteht nur mit gesetztem controlId-Zeilen-Schlüssel (s. Abschnitt 7) — Alt-Aufrufer ohne den Schlüssel rendern unverändert; Details: Accessibility.

• Vollständiger Überblick: Accessibility (konsolidiert, nicht hier dupliziert).
• Ohne JavaScript bleiben alle Sektionen offen bedienbar (native <details>-Semantik); nur die Persistenz des Offen-Zustands über Reloads entfällt.
• Browserkompatibilität: keine Anforderungen über CSS-Grid-Grundunterstützung hinaus.

Symptom: Pflichtfeld zeigt kein rotes Sternchen trotz required ⇒ true.

Ursache: required in der Zeilen-Definition und required als HTML-Attribut im controlHtml sind zwei getrennte Dinge — nur ersteres steuert das Sternchen.

Lösung: 'required' => true in der Zeile setzen und das required-Attribut selbst im controlHtml ergänzen, wenn native Browser-Validierung gewünscht ist.

Symptom: Sektions-Offen-Zustand geht bei jedem Seitenaufruf verloren.

Ursache: $opts['persistKey'] fehlt.

Lösung: einen über Seitenaufrufe stabilen, pro Formular eindeutigen persistKey setzen.

• Demo-Übersicht — alle Kategorien
• FluentUI: Öffentliche Helper-API — vollständiger Methodenvertrag
• FluentUI: Basis-Widget-Katalog — FormLayout-Einordnung (ADS)
• form-fields — Eingabefelder für controlHtml
• Tutorial: Erste Admin-Oberfläche mit FluentUI bauen — Schrittanleitung
• FluentUI: Admin-Bereich (vertieft) — Formularmetrik/Farbsemantik