FluentUI: Schema-gestützte Formular-Seiten
Zurück: FluentUI: Komponenten-Referenzen
1. Übersicht und Zweck
Status: [Live] — Umsetzung der
Initiative FluentUI: Zukünftige Richtung — Schema-gestützte Formular-Seiten als
Option (a), per Nutzer-Entscheid integriert in wkfluentui
(kein eigenes Plugin). Ein Seitentyp wird durch eine XML-Schema-Datei
definiert (Pflichtfelder, Typen, Auswahllisten); Anlage und Bearbeitung
laufen über ein generiertes Formular statt Freitext, gespeichert wird
eine reguläre DokuWiki-Seite, die als Formular-Chrome rendert.
Ideen-Vorbild ist Wdx' Page-Contract (Trennung Deklaration/Logik, erzwungene Feld-Validierung) — gemäß der Entscheidung auf FluentUI: Zukünftige Richtung — Wdx als Inspirationsquelle ausschließlich als Inspiration, ohne Laufzeit-Abhängigkeit.
2. Voraussetzungen
Plugin wkfluentui aktiv; für die Anlage AUTH_CREATE, für die
Bearbeitung AUTH_EDIT auf der Zielseite (DokuWiki-ACL).
3. Konzepte
Drei Komponenten, ein Datenfluss:
helper/formpage.php— Schema-Loader (schemas/<typ>.xml), serverseitige Validierung, Serialisierung/Parsen des Seiten-Blocks, Formular-Rendering.action/formpage.php— die zwei Aktionendo=wkformpage_new&fptype=<typ>(Anlage, Seite darf nicht existieren) unddo=wkformpage_edit(Bearbeitung; der Typ kommt aus der gespeicherten Seite, nie aus dem Request).syntax/formpage.php— rendert den gespeicherten<wkform type="...">-Block als Formular-Chrome (Definitionsliste in Schema-Reihenfolge, Bearbeiten-Button nur beiAUTH_EDIT). Dies ist die erste Syntax-Komponente der Bibliothek; das Markup schreibt ausschließlich der eigene Speicher-Fluss, Autoren schreiben es nicht von Hand.
Speicherformat: generierte Überschrift (Seitentitel = Wert des ersten Pflicht-Textfelds, Fallback Schematitel) plus ein Block mit den Werten als JSON. Die Seite bleibt eine normale Wiki-Seite: der Roh-Editor bleibt als Fallback nutzbar, und bei deaktiviertem Plugin bleibt das JSON als lesbarer Seitentext erhalten (dokumentierte Degradation).
4. Erste Schritte
Anlage einer BUG-WI-Seite (Beispielschema schemas/bug-wi.xml):
doku.php?id=projekt:bugs:export-500&do=wkformpage_new&fptype=bug-wi
Das Formular rendert die neun Schema-Felder mit dem Feld-Basiskontrakt (Eingabefelder: Grundlagen); Speichern validiert serverseitig, legt die Seite an und leitet auf die gerenderte Ansicht weiter.
5. Verwendung
| Bedarf | Weg |
|---|---|
| Neuen Seitentyp definieren | XML-Datei unter lib/plugins/wkfluentui/schemas/<typ>.xml (Schema-Vertrag: Abschnitt 7) |
| Seite anlegen | Link auf do=wkformpage_new&fptype=<typ> (z. B. aus einer Portal-Seite oder einem Snippet) |
| Seite bearbeiten | Bearbeiten-Button im Chrome-Kopf oder do=wkformpage_edit |
| Rohtext bearbeiten | normaler Wiki-Editor (do=edit) — bleibt unverändert möglich |
6. API-Referenz
helper_plugin_wkfluentui_formpage — laden per
plugin_load('helper', 'wkfluentui_formpage'):
| Methode | Vertrag |
|---|---|
loadSchema($type) | Schema-Array oder null (unbekannter/kaputter Typ); Typname allowlist-validiert vor dem Dateizugriff (CWE-22) |
validate($schema, $input) | ['values' => normalisiert, 'errors' => feld => meldungsschlüssel] — unabhängig vom Client (Pflicht, Auswahlwerte, Datumsformat, Array-Injection) |
serialize($schema, $values) | vollständiger Wiki-Seitentext (Überschrift + Block) |
parse($text) | ['type', 'values'] oder null |
formFields($schema, $values, $errors) | Formularfelder-HTML (.wk-field-Vertrag), ohne <form>-Hülle |
7. Parameter, Optionen und Zustände: Schema-Vertrag
| XML | Bedeutung |
|---|---|
<schema title="..."> | Anzeigename des Typs (Chrome-Badge, Fallback-Seitentitel) |
<field name= type= required= label= hint= rows=> | ein Feld; name = [a-z0-9_]{1,64} (wird Formularname und JSON-Schlüssel) |
type | text · textarea · select · date · checkbox — unbekannte Typen machen das ganze Schema ungültig (fail-closed) |
<option> | Auswahlwerte eines select; eingereichte Werte müssen exakt einem Eintrag entsprechen |
8. Vollständige Beispiele
Das Beispielschema bug-wi (mitgeliefert): Titel (Pflicht), Schweregrad
(Select, Pflicht), System/Umgebung, Gefunden am (Datum), Repro-Schritte /
Erwartet / Ist (Pflicht-Textareas), Akzeptanzkriterien,
Regression-Checkbox.
9. Einschränkungen und Randfälle
- Bewusste v1-Grenzen: keine Seitensperren-Integration (letzter Speichernder gewinnt — wie bei jedem externen Editor) und keine Draft-Integration; der Roh-Editor ist für beides der Fallback-Pfad.
- Die Anlage verweigert existierende Zielseiten (kein stilles Überschreiben fremden Inhalts).
- Checkboxen posten explizit
0/1(Hidden-Feld-Muster) — ein fehlender Wert ist nie mehrdeutig.
10. Accessibility und Kompatibilität
Formularfelder folgen dem Feld-Basiskontrakt (label[for],
aria-required, aria-invalid + aria-describedby auf die
Fehlermeldung, Pflicht-Stern mit Screenreader-Text). Ohne JavaScript ist
der gesamte Fluss voll funktionsfähig (reines Formular-POST-Muster);
Browser-required ist Komfort, die Server-Validierung ist die
Grenze.
11. Troubleshooting
Symptom: „Unbekannter oder fehlerhafter Seitentyp„.
Ursache: Typname nicht im Allowlist-Format, Schema-Datei fehlt, XML
kaputt, unbekannter Feldtyp oder select ohne Optionen (fail-closed).
Lösung: Schema gegen den Vertrag in Abschnitt 7 prüfen.
Symptom: Chrome zeigt Fehlerbox + JSON-Codeblock. Ursache: der gespeicherte Block verweist auf einen entfernten/ umbenannten Typ — Inhalte werden lesbar gezeigt statt versteckt.
12. Verwandte Themen
- FluentUI: Zukünftige Richtung — Schema-gestützte Formular-Seiten — Entscheidungsgrundlage und Optionsvergleich (historisch)
- FluentUI: Zukünftige Richtung — Wdx als Inspirationsquelle — Ideen-Vorbild Page-Contract, Nicht-Integrations-Entscheidung
- Eingabefelder: Grundlagen — Feld-Basiskontrakt
- FluentUI: Öffentliche Helper-API — Helper-Verzeichnis
Verifiziert gegen: wkfluentui@1366902