BC005 Formulare erstellen mit ConfiForms

ConfiForms ist ein Confluence-Plugin, das benutzerdefinierte Formulare und Workflows ermöglicht. Es bietet vielfältige Feldtypen, Automatisierungen und Integrationen, um Daten effizient zu verwalten und anzuzeigen. ConfiForms ist im BayernCollab für alle Einrichtungen verfügbar.

Um den Einstieg in ConfiForms zu erleichtern, gibt es in der BayernCollab Dokumentation ein paar Formularrezeptideen. Diese erklären die einzelnen Funktionen anhand konkreter Beispiele. Bei der ersten Formularidee handelt es sich um eine Seite, mit der ein Weihnachtsbuffet unter Arbeitskollegen koordiniert werden soll. Nutzer sollen eintragen, was sie zum Buffet mitbringen wollen und andere Nutzer können dadurch besser abschätzen, was es (noch nicht) gibt und was sie selbst bringen könnten. Das Formular und die Formulareinträge sollen dabei auf der selben Seite sichtbar sein. Wir werden die Grundlegenden Blöcke von ConfiForms zeigen, und zusätzlich ein paar fortgeschrittenere Themen anschneiden.

Um ein Formular zu definieren, benötigt man das 'ConfiForms Form Definition' Makro.

In diesem legt man den Namen des Formulars (dient als Identifikator), den Titel und weitere grundlegende Eigenschaften fest. Hier kann man auch einstellen, ob "Secure Storage" für das Formular aktiviert werden soll. Damit werden Anhänge, die Nutzer im Formular hochladen, nur für Administratoren sichtbar. Um die Knöpfe des Formulars auf deutsch angezeigt zu bekommen, müssen die 'Label' Felder überschrieben werden. Zum Beispiel soll in 'Label for Save Button' in unserem Fall 'Speichern' stehen.

Damit in dem Formular Felder stehen, müssen im Form Definition Makro 'ConfiForms Field Definition' Makros eingetragen werden. 

Field Definitions bekommen erneut einen selbst wählbaren Namen (als Identifikator), ein Label (der Anzeigename) und den Field Type, also die Art des Formularfeldes. Manche unserer Felder werden als "required" angegeben. Ohne sie auszufüllen, kann das Formular nicht abgesendet werden. Folgende Field Definitions werden in unserem Formular verwendet:

Mit Feldefinitionen alleine wird das Formular für Nutzer noch nicht sichtbar. Dafür benötigt man das 'ConfiForms (FormView) Registrations Control' Makro, welches wir im nächsten Abschnitt erklären.

Um ein Formular anzuzeigen, muss ein 'ConfiForms (FormView) Registrations Control' Makro auf einer Seite eingefügt werden. Damit das Registrations Control Makro weiß, welches Form Definition Makro die Struktur des Formulars definiert, muss der 'ConfiForms Form name' Wert dem des Form Definition Makros entsprechen. In unserem Fall wäre dies 'xmasbuffet'.

Standardmäßig werden Formulare als Knopf angezeigt, welcher das Formular in einem Popup Fenster öffnet. Wir würden das Formular lieber einbetten, weshalb wir bei dem Punkt "Rendering form as" die Option "Embedded" wählen. Wie schon bei der Form Definition sind die Standardtexte für Steuerungsknöpfe auf Englisch. Diese passen wir wieder manuell an, in dem wir die 'Label' Felder ändern.

Nun können Nutzer Einträge anlegen. Diese sehen jedoch nur Personen mit Schreibrechte auf der Seite. Um die Ergebnisse für alle Sichtbar zu machen, brauchen wir noch ein Visualisierungsmakro, welches wir im nächsten Abschnitt zeigen.

ConfiForms bietet verschiedene Möglichkeiten, um Formulareinträge zu visualisieren. Wir nutzen den 'ConfiForms Tableview', also eine Tabellenansicht.

Wie auch im Registrations Control Makro muss hier der 'ConfiForms Form name' dem des Field Definition Makros entsprechen. Standarmäßig würde das TableView Makro nun alle Felder des Formulars als Spalte anzeigen. In unserem Falls wäre es jedoch besser, wenn manche Felder wie zB. das "Besteck" Feld nicht angezeigt werden. Dieses Feld ist nämlich nur für die Organisatoren des Weihnachtsbuffets interessant. Um die Spalten benutzerdiefiniert anzuzeigen, müssen innerhalb des TableView Makros 'Confiform Field' Makros eingefügt werden.

