====== DokuWiki – Formulare erstellen und verwalten ======

===== 1. Zweck =====

Mit dem Bureaucracy-Plugin können in DokuWiki Eingabeformulare erstellt werden.

Diese Formulare ermöglichen es, neue Wiki-Seiten nach einer einheitlichen Struktur anzulegen.

Das Plugin BureaucracyToolbar ergänzt die Formulare um eine Werkzeugleiste zur Eingabe von DokuWiki-Formatierungen.

Dieses Handbuch beschreibt die Einrichtung, Verwendung und Verwaltung solcher Formulare in RoWaWiki (RWW).

===== 2. Grundprinzip =====

Die Erstellung einer neuen Seite erfolgt über drei voneinander getrennte Bestandteile:

  - **Formular:** Erfasst die benötigten Informationen.
  - **Seitenvorlage:** Definiert den Aufbau der neuen Seite.
  - **Zielseite:** Enthält die aus Formular und Vorlage erzeugten Informationen.

Die drei Bestandteile können in unterschiedlichen Namensräumen liegen.

===== 3. Namensräume in RoWaWiki =====

Für RoWaWiki gelten folgende zentrale Namensräume:

^ Namensraum ^ Aufgabe ^
| ''formulare:'' | Zentrale Verwaltung aller Formulare |
| ''vorlagen:'' | Zentrale Verwaltung aller Seitenvorlagen |
| Fachnamensräume | Ablage der erzeugten Wiki-Seiten |

Die Übersichtsseiten lauten:

  * [[formulare:start|Formularverzeichnis]]
  * [[vorlagen:start|Vorlagenverzeichnis]]

Jedes Formular und jede Seitenvorlage erhält eine eigene Wiki-Seite.

===== 4. Benötigte Plugins =====

==== 4.1 Bureaucracy ====

Das Bureaucracy-Plugin ermöglicht die Erstellung und Verarbeitung von Formularen.

Es unterstützt unter anderem:

  * Eingabefelder
  * Pflichtfelder
  * Mehrzeilige Textfelder
  * Feldvalidierung
  * Automatische Seitenerstellung anhand einer Vorlage

Weitere Informationen:

https://www.dokuwiki.org/plugin:bureaucracy

==== 4.2 BureaucracyToolbar ====

Das Plugin BureaucracyToolbar ergänzt Formulare um eine Werkzeugleiste.

Unterstützte Funktionen sind:

  * Fettschrift
  * Kursivschrift
  * Unterstreichung
  * Code
  * Aufzählungen
  * Links

Die Werkzeugleiste wird mit folgender Anweisung eingebunden:

<code>
<bureaucracytoolbar>
</code>

Die Anweisung steht oberhalb des Formularblocks.

Weitere Informationen:

https://github.com/edwardcodelab/bureaucracytoolbar

===== 5. Formular erstellen =====

==== 5.1 Formularseite anlegen ====

Im Namensraum ''formulare:'' wird eine neue Seite erstellt.

Beispiel:

<code>
formulare:beispiel
</code>

Jedes Formular erhält einen eindeutigen, aussagekräftigen Seitennamen.

==== 5.2 Grundaufbau ====

Ein einfaches Formular sieht folgendermaßen aus:


<file>
====== Neue Beispielseite ======

<bureaucracytoolbar>

<form>
action template vorlagen:beispiel beispiele:@@Kennung@@

fieldset "Stammdaten"

textbox "Kennung" !
textbox "Bezeichnung" !

fieldset "Beschreibung"

textarea "Beschreibung" x5

submit "Seite erstellen"
</form>
</file>

==== 5.3 Erklärung der Anweisungen ====

^ Anweisung ^ Bedeutung ^
| %%<form>%% | Beginn des Formulars |
| ''action template'' | Verwendet eine Seitenvorlage und legt das Ziel fest |
| ''fieldset'' | Erstellt einen Formularabschnitt |
| ''textbox'' | Einzeiliges Eingabefeld |
| ''textarea'' | Mehrzeiliges Eingabefeld |
| ''submit'' | Schaltfläche zum Absenden |
| %%</form>%% | Ende des Formulars |

Das Zeichen ''!'' kennzeichnet ein Pflichtfeld.

Mit ''x5'' wird bei einem Textfeld die sichtbare Höhe festgelegt.

===== 6. Seitenvorlage erstellen =====

==== 6.1 Vorlagenseite anlegen ====

Im Namensraum ''vorlagen:'' wird eine eigene Seite angelegt.

Beispiel:

<code>
vorlagen:beispiel
</code>

==== 6.2 Beispielvorlage ====

<code>
====== @@Kennung@@ – @@Bezeichnung@@ ======

===== Stammdaten =====

^ Merkmal ^ Angabe ^
| Kennung | @@Kennung@@ |
| Bezeichnung | @@Bezeichnung@@ |

===== Beschreibung =====

@@Beschreibung@@
</code>

==== 6.3 Platzhalter ====

Platzhalter verbinden Formularfelder mit den entsprechenden Stellen der Seitenvorlage.

Sie werden durch doppelte @-Zeichen eingeschlossen.

Beispiel:

<code>
@@Bezeichnung@@
</code>

Der Platzhaltername muss exakt zur Bezeichnung des Formularfeldes passen.

===== 7. Zielnamensraum festlegen =====

Der Speicherort der erzeugten Seite wird in der Anweisung ''action template'' definiert.

Beispiel:

<code>
action template vorlagen:beispiel beispiele:@@Kennung@@
</code>

Die Anweisung besteht aus:

  - ''vorlagen:beispiel'' – verwendete Seitenvorlage
  - ''beispiele:@@Kennung@@'' – Zielnamensraum und Seitenname

Das Formular kann sich unabhängig davon unter ''formulare:beispiel'' befinden.

Damit lassen sich zentral verwaltete Formulare für unterschiedliche Fachbereiche verwenden.

Für RoWaWiki wird empfohlen, den Zielnamensraum je Formular fest vorzugeben.

===== 8. Eingabefelder =====

==== 8.1 Einzeiliges Textfeld ====

<code>
textbox "Bezeichnung" !
</code>

Das Feld ist verpflichtend.

==== 8.2 Mehrzeiliges Textfeld ====

<code>
textarea "Beschreibung" x5
</code>

Das Feld ist optional und besitzt eine sichtbare Höhe von fünf Zeilen.

==== 8.3 Feldvalidierung ====

Eingaben können durch reguläre Ausdrücke überprüft werden.

Beispiel für eine Kennung mit dem Format DG-001:

<code>
textbox "Kennung" /^DG-[0-9]{3}$/ !
</code>

Zulässige Beispiele:

  * DG-001
  * DG-025
  * DG-999

Nicht zulässig sind beispielsweise DG-1 oder AB-001.

===== 9. DokuWiki-Formatierungen =====

In mehrzeiligen Formularfeldern kann DokuWiki-Syntax verwendet werden.

==== 9.1 Überschriften ====

<code>
==== Medikamente ====
</code>

==== 9.2 Aufzählungen ====

<code>
  * Erster Eintrag
  * Zweiter Eintrag
</code>

==== 9.3 Interne Links ====

<code>
[[gesundheit:medikamente:med-001|MED-001 – Relvar]]
</code>

Vor dem senkrechten Strich steht das Seitenziel, dahinter die sichtbare Beschriftung.

Die BureaucracyToolbar unterstützt das Einfügen der Syntax. Der korrekte Seitenpfad muss gegebenenfalls manuell ergänzt werden.

===== 10. Formular testen =====

Vor der produktiven Verwendung sollte jedes neue Formular getestet werden.

Empfohlene Vorgehensweise:

  - Formularseite speichern und Darstellung prüfen.
  - Kontrollieren, ob alle Eingabefelder vorhanden sind.
  - Testdaten eingeben.
  - Eine Testseite erstellen.
  - Zielnamensraum und Seitennamen prüfen.
  - Übernahme aller Platzhalter kontrollieren.
  - Überschriften, Listen und Links überprüfen.
  - Testseite nach erfolgreicher Prüfung entfernen.

Bereits vorhandene Seiten dürfen nicht unbeabsichtigt überschrieben werden.

===== 11. Berechtigungen =====

Die Erstellung neuer Seiten unterliegt den DokuWiki-Zugriffsrechten (ACL).

Für RoWaWiki gelten folgende Empfehlungen:

  * Formulare dürfen nur berechtigten Personen zugänglich sein.
  * Änderungen an Formularen und Vorlagen bleiben autorisierten Bearbeitern vorbehalten.
  * Für die Zielnamensräume müssen die erforderlichen Erstellungsrechte vorhanden sein.
  * Ein Formular darf keine Berechtigungen auf geschützte Fachseiten umgehen.

===== 12. Wartung und Änderungen =====

Änderungen an Formularen und Seitenvorlagen sollten aufeinander abgestimmt werden.

Dabei ist zu beachten:

  * Feldnamen und Platzhalter müssen übereinstimmen.
  * Änderungen an Vorlagen wirken sich auf künftig erzeugte Seiten aus.
  * Bereits erstellte Seiten werden durch eine Vorlagenänderung nicht automatisch aktualisiert.
  * Nach strukturellen Änderungen ist ein erneuter Funktionstest sinnvoll.

===== 13. Beispiel aus RoWaWiki =====

Das Formular zur Erstellung medizinischer Diagnoseseiten ist unter folgendem Pfad gespeichert:

[[formulare:dg|Neue Diagnose (DG)]]

Die zugehörige Seitenvorlage:

[[vorlagen:dg|Seitenvorlage Diagnose (DG)]]

Erzeugte Diagnoseseiten werden im Namensraum

''gesundheit:medizinische-themen:''

abgelegt.

===== 14. Weiterführende Dokumentation =====

  * [[https://www.dokuwiki.org/plugin:bureaucracy|Bureaucracy-Plugin]]
  * [[https://github.com/edwardcodelab/bureaucracytoolbar|BureaucracyToolbar]]
  * [[https://www.dokuwiki.org/wiki:syntax|DokuWiki-Syntax]]
  * [[https://www.dokuwiki.org/acl|DokuWiki-Zugriffsrechte]]