Inhalt

Vorbemerkungen

In dem vom Bayerischen Landkreistag und dem Bayerischen Staatsministerium für Digitales herausgegebenen Leitfaden zur nutzerorientierten und einheitlichen Formulargestaltung für die bayerischen Landkreise werden für die Umsetzung von Online-Formularen konkrete Vorschläge gemacht und Empfehlungen gegeben.

Das kostenpflichtige Leitfaden-Plugin stellt Funktionalitäten zur Verfügung, welche im Leitfaden beschrieben wurden, aber nicht standardmäßig in umsetzbar sind. Für Sachsen wurde auf Basis dieses Leitfadens ein eigenes Qualitätshandbuch für formcycle erarbeitet, das konkrete Empfehlungen und Standards für die Formularerstellung im sächsischen Kontext beschreibt. Eine Übersicht sowie das vollständige Handbuch findet man im Artikel Sachsen Leitfaden.

Im folgenden wird nach allgemeinen Installationshinweisen zunächst beschrieben, wie die einzelnen Punkte im Leitfaden unter Zuhilfenahme des Plugins umgesetzt werden können. Danach folgt eine detaillierte Beschreibung der durch das Plugin vorgenommenen Anpassungen an der Darstellung von Formularen und der durch das Plugin hinzugefügten Widgets und Funktionalitäten im Punkt Technische Dokumentation. 

Hinweis bezüglich eigenen CSS-Anpassungen

Bei Auswahl des Leitfaden-Formular-Themes werden Änderungen am Aussehen von Formularen vorgenommen. Daher kann es nach der Installation des Plugins zu Konflikten mit bereits vorhanden CSS-Anpassungen kommen, wodurch entweder die Darstellungsoptionen des Leitfaden-Themes eventuell überschrieben werden oder das Leitfaden-Theme vorhandene Darstellungsoptionen überschreibt. Daher sollte nach Auswahl des Leitfaden-Themes geprüft werden, ob das Aussehen noch den eigenen Richtlinien und den Richtlinien des Leitfadens entspricht, und bei Bedarf Anpassungen am eigenen CSS vorgenommen werden.

Installation

Das Plugin kann als Mandant-Plugin oder System-Plugin installiert werden. Eine Anleitung zur Installation von Plugins finden Sie hier.

Umsetzung von Formularen gemäß des Leitfadens

Im Folgenden wird auf die einzelnen Punkte des Leitfadens stichpunktartig eingegangen und gezeigt, wie diese nach der Installation des Leitfaden-Plugins in formcycle realisiert werden können.

Technische Dokumentation des Leitfaden-Plugins

Das Plugin stellt Ressourcen zur Verfügung, welche in Formularen automatisch verwendet werden und fügt neue Validierungsreglen und Widgets hinzu. Diese werden im folgenden genauer beschrieben.

Designanpassungen

Das Leitfaden-Plugin stellt Inhalte zur Verfügung, die das Erscheinungsbild von Formularen beeinflussen. Diese Anpassungen werden als Formular-Theme bereitgestellt und können im Formular-Designer für jedes Formular individuell ausgewählt werden.

CSS-Designanpassungen

Optische Anpassungen am Formular wie das Aussehen der Labels von Elementen, Upload-Elemente, Mussfeld-Sterne, usw.

Weiterhin kann am Upload-Element im Formular-Designer rechts unter "Erweitert" die CSS-Klasse "XUpload-Dropzone" als Container-Klasse gesetzt werden. Das Upload-Element wird dann mit einem rechteckigen Kästchen dargestellt, wo man auch per Drag&Drop Dateien hochladen kann. 

Roboto-Schriftart

Das Plugin stellt diese Schriftart als Ressource auf dem Server bereit und verwendet diese in den Formularen für alle Texte.

Upload-Feld-Darstellung

Am Upload-Feld gibt es eine neue Auswahl, welche steuert, wie Upload-Felder dargestellt werden sollen.

Klassich

Die klassische Darstellung, wie diese von formcycle bereitgestellt wird.

Modern

