README

Contao-Erweiterung, mit der Schachspielerinnen und Schachspieler über die Website eine FIDE-Identifikationsnummer beim Deutschen Schachbund beantragen können. Das Bundle nimmt die Anträge im Frontend entgegen, lässt sie per E-Mail bestätigen und stellt der Geschäftsstelle im Backend eine Bearbeitungsmaske samt Vorlagen für den Schriftverkehr zur Verfügung.

Contao: 4.13 LTS und 5.x
PHP: 7.4 bis 8.x
Lizenz: LGPL-3.0-or-later
Autor: Frank Hoppe

Installation

Über den Contao Manager nach schachbulle/contao-fideid-bundle suchen und installieren, oder auf der Kommandozeile:

composer require schachbulle/contao-fideid-bundle

Anschließend die Datenbank aktualisieren:

vendor/bin/contao-console contao:migrate

Dabei entstehen die drei Tabellen tl_fideid, tl_fideid_mails und tl_fideid_templates sowie das Feld fideid_formtyp in tl_module.

Mitinstalliert wird schachbulle/contao-helper-bundle; von dort stammt die Altersberechnung, die im Antragsformular entscheidet, ob eine erziehungsberechtigte Person angegeben werden muss.

Einrichtung

1. Einstellungen ausfüllen

System → Einstellungen → FIDE-ID-Nummern

Einstellung	Bedeutung
Signatur für E-Mail-Versand	Wird als Platzhalter `##signatur##` in jede Vorlage eingesetzt. Darf ihrerseits `##benutzer_name##` enthalten, dann unterschreibt jede Bearbeiterin mit dem eigenen Namen.
Absender für E-Mail-Versand	Absender aller aus dem Backend verschickten E-Mails, in der Form `Name <adresse@example.org>`. Die spitzen Klammern sind Pflicht — ohne sie kann der Name nicht von der Adresse getrennt werden.
Bestätigungsseite	Die Seite, auf der das Frontend-Modul FIDE-ID Antragsbestätigung eingebunden ist. Aus ihr wird der Link in der Bestätigungsmail gebildet. Ohne diese Angabe geht die Mail ohne Link hinaus und kein Antrag wird je bestätigt.
Ordner für Uploads	Zielordner für hochgeladene Ausweise und Geburtsurkunden.

Zum Upload-Ordner: Dort landen Ausweiskopien und Geburtsurkunden, also besonders schützenswerte Daten. Den Ordner in der Dateiverwaltung so anlegen, dass er nicht öffentlich abrufbar ist (in Contao: außerhalb von files/ geschützter Bereich bzw. Zugriffsschutz über den Webserver), und die Dateien nach Abschluss des Antrags löschen.

2. Seiten und Module anlegen

Layout → Module → neues Modul vom Typ FIDE-ID Antragsformular.
Layout → Module → neues Modul vom Typ FIDE-ID Antragsbestätigung.
Beide Module auf je einer eigenen Seite einbinden (Inhaltselement Modul oder als Modul im Seitenlayout).
Die Seite mit der Antragsbestätigung in den Einstellungen unter Bestätigungsseite auswählen.

Die Bestätigungsseite braucht keinen Menüeintrag — sie wird ausschließlich über den Link aus der E-Mail aufgerufen. Sie darf aber nicht geschützt sein, sonst scheitert die Bestätigung.

3. Mindestens eine E-Mail-Vorlage anlegen

Siehe E-Mail-Vorlagen. Ohne Vorlage lässt sich aus dem Backend keine Antwort verschicken.

Der Weg eines Antrags

Frontend-Formular  →  Bestätigungsmail  →  Klick auf den Link  →  Bearbeitung im Backend
   (tl_fideid)          an den Antrag-        setzt                  Status pflegen,
                        steller               form_confirmed         Antwort verschicken