Der Parameter 'Field name' muss hier dem gewünschten Namen der Field Definition entsprechen. Außerdem können wir den Wert, der in der Tabellenüberschrift für diese Spalte stehen soll, selbst bestimmen. Im Fall 'name' wollen wir das Label von "Dein Name" (Label in der Field Definition) zu "Name" ändern, da es sich hier um eine Auflistung und nicht um ein Formular handelt.

Ein weiterer Kniff, den man hier anwenden kann, ist einen Filter auf die Tabelle anzuwenden. Damit kann man zB. nur Einträge eines bestimmten Wertes anzeigen. Wir wollen insgesamt 3 Tabellen. Eine für Essen, eine für Getränke und eine für Nachspeisen. Deshalb kopieren wir den gesamten TableView bis wir 3 Makros haben, auf die wir die Filter foodtype:food, foodtype:drinks und foodtype:sweets anwenden. Für Essen und Nachspeisen können wir ebenfalls das Field "alcoholic" löschen, da dies nur für Getränke benötigt wird.

Weitere Filtermöglichkeiten werden im nächsten Abschnitt erklärt.

Mit 'ConfiForms Rules for Field Definitions' können Automatismen für Felder erstellt werden. Als erstes Beispiel wollen wir, dass das 'name' Feld automatisch mit dem Anzeigenamen des aktuellen Nutzers befüllt wird. 

Wir setzen den 'Field name' Parameter auf 'name', wählen 'Set value if empty' für den 'Action to execute' Parameter und schreiben name=[user.fullName] in den 'Values to set' Parameter. Dadurch wird der Name des aktuellen Nutzers ausgelesen und in das 'name' Feld geschrieben, falls dieses leer ist. Beim initialen Öffnen der Formularseite ist der Wert immer leer, weshalb am Anfang immer der Anzeigename vorgefüllt wird. Der 'No event propagation on value change' Haken verhindert hier, dass keine Endloschschleife auftreten würde, falls der Nutzer einen leeren Anzeigenamen hat (zum Beispiel durch Fehlkonfiguration in Confluence).

Anmerkung: für eine vollständige Liste aller verwendbaren Werte kann die ConfiForms Wiki herangezogen werden. Der modernere Weg wäre ebenso [user.fullName] mit [entry._user.fullName] zu ersetzen.

Rules for Field Definitions können auch bestimmte Elemente verstecken, falls diese durch Auswahl eines vorherigen Feldes nicht mehr benötigt werden. In unserem Fall wollen wir die 'Alkoholisch' Checkbox nur anzeigen, wenn im Dropdown die Option Getränk ausgewählt wurde.

Hier wählen wir als Field name 'foodtype', da dies das Feld ist, das die Bedingung auslöst. Als 'Condition' verwenden wir foodtype.label:Getränk und als 'Action to execute' wählen wir 'Show field'. Mit 'Actionable field name' wird bestimmt, auf welchem Feld die Aktion ausgeführt wird. Deshalb füllen wir hier den Feldnamen 'alcoholic' ein. Die Regel zeigt nun die Checkbox an, wenn man im Dropdown 'Getränk' ausgewählt hat. Damit auch das Gegenteil eintritt (also die Checkbox verschwindet, wenn man was anderes gewählt hat), muss die Checkbox 'With a reverse rule' gesetzt sein.

Zum Schluss wollen wir noch eine 'ConfiForms IFTTT Integration Rule' einfügen, die es uns erlaubt E-Mails zu erhalten, falls eine bestimmte Aktion im Formular ausgeführt wurde. In unserem Fall wollen wir lediglich per E-Mail informiert werden, wenn ein Neuer Eintrag hinzugefügt wurde.

In den Makro Einstellungen des IFTTT Makros legen wir fest, wann die Regel aktiviert werden soll. In unserem Fall ist das 'onCreated'. Danach definieren wir, was passieren soll: 'Send Email'. Danach können wir einen eigenen Betreff für die E-Mail festlegen (Neuer Eintrag im Weihnachtsbuffet) und im Feld 'Recipients' unsere Adresse angeben. Damit im Körper der E-Mail auch Informationen stehen, speichern wir die Makro Einstellungen und befüllen den Makro-Körper. Mit

[entry.name] hat [entry.nameoffood] zur Weihnachtsbuffet Liste hinzugefügt.

kennen wir die wichtigsten Informationen. Als kleiner Bonus, verlinken wir die Seite auf der das Formular ist direkt im Makro-Körper. Dadurch können wir diese aus der E-Mail direkt aufrufen.