Die moderne Darstellung vom Leitfaden-Plugin, inklusive Anzeige der erlaubten Dateiendungen und der maximalen Dategröße.

Dropzone

Darstellung als Drop-Zone, welche die Auswahl einer Datei per Drag&Drop erlaubt.

Darstellung Hilfetexte bei Fokus

Im Formular-Designer kann im Tab "Formular" ausgewählt werden, was mit Hilfetexten passieren soll, wenn das dazugehörige Eingabefeld fokussiert wird (also etwa in das Feld geklickt wird).

(globale Einstellung)

Es wird die am Plugin konfigurierte Einstellung verwendet. Diese Option existiert aus Kompatiblitätgründen.

anzeigen

Bei Fokus eines Formularfeld wird der Hinweistext sofort angezeigt.

nicht anzeigen

Bei Fokus eines Formularfeld wird der Hinweistext nicht sofort angezeigt (sondern erst beim Überfahren des Hilfe-Icons mit der Maus).

Formularwidget: Hinweis

Mit diesem Widget können farblich abgehobene Hinweistexte leichter im Formular platziert werden. Die Konfigurationsoptionen entsprechen denen von Text-Elementen.

Formularwidget: Kontaktdaten

Mit diesem Widget können Kontaktinformationen leicht im Formular eingebunden und in einer leitfadengemäßen Form dargestellt werden. Unter Optionen kann der Inhalt des Widgets direkt konfiguriert werden. 

Der Inhalt des Widgets kann auch aus einer CSV-Datenquelle bezogen werden. Dabei ist zu beachten, dass im Header eine Spalte mit der Bezeichnung id vorhanden ist. Diese dient als Bezugspunkt zur Ermittlung der Daten. Das Gleiche gilt für DB-Abfragen.

Die Zeile in der Datenquelle, aus der die Daten gelesen werden, wird über den eingetragenen ID Wert unter Optionen ermittelt und muss einem Wert in der Tabelle entsprechen. Bei den anderen Konfigurationsoptionen werden jeweils die Spaltenbezeichnungen angegeben, aus denen die Daten entnommen werden sollen. 

Zusammenfassung

Durch das Plugin werden im Formular-Designer zusätzliche Konfigurationsmöglichkeiten hinzugefügt, welche es ermöglichen, auf der letzten im Formular vorhandenen Seite eine Zusammenfassung anzuzeigen. Auf dieser Seite wird zuerst die Zusammenfassung aller vorangegangen Seiten angezeigt und darunter alle Elemente, welche im Formular-Designer auf dieser Seite platziert wurden. In der Zusammenfassung tauchen nur die Formularelemente auf, welche sichtbar sind und einen Wert haben. Das bedeutet, dass leere Eingabefelder nicht in der Zusammenfassung aufgeführt werden. Werden Formularfelder in einem Fieldset platziert, werden diese auch in der Zusammenfassung als Block dargestellt, in welchem oben rechts ein Link Angaben ändern angezeigt wird. Mit diesem kann im Formular zurück zum jeweiligen Fieldset gesprungen werden, um eingegebene Daten zu korrigieren. Diese Funktionalität ist nur bei Fieldsets, aber nicht bei Containern und Unsichtbaren Containern vorhanden.

Um die Zusammenfassung nutzen zu können, muss bei einer Schaltfläche Zusammenfassung + prüfen als Aktion konfiguriert werden. Dadurch wird beim Klicken auf diese Schaltfläche auf die Zusammenfassungsseite gesprungen.

Konfiguration von Formularelementen

Über die unter Darstellung zu findende Option Bei Zusammenfassung kann die Sichtbarkeit von Formularelementen in der Zusammenfassung gesteuert werden. Diese Option wird bei allen Formularelementen und Widgets angezeigt, ist aber nur sinnvoll bei Bildern und bei Formularelementen, in denen der Nutzer eine Eingabe tätigen kann. Andere Elemente wie Schaltflächen werden generell nicht in der Zusammenfassung angezeigt. 

Folgende Optionen stehen zur Auswahl:

Sichtbarkeit automatisch

Das Element wird in der Zusammenfassung angezeigt, wenn es sichtbar ist und einen Wert hat oder vom Typ Bild ist. Standmäßig ist diese Option ausgewählt

nicht sichtbar

Das Element wird nicht in der Zusammenfassung angezeigt

Konfiguration der Schaltfläche

Das Leitfaden-Plugin fügt für Schaltflächen eine neue Aktion mit dem Namen Zusammenfassung + prüfen hinzu. Diese Aktion springt dabei immer auf die letzte im Formular vorhandene Seite.

Der Senden-Button zum Abschicken des Formulars sollte auf einer neuen Seite nach der Zusammenfassung eingebaut werden.

Überschrift auf der Zusammenfassungsseite

Um mit standardmäßig in formcycle vorhandenen Mitteln auf der letzten Seite über der Zusammenfassung Informationen wie zum Beispiel eine Überschrift oder einen Hinweis anzuzeigen, kann auf der für die Zusammenfassung verwendeten letzten Formularseite ein Titel oder/und Untertitel definiert werden.

Falls dies beispielsweise nur eine einfache Nachricht sein soll und die standardmäßig verwendeten Schriftgrößen dafür zu groß sind, kann das Aussehen des (Unter-)titels per CSS angepasst werden. Dies könnte für eine Zusammenfassungsseite mit dem technischen Namen pZusammenfassung beispielsweise wie folgt aussehen:

.CXPage[xn="pZusammenfassung"] .header h1 {
    /* Setzt die Schriftgröße des Titels der Zusammenfassungsseite auf 20 Pixel */
    font-size: 20px;
}
.CXPage[xn="pZusammenfassung"] .header h2 {
    /* Setzt die Schriftgröße des Untertitels der Zusammenfassungsseite auf 14 Pixel */
    font-size: 14px; 
    /* Sorgt dafür, dass der Text des Untertitel normal und nicht fett dargestellt wird */
    font-weight: normal; 
}

Drucken der Zusammenfassung

Um die Zusammenfassung drucken zu können, muss der Funktion showSummary() der Name der letzten Seite übergeben werden. Aufgerufen wird die Funktion innerhalb der on-print-Routine, d.h. wenn sich das Formular im Druckmodus befindet.

/* $.xutil.on('print') wird aufgerufen, wenn sich das Formular im Druckmodus befindet */
$.xutil.on('print', function(){
    /* nimmt alle Seiten des Formulars */
    var pages = $('.XPage') ;
    /* zählt die Seiten des Formulars (minus 1, weil JavaScript bei Null zu zählen anfängt) */    
    var lastPage = pages.get(pages.length - 1);
    /* er holt sich den Namen der letzten Seite */
    var lastPageName = $(lastPage).data('name');
    /* hier wird die letzte Seite der Funktion übergeben */ 
    $.leitfaden.showSummary('.' + lastPageName);
});

Ereignisse

Das Plugin löst Ereignisse aus, wenn die Zusammenfassung gestartet oder beendet wird. Diese können von selber geschriebenen JavaScript genutzt werden, um eigene Funktionen zu implementieren. Im Folgenden findet sich eine kurze Übersicht über die vorhandenen Ereignisse. Alle Ereignisse werden auf dem "document" gefeuert, Listener können also per "document.addEventListener(...)" oder mittels JQuery per "$(document).on(...)" registriert werden. Alle Ereignisse sind vom Typ CustomEvent, zusätzlich bereitgestellte Daten finden sich daher in der Eigenschaft detail dieses Events. 

• xfc-summary-create Wenn die Zusammenfassung erstellt wird. Wird jeweils einmal für jede Seite gefeuert, welche zusammengefasst wird. Bereitgestellte Daten sind:
  • containerHTMLElement der Seite, welche zusammengefasst wird.
  • queueAsync Funktion zum Ausführen von asynchronen Operationen.
• xfc-summary-finalize Nachdem die Zusammenfassung für alle Seiten erstellt wurde. Wird im Gegensatz zu xfc-summary-createdaher nur einmal am gefeuert. Bereitgestellte Daten sind:
  • form HTMLFormElement des Formulars, welches zusammengefasst wurde.
  • queueAsync Funktion zum Ausführen von asynchronen Operationen.
• xfc-summary-hide Wenn die Zusammenfassung beendet wird. Wird einmal gefeuert, nachdem die Zusammenfassung beendet wurde. Bereitgestellte Daten sind:
  • formHTMLFormElement des Formulars, dessen Zusammenfassung beendet wurde.
  • queueAsync Funktion zum Ausführen von asynchronen Operationen.
• xfc-summary-submit Wenn ein Formular abgesendet wird. Das Leitfaden-Plugin führt beim Absenden des Formulars noch einige zusätzliche Operationen aus, wie beispielsweise dem Entsperren von Elementen, die nur während der Zusammenfassung gesperrt sind. Dieses Ereignis wird nach diesen Operationen ausgeführt. Bereitgestellte Daten sind:
  • formHTMLFormElement des Formulars, welches abgesendet wird.

Einige Ereignisse stellen wie oben zu sehen noch eine Funktion queueAsync zur Verfügung, welche benutzt werden kann, um asynchrone Operationen auszuführen. Es wird dann gewartet, bis diese asynchronen Operationen beendet wurden, bevor fortgefahren wird. Dazu kann ein Promise übergeben werden. Die Signatur dieser Funktion ist:

(promise: Promise<unknown>) => void

document.addEventListener("xfc-summary-hide", event => {
  console.log("Hiding summary for form", event.detail.form);
});

Funktionen von $.leitfaden

Das Plugin enthält eine JavaScript-Bibliothek und stellt drei Hilfsfunktionen bereit, die über $.leitfaden verfügbar sind.

• setCompactMode(enabled: boolean)

- Beschreibung: Aktiviert den Kompaktmodus, der die Formatierung so ändert, dass das Formular kompakter angezeigt wird.

- Parameter:

- enabled (boolean): Aktiviert oder deaktiviert den Modus.

- Beispiel:

$.leitfaden.setCompactMode(true);

• showSummary(element: JQuery | HTMLElement | string)

- Beschreibung: Zeigt die Zusammenfassung bis zur angegebenen Seite an.

- Parameter:

- element (JQuery | HTMLElement | string): Element, bis zu dem die Zusammenfassung angezeigt wird. Ein String wird als CSS-Selektor interpretiert.

- Beispiel:

$.leitfaden.showSummary(".pKontakt");

• showSummaryOn(requestTypes: ...string[])

- Beschreibung: Ähnlich wie showSummary, zeigt jedoch nur die Zusammenfassung für die angegebenen Anforderungstypen an und führt sonst keine Aktionen aus..

- Parameter:

- requestTypes (string[]): Anforderungstypen für die die Zusammenfassung angezeigt wird.

- Beispiel:

$.leitfaden.showSummaryOn('provide', 'review');

i18n Variablen

Verschiedene im Leitfaden-Plugin verwendete Texte können unter dem Menüpunkt Dateien & Templates > i18n-Variablen angepasst und internationalisiert werden. Hierfür muss in der Tabelle der Variablenname und der gewünschte Text in einer neuen Zeile eingetragen werden.

Einführungsvideo

Für die vorhergehende formcycle Version 6 gibt es ein Einführungsvideo für das Leitfaden-Plugin.

Migrationsanleitung

Version 4.0.0

In Version 4 wurden einige Umstrukturierungen am Plugin vorgenommen. Diese sind insoweit abwärtskompatibel, als dass nach Update der Plugins alle Formulare noch genauso aussehen und funktionieren wie zuvor. Einige Optionen sind allerdings nun veraltet (deprecated) und sollten wie im Folgenden beschrieben entsprechend umgestellt werden.

Die Validatoren (Datentypen für Eingabefelder) wurden aus dem Leitfaden-Plugin entfernt. Um diese weiterzunutzen, muss das Validationsregel-Plugin in Version 4.1.0 installiert werden.

• Die bisher vom Leitfaden-Plugin bereitgestellten Validatoren (Datentypen für Eingabefelder) wurden entfernt. Stattdessen kann das Validationsregel-Plugin verwendet werden. Nach Installation des Validationsregel-Pluginsind die Datentypen wieder verfügbar, aber werden als veraltet markiert und sollten durch Datentypen des  Validationsregel-Plugin-Plugin ersetzt werden.
  • Beim Speichern im Formular-Designer werden die Eingabefelder angezeigt, wo noch veraltete Datentypen verwendet werden.
    
  • Statt dem Datentyp Deutsche Steueridentifikationsnummer (wie Steuernummer) sollte der Datentyp Deutsche Steueridentifikationsnummer (mit Leerzeichen) oder Deutsche Steueridentifikationsnummer (ohne Leerzeichen) verwendet werden. Der bisherige Datentyp hat die Steueridentifikationsnummer versehentlich wie eine Steuernummer formatiert.
  • Statt dem Datentyp IBAN sollte IBAN (international) verwendet werden.
  • Statt dem veralteten Datentyp IBAN (Deutschland) sollte der neue Datentyp IBAN (Deutschland) verwendet werden.
  • Statt dem Datentyp BIC sollte BIC 8-11-stellig (oder bei Bedarf auf BIC 8 stellig) verwendet werden.
• Bisher wurde das Leitfaden-Theme immer automatisch in alle Formular eingebunden. Dies geschieht aus Kompatbilitätsgründen standardmäßig immer noch. Im Formular-Designer gibt es im Tab "Formular" nun die Option, das automatische Einbinden abzuschalten. Diese sollte aktiviert werden.
  • Stattdesssen stellt das Plugin nun ein Formular-Theme bereit, was im Formular-Designer als Theme ausgewählt werden kann.
    
  • Beim Speichern im Formular-Designer wird eine Warnung angezeigt, wenn das Leitfaden-Theme noch automatisch eingebunden wird.
    
  • In einer späteren Versionen wird diese Option entfernt und das Leitfaden-Theme nie mehr automatisch eingebunden.
  • Wird ein eigenes Formular-Theme verwendet, was auf dem Leitfaden basiert, dann kann das Leitfaden-Theme bei "basierend auf" ausgewählt werden (Menü Dateien & Templates -> Formular-Theme). 
• An Upload-Felder war es möglich, durch Setzen der CSS-Klasse XUpload-Dropzone das Upload-Feld wie eine Dropzone mit Drag&Drop-Unterstützung darzustellen. Dies ist aus Kompatibilitätsgründen immer noch möglich, sollte aber nicht mehr verwendet werden.
  • Stattdessen gibt es am Upload-Feld unter "Darstellung" nun eine Auswahl, wie das Upload-Feld dargestellt werden soll. Diese Auswahl ist nur verfügbar, wenn die CSS-Klasse XUpload-Dropzone nicht gesetzt ist.
    
  • Beim Speichern im Formular-Designer wird eine Warnung angezeigt, wenn die CSS-Klasse XUpload-Dropzone noch verwendet wird.
    
  • In einer späteren Version wird die Unterstützung für die CSS-Klasse XUpload-Dropzone entfernt werden.
• Bisher gab es am Plugin eine Einstellungsmöglichkeit, um das automatische Anzeigen von Hilfetexten beim Fokussieren des Eingabefelds abzuschalten. Diese Einstellung gibt es aus Kompatiblitätsgründen immer noch.
  • Zusätzlich wurde im Formular-Designer im Tab "Formular" eine neue Auswahloption eingefügt, die steuert, wie Hilfetexte angezeigt werden. Hier gibt es 3 Auswahlmöglichkeiten: (a) globale Einstellung, (b) Anzeigen (c) Nicht anzeigen. Die Auswahlmöglichkeit globale Einstellung existiert aus Kompatiblitätsgründen und verwendet den am Plugin konfigurierten Wert.
    
• Allgemein wurde das CSS etwas überarbeitet. Dadurch hat sich möglicherweise die Spezifizität einiger CSS-Selektoren geringfügig geändert. Falls ein selber geschriebenes Theme (CSS) verwendet wird, was auf dem Leitfaden-Theme aufbaut, sollte dies überprüft werden.