Der Besucher füllt das mehrseitige Antragsformular aus. Nach jedem Schritt wird der Zwischenstand in der Sitzung und als unfertiger Datensatz in tl_fideid gespeichert (Status 0 — Formular nicht übertragen). Bricht jemand ab, bleibt der angefangene Antrag also sichtbar.
Mit dem letzten Schritt bekommt der Antrag den Status 1 — Unbearbeitet und ein Bestätigungs-Token. Es geht eine E-Mail an die Adresse der beantragten Person, in Kopie an die Geschäftsstelle.
Der Klick auf den Link in dieser Mail setzt form_confirmed. Erst jetzt gilt der Antrag als echt. In der Antragsliste wechselt die Zeile von Grau auf Farbe.
Die Geschäftsstelle arbeitet den Antrag ab, trägt die FIDE-ID ein und verschickt die Antwort.

Frontend-Module

FIDE-ID Antragsformular

Führt in mehreren Schritten durch den Antrag. Welche Schritte erscheinen, hängt von den Antworten ab:

Schritt	Inhalt	Wird übersprungen, wenn …
1	Länderkennung GER, Datenweitergabe an die FIDE, Altersbestätigung (alle drei Pflicht)	nie
2	Angaben zur beantragten Person: Name, Titel, E-Mail, Geburtsdatum, Geschlecht	nie
2.1	Angaben zur erziehungsberechtigten Person und Upload von Ausweis oder Geburtsurkunde	die beantragte Person volljährig ist
3	Anlass des Antrags (Turnier o. Ä.) und Frage nach der Vereinsmitgliedschaft	nie
4	Name des Vereins	keine Vereinsmitgliedschaft angegeben wurde
5	Upload von Ausweis oder Geburtsurkunde	bereits eine Datei vorliegt oder eine Vereinsmitgliedschaft besteht (dann bürgt der Verein für die Angaben)
6	Freie Bemerkungen	nie
7	Zusammenfassung, Sicherheitsfrage, endgültiges Absenden	nie

Das Geburtsdatum wird im Format TT.MM.JJJJ erwartet. Auf jeder Seite ab der zweiten steht unter dem Formular ein Link Formular zurücksetzen, der die Sitzung leert und wieder bei Schritt 1 beginnt.

Die Moduleinstellung Formulartyp stammt aus einer früheren Fassung und hat auf den Ablauf derzeit keinen Einfluss — der Weg durch das Formular ergibt sich allein aus den Antworten.

Gestaltung: Das Modul bindet bundles/contaofideid/css/frontend.css ein und benutzt das Template mod_fideid. Beides lässt sich im eigenen Theme überschreiben; über die Moduleinstellung Template (customTpl) kann pro Modul ein abweichendes Template gewählt werden. Die Felder tragen die üblichen Contao-Klassen (widget, widget-text, formbody …), zusätzlich die Bootstrap-Klassen form-control bzw. btn btn-primary.

FIDE-ID Antragsbestätigung

Wertet den Parameter ?token=… aus der Adresszeile aus und gibt einen von vier Sätzen aus:

Der Antrag wurde bestätigt. — der Regelfall
Der Antrag wurde bereits bestätigt. — der Link wurde ein zweites Mal geklickt
Das Token wurde nicht gefunden. — kein passender Antrag, etwa nach dem Löschen
Das Token fehlt. — die Seite wurde ohne Parameter aufgerufen

Backend: Anträge bearbeiten

Inhalte → FIDE-ID-Nummern

Die Antragsliste

Die Zeilenfarbe zeigt den Stand auf einen Blick:

Farbe	Bedeutung
grau	Der Antrag ist noch nicht per E-Mail bestätigt
rot	bestätigt, Status 0 — Formular nicht übertragen
blau	bestätigt, Status 1 bis 3 (in Arbeit)
grün	bestätigt, Status 4 — FIDE-ID versenden

Das Symbol Postfach neben jedem Antrag führt zu den E-Mails dieses Antrags. Auch seine Farbe spricht: rot, solange Nachrichten unversendet sind, gelb wenn alle heraus sind, grau wenn es noch keine gibt.

Mit dem Auge-Symbol lässt sich die Bestätigung von Hand setzen oder zurücknehmen — zum Beispiel, wenn ein Antrag telefonisch bestätigt wurde.

Die Antragsmaske

Bereich	Inhalt
Anleitung	Die 13-Punkte-Liste der Geschäftsstelle für die Abarbeitung eines Antrags
Status	Bestätigt ja/nein und der Bearbeitungsstand (0 bis 5)
Infobox	Die Antragsdaten in genau der Schreibweise, die das FIDE-Formular verlangt — Umlaute sind in ASCII umgeschrieben, das Geschlecht W erscheint als F. Zeile markieren, kopieren, im FRS einfügen.
Antragsteller	Name, Titel, Geburtsdatum, Geschlecht, E-Mail
Auftraggeber	Nur belegt, wenn jemand anderes den Antrag gestellt hat
FIDE-ID	Die vergebene Nummer und der Haken für die Eintragung in MIVIS/nuLigaLight
Datei	Der hochgeladene Ausweis samt Vorschau und Downloadlink
Schnellversand	Ein Knopf je Vorlage mit aktiviertem Schnellknopf — ein Klick verschickt die Nachricht sofort

Vorschau von PDF-Dateien: Hochgeladene PDF-Dateien werden über die PHP-Erweiterung Imagick in Bilder umgerechnet und in der Maske angezeigt. Fehlt Imagick auf dem Server, erscheint statt der Vorschau ein Hinweis; der Downloadlink funktioniert weiterhin.

Die Statuswerte

Wert	Bedeutung
0	Formular nicht übertragen (der Besucher hat abgebrochen)
1	Unbearbeitet
2	Daten unvollständig
3	Daten vollständig, FIDE-ID festlegen
4	FIDE-ID versenden
5	Fertig

E-Mail-Vorlagen

Inhalte → FIDE-ID-Nummern → Templates

Eine Vorlage besteht aus einer Betreffzeile und einer vollständigen HTML-Seite. Beim Anlegen ist bereits ein Grundgerüst eingetragen:

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<title>##subject##</title>
</head>
<body>

	##content##

</body>
</html>

Wichtig ist das <body>-Element: Für die Vorschau im Backend und für die Ablage der verschickten Nachricht wird genau sein Inhalt herausgeschnitten. Fehlt es, erscheint die ganze Seite samt <head> in der Vorschau.

Felder einer Vorlage

Feld	Bedeutung
Name, Beschreibung	Nur zur Unterscheidung in der Auswahlliste
Betreff	Betreffzeile, Platzhalter erlaubt
HTML-Inhalt	Die Vorlage selbst
Schnellversand aktivieren	Legt in der Antragsmaske einen Knopf an, der die Nachricht ohne Vorschau verschickt
Text / Hilfetext	Beschriftung und Erklärung dieses Knopfes
Aktiv	Nur aktive Vorlagen stehen zur Auswahl. Bereits verschickte Nachrichten behalten ihre Vorlage auch nach dem Deaktivieren

Platzhalter in Vorlagen

Platzhalter werden als ##name## geschrieben. Zusätzlich sind alle Insert-Tags von Contao erlaubt, etwa {{date::d.m.Y}}.

Angaben zum Antrag

Platzhalter	Inhalt
`##status##`	Bearbeitungsstand als Zahl 0 bis 5
`##formulardatum##`	Eingangsdatum als `TT.MM.JJJJ HH:MM`
`##art##`	Art des Antrags (Altbestand, in neuen Anträgen leer)
`##bemerkungen##`	Bemerkungen des Absenders
`##intern##`	Interne Bemerkungen der Geschäftsstelle

Angaben zur beantragten Person

Platzhalter	Inhalt
`##nachname##`, `##vorname##`, `##titel##`	Name und akademischer Titel
`##geburtsdatum##`	Geburtsdatum als `TT.MM.JJJJ`
`##geschlecht##`	`M` oder `W`
`##email##`	E-Mail-Adresse
`##fide_id##`	Die vergebene FIDE-Identifikationsnummer
`##verein##`	Verein
`##turnier##`	Anlass des Antrags

Angaben zum Auftraggeber

Platzhalter	Inhalt
`##antragsteller_ungleich_person##`	`1`, wenn jemand anderes den Antrag gestellt hat
`##nachname_person##`, `##vorname_person##`, `##email_person##`	Dessen Name und Adresse

Ja/Nein-Angaben (jeweils 1 oder 0)

Platzhalter	Inhalt
`##germany##`	Länderkennung GER gewünscht
`##datenschutz##`	Weitergabe der Daten an die FIDE zugestimmt
`##elterneinverstaendnis##`	Einverständnis der Eltern liegt vor
`##nuligalight##`	In MIVIS/nuLigaLight eingetragen
`##ausweis##`	Ausweis oder Geburtsurkunde ist hinterlegt

Vom System eingesetzt

Platzhalter	Inhalt
`##subject##`	Betreff aus dem E-Mail-Datensatz
`##content##`	Zusatztext aus dem E-Mail-Datensatz
`##signatur##`	Die Signatur aus den Einstellungen
`##benutzer_name##`	Name des angemeldeten Backend-Benutzers

Dieselbe Liste steht im Backend hinter dem Hilfe-Symbol neben den Feldern Betreff und HTML-Inhalt.

E-Mails versenden

Es gibt zwei Wege.

Mit Vorschau

In der Antragsliste auf das Postfach-Symbol klicken.
Neue E-Mail anlegen, eine Vorlage auswählen. Die Vorschau darunter zeigt sofort, wie die Nachricht mit den Daten dieses Antrags aussieht.
Bei Bedarf einen abweichenden Betreff und Zusatztext eintragen (##subject## und ##content## in der Vorlage).
Speichern, dann auf das Senden-Symbol klicken.
Empfänger prüfen und E-Mail versenden.

Empfänger und Kopie sind vorbelegt: Gibt es eine erziehungsberechtigte Person, geht die Post an sie und die beantragte Person bekommt eine Kopie. Sonst geht sie direkt an die beantragte Person. Mehrere Adressen mit Komma trennen; die Schreibweise Name <adresse@example.org> ist erlaubt.

Nach dem Versand werden Datum, Text und alle Empfänger im Datensatz festgehalten und die Nachricht lässt sich nicht erneut verschicken.

Ohne Vorschau (Schnellversand)

Vorlagen mit aktiviertem Schnellknopf erscheinen in der Antragsmaske unter Schnellversand. Ein Klick verschickt die Nachricht nach einer Sicherheitsabfrage sofort und legt sie anschließend als Datensatz im Postfach des Antrags ab. Gedacht ist das für Standardschreiben wie die Eingangsbestätigung.

Anträge aus dem Formulargenerator

Anträge müssen nicht über das Frontend-Modul hereinkommen. Wer lieber ein Formular aus dem Contao-Formulargenerator baut und es in tl_fideid speichern lässt, bekommt drei Hooks mitgeliefert, die dabei das Nötige ergänzen:

Hook	Klasse	Wirkung
`prepareFormData`	`Classes\FormToken`	Erzeugt `form_token` für die E-Mail-Bestätigung — greift nur, wenn das Formular ein Feld `formulardatum` hat
`prepareFormData`	`Classes\CopyEmail`	Füllt `email_person` mit der Adresse aus `email`, falls das Formular kein eigenes Feld dafür hat
`storeFormData`	`Classes\SaveAusweis`	Wandelt den Pfad einer hochgeladenen Datei in die UUID um, die die Spalte `ausweis` erwartet

Die Feldnamen im Formular müssen den Spaltennamen in tl_fideid entsprechen. Die Bestätigungsmail verschickt das Bundle in diesem Fall nicht — darum muss sich die Benachrichtigung des Formulargenerators kümmern, mit dem Token aus ##form_token## im Link.

Datenbanktabellen

Tabelle	Inhalt
`tl_fideid`	Die Anträge. `token` hält den unfertigen Antrag der laufenden Sitzung fest und wird beim Abschluss geleert; `form_token` ist das Token aus der Bestätigungsmail; `ausweis` enthält die binäre Datei-UUID
`tl_fideid_mails`	Die E-Mails je Antrag (`pid`), vorbereitet oder verschickt. `sent_to`, `sent_cc` und `sent_bcc` sind serialisierte Listen
`tl_fideid_templates`	Die Vorlagen für den Schriftverkehr

Fehlersuche

Der Bestätigungslink fehlt in der E-Mail. In den Einstellungen ist keine Bestätigungsseite gewählt oder die gewählte Seite existiert nicht mehr.

Nach dem Klick auf den Bestätigungslink erscheint „Das Token wurde nicht gefunden.“ Der Antrag wurde zwischenzeitlich gelöscht, oder der Link stammt aus einer Mail zu einem Antrag, der nachträglich neu angelegt wurde.

Das Antragsformular meldet „Das Formular hat vom Browser ungültige Parameter bekommen.“ Im Browser wurde eine alte Formularseite erneut abgeschickt. Der mitgelieferte Link setzt das Formular zurück.

Der Upload landet nicht in der Dateiverwaltung. In den Einstellungen ist kein Ordner für Uploads gewählt, oder der Ordner existiert im Dateisystem nicht mehr. Erlaubt sind JPG, JPEG, GIF, PNG und PDF; die Größenbegrenzung stammt aus den allgemeinen Contao-Einstellungen (Maximale Dateigröße).

Beim Versand kommt „Die Adresse … enthält ungültige Zeichen!“ Eine der Empfängerangaben ist keine gültige E-Mail-Adresse. Erlaubt sind die nackte Adresse und die Form Name <adresse@example.org>.

Der Absender der E-Mail ist leer. Die Einstellung Absender für E-Mail-Versand muss die Form Name <adresse@example.org> haben — ohne die spitzen Klammern lässt sich der Name nicht von der Adresse trennen.

Statt der PDF-Vorschau steht ein Hinweis in der Maske. Auf dem Server fehlt die PHP-Erweiterung Imagick. Der Downloadlink funktioniert trotzdem.

Die Backend-Bezeichnungen sind leer. Das Bundle liefert nur deutsche Sprachdateien. Die Backend-Sprache des Benutzers muss auf Deutsch stehen.

Entwicklung

Das Bundle hat bewusst kein eigenes vendor/-Verzeichnis — es wird immer als Abhängigkeit einer Contao-Installation benutzt. Die Tests laufen deshalb mit einem eigenständigen PHPUnit:

php /pfad/zu/phpunit9/vendor/phpunit/phpunit/phpunit

Die Konfiguration steht in phpunit.xml.dist, der Autoloader für den Namensraum des Bundles in tests/bootstrap.php.

Die Unit-Tests decken die Teile ab, die ohne laufenden Contao-Kern auskommen: den Aufbau der Platzhalterliste, die Formular-Hooks und die Buchführung des Formularbaukastens.

Alles Übrige — die DCA-Rückrufe, der Formularbaukasten mit echten Widgets, die E-Mail-Vorschau und die beiden Frontend-Module — wird mit dem Prüfstand gegen eine echte Installation geprüft:

php tests/Harness/pruefstand.php /pfad/zur/contao-installation

Er muss sowohl gegen eine Contao-4.13- als auch gegen eine Contao-5-Installation fehlerfrei durchlaufen. Voraussetzung ist eine Installation, in der das Bundle eingerichtet, contao:migrate gelaufen und assets:install ausgeführt wurde. Der Prüfstand legt eigene Datensätze an, räumt sie wieder ab und überschreibt dabei zwei Einstellungen — also besser keine Produktivinstallation verwenden.

Wissenswertes zum Aufbau

Classes/FormBuilder ersetzt Haste\Form\Form. Die Felder entstehen über die Widget-Klassen aus $GLOBALS['TL_FFL'], deshalb spielt es keine Rolle, dass die Upload-Klasse in Contao 4.13 FormFileUpload und in Contao 5 FormUpload heißt.
Classes/Tokens ersetzt Haste\Util\StringUtil::recursiveReplaceTokensAndTags() über die Contao-Dienste contao.string.simple_token_parser und contao.insert_tag.parser.
Classes/Helper bündelt die Ersatzlösungen für REQUEST_TOKEN, TL_MODE, TL_SCRIPT, \Session und $dc->activeRecord, die es in Contao 5 nicht mehr gibt.

schachbulle / contao-fideid-bundle

Package info

Security

Statistics