Lernseite · Form Framework
Formulare mit dem Form Framework bauen, konfigurieren und übersetzen
Fast jede Website braucht Formulare: Kontakt, Anmeldung, Bewerbung. TYPO3 bringt dafür das Form Framework mit. Auf dieser Seite baut die Integratorin Mara für die Musikschule Lindenau ein Anmeldeformular für Probestunden. Danach weißt du, wie Konfiguration und Formular zusammenhängen, wo Formulare gespeichert werden, was nach dem Absenden passiert und wie du Texte und Templates anpasst.
Was das Form Framework ist
Das Form Framework ist die System-Extension EXT:form. Sie gehört zum Core und kostet nichts extra. Drei Gruppen arbeiten damit: Redakteure bauen Formulare im Backend, Integratoren konfigurieren das Framework, und Entwickler erweitern es mit eigenem Code.
Im Backend besteht EXT:form aus drei Bestandteilen:
- Der Form Manager zeigt alle Formulare als Liste. Hier legst du Formulare an, duplizierst oder löschst sie.
- Der Form-Editor bearbeitet ein einzelnes Formular. Elemente ordnest du dort per Drag and Drop an.
- Das Formular-Plugin mit dem Namen „Form“ bindet ein fertiges Formular als Inhaltselement auf einer Seite ein.
Form Manager und Form-Editor findest du in TYPO3 14 im Modul Content, Forms. Das Plugin wählst du wie jedes andere Inhaltselement auf der Seite aus. Einen HTML-Code kopierst du dafür nicht.
Zwei Begriffe begegnen dir ständig. Validatoren prüfen die Eingaben, bevor das Formular als abgeschickt gilt. Finisher sind die Aktionen nach dem erfolgreichen Absenden, etwa eine E-Mail senden oder auf eine Dankeseite weiterleiten. Dazu kommen Varianten: Sie ändern ein Element zur Laufzeit, wenn eine Bedingung erfüllt ist.
Beschrieben wird alles in YAML, die Konfiguration des Frameworks ebenso wie die Formulare selbst.
Baukasten und Formular
Das Wichtigste am Form Framework ist eine Unterscheidung.
- Die Form-Konfiguration beschreibt das Framework. Sie legt fest, welche Elemente, Validatoren und Finisher es gibt, wie sie voreingestellt sind und wie sie im Frontend und im Backend erscheinen.
- Die Formulardefinition beschreibt ein einzelnes Formular: seine Seiten, seine Felder in einer bestimmten Reihenfolge, die Validatoren an den Feldern und die Finisher.
Der Elementtyp Text steht also in der Konfiguration, das Textfeld „Name“ im Probestunden-Formular in der Definition. Die Konfiguration liegt als YAML in einer Extension und wird nicht im Form-Editor bearbeitet. Die Definition entsteht meistens im Form-Editor.
Die Konfiguration ist in Prototypen gegliedert. Ein Prototyp bündelt alle Elemente, Validatoren, Finisher, Rendering-Optionen und Übersetzungsdateien unter einem Namen. Der Standard-Prototyp heißt standard. Fast jede Formulardefinition verweist mit dem Schlüssel prototypeName auf ihn. Mehrere Prototypen sind möglich, aber kein Formular braucht einen eigenen.
Form Sets: Konfiguration aus der Extension
Mara will die Form-Konfiguration anpassen, etwa eigene Templates und Übersetzungen eintragen. Das gehört in ihr Sitepackage lindenau_site. Seit TYPO3 14.2 geht das über Form Sets. Ein Form Set ist ein Unterordner im Ordner Configuration/Form/ einer Extension mit einer Datei config.yaml. Der Name des Unterordners ist frei wählbar, eine Extension darf mehrere Sets mitbringen.
# EXT:lindenau_site/Configuration/Form/LindenauForm/config.yaml
name: lindenau/form
label: 'Musikschule Lindenau: Formulare'
priority: 200
persistenceManager:
allowedExtensionPaths:
10: 'EXT:lindenau_site/Resources/Private/Forms/'Die drei Schlüssel name, label und priority sind reservierte Metadaten. Der Name folgt dem Muster Anbieter, Schrägstrich, Name, wie bei Composer-Paketen. Das Label dient nur der Anzeige. Die Priorität bestimmt die Ladereihenfolge. Alle anderen Schlüssel sind Form-Konfiguration.
TYPO3 findet Form Sets automatisch in allen aktiven Extensions, für Frontend und Backend zugleich. Du musst nichts in PHP oder TypoScript registrieren.
Reihenfolge: Die Sets werden nach aufsteigender priority geladen. Jedes Set wird mit der PHP-Funktion array_replace_recursive über das vorherige gelegt. Das Basis-Set aus dem Core heißt typo3/form-base und hat die Priorität 10. Ein Set ohne Angabe bekommt 100. Ein höherer Wert wird später geladen und überschreibt also.
Der alte Weg: Bis TYPO3 14.1 registrierte man YAML-Dateien per TypoScript unter settings.yamlConfigurations, im Plugin tx_form und für das Backend zusätzlich unter module. Seit 14.2 ist das veraltet. Es funktioniert für Frontend und Backend noch, löst aber eine Deprecation-Meldung aus und fällt mit TYPO3 15 weg.
Aufbau einer Formulardefinition
Jetzt zum eigentlichen Formular. Auf oberster Ebene hat jede Definition vier Angaben: identifier als eindeutige Kennung, label als Beschriftung, prototypeName für den Prototyp und type mit dem Wert Form. Darunter folgen die Seiten unter renderables und die Finisher unter finishers.
identifier: probestunde
label: 'Anmeldung zur Probestunde'
prototypeName: standard
type: Form
renderables:
- identifier: seite-1
type: Page
label: 'Deine Angaben'
renderables:
- identifier: name
type: Text
label: 'Name'
validators:
- identifier: NotEmpty
- identifier: email
type: Email
label: 'E-Mail'
validators:
- identifier: NotEmpty
- identifier: EmailAddress
finishers:
- identifier: EmailToReceiver
options:
subject: 'Neue Anmeldung'Die Verschachtelung ist immer gleich. Ein Formular enthält unter renderables eine oder mehrere Seiten vom Typ Page, jede Seite unter renderables ihre Felder. Ein Feld braucht mindestens Kennung und Typ, meistens auch eine Beschriftung.
Validatoren hängen am Feld, als Liste unter validators. Jeder Eintrag verweist mit seinem identifier auf einen Validator der Konfiguration, etwa NotEmpty, EmailAddress oder StringLength. Bei ungültiger Eingabe erscheint eine Fehlermeldung direkt am Feld.
Finisher hängen dagegen am Formular, unter finishers auf oberster Ebene. Sie laufen erst, wenn alle Validatoren zufrieden sind.
Bedingungen mit Varianten
Die Musikschule nimmt auch Kinder an. Bei einem Kind muss der Name eines Elternteils dabei sein, bei Erwachsenen nicht. Ein zweites Formular wäre umständlich, und ein Finisher käme zu spät, denn er läuft erst nach erfolgreicher Prüfung. Die Lösung ist eine Variante.
Eine Variante hängt an einem Element. Sie hat eine eigene Kennung, eine Bedingung und die Werte, die gelten sollen, wenn die Bedingung erfüllt ist. Zur Laufzeit prüft EXT:form die Bedingung und überschreibt dann die genannten Eigenschaften.
- identifier: elternteil
type: Text
label: 'Name eines Elternteils'
variants:
- identifier: pflicht-fuer-kinder
condition: 'traverse(formValues, "kind") == 1'
validators:
- identifier: NotEmptyVarianten können Eigenschaften wie label, enabled, validators, defaultValue und die Werte unter properties ändern. Mit enabled blendest du ein Element ganz aus oder ein. Die Kennung und der Typ eines Elements bleiben dagegen fest. Eine Variante macht aus einem Textfeld also kein Auswahlfeld.
Finisher und E-Mails
Nach dem Absenden soll die Musikschule eine E-Mail bekommen, die Anmelderin eine Bestätigung, und der Browser soll eine Dankeseite zeigen. Dafür gibt es fertige Finisher:
- Email to receiver, intern EmailToReceiver, schickt die Eingaben an den Empfänger, meistens den Betreiber der Website.
- Email to sender, intern EmailToSender, schickt eine E-Mail an die Person, die das Formular ausgefüllt hat.
- Confirmation zeigt eine Bestätigungsmeldung an.
- Redirect leitet auf eine andere Seite weiter.
- SaveToDatabase speichert die Daten in einer Tabelle.
- DeleteUploads entfernt hochgeladene Dateien wieder.
Feldwerte einsetzen: In Finisher-Optionen setzt du einen Feldwert ein, indem du die Kennung des Felds in geschweifte Klammern schreibst. Für das Feld email-1, so benennt der Form-Editor Felder, steht dort also email-1 in geschweiften Klammern. Andere Schreibweisen, etwa mit Dollarzeichen oder Prozentzeichen, funktionieren hier nicht.
options:
subject: 'Probestunde für {name}'
senderAddress: 'anmeldung@musikschule-lindenau.de'
senderName: 'Musikschule Lindenau'
recipients:
'sekretariat@musikschule-lindenau.de': 'Sekretariat'
replyToRecipients:
'{email-1}': ''Die Adressfelder einer E-Mail haben verschiedene Aufgaben:
- From ist der Absender. Nimm eine Adresse der eigenen Domain. Eine fremde Absenderadresse, etwa die des Besuchers oder eines Freemailers, erkennen Prüfverfahren wie SPF und DMARC oft als gefälscht. Die Mail landet dann im Spam oder wird abgewiesen.
- To nennt die Empfänger.
- Reply-To bestimmt, wohin eine Antwort geht. Hier gehört die Adresse des Besuchers hin. Klickt das Sekretariat auf Antworten, landet die Antwort bei der Anmelderin.
- Cc schickt eine Kopie. Alle Empfänger sehen die Cc-Adressen.
- Bcc schickt eine Blindkopie. Diese Empfänger sind für die anderen nicht sichtbar.
- Return-Path nimmt Unzustellbarkeitsmeldungen auf, also die Rückläufer, wenn eine Mail nicht ankommt. Eine eigene Option dafür hat der E-Mail-Finisher nicht.
Neu seit 14.2: eine eigene Nachricht. EmailToSender und EmailToReceiver haben ein optionales Nachrichtenfeld mit Rich-Text-Editor. Es nutzt das RTE-Preset form-content. Ein besonderer Platzhalter bestimmt, wo die Tabelle mit den Eingaben erscheint: das Wort formValues in geschweiften Klammern. Text davor steht über der Tabelle, Text danach darunter. Fehlt der Platzhalter, enthält die E-Mail nur die Nachricht, die Tabelle der Eingaben wird ausgeblendet. Das Nachrichtenfeld gibt es im Form-Editor und in den Finisher-Einstellungen des Plugins.
Was der Editor nicht kann: Im Form-Editor bearbeitest du Betreff, Empfänger, Absender, Reply-To, Cc, Bcc, Titel und Sprache. Auch HTML-Teil und Anhänge schaltest du dort. Die Template-, Partial- und Layout-Pfade des E-Mail-Finishers und die Option variables setzt du dagegen nur in YAML oder PHP.
Der Form-Editor
Mara klickt im Modul Content, Forms auf „Neues Formular erstellen“. Der Assistent fragt nach Prototyp, Vorlage und Speicherort. Dann öffnet sich der Form-Editor. Neue Felder fügt sie über den Knopf „Neues Element erstellen“ ein. Ein Dialog zeigt die Elemente in Gruppen wie Grundelemente, Auswahlelemente, erweiterte Elemente und Container. Per Drag and Drop verschiebt sie vorhandene Elemente an die richtige Stelle. Neue Elemente zieht man nicht aus einer Leiste ins Formular. Rechts im Inspector stellt sie Beschriftung, Platzhalter, Validatoren und weitere Eigenschaften ein. HTML schreibt sie dabei nicht.
Datum: Für den Wunschtermin nimmt Mara das Element Date. Es nutzt das native HTML-Eingabefeld vom Typ date, der Browser bringt den Kalender selbst mit. Das ältere Element DatePicker hing an jQuery und ist seit TYPO3 14.2 veraltet, mit TYPO3 15 fällt es weg. Für Date gibt es seit 14.2 im Backend einen Datumseditor. Mit ihm stellst du Standardwert und Grenzen des Validators DateRange bequem ein, auch relativ wie „heute“ oder „in einem Monat“.
Rich Text im Editor: Seit 14.2 unterstützt der Form-Editor CKEditor 5. Jedes Textarea-Feld im Inspector kann einen Rich-Text-Editor bekommen. Du schaltest ihn in der Form-Konfiguration ein, mit der Option enableRichtext und einem RTE-Preset unter richtextConfiguration. Jedes registrierte Preset ist möglich. Neu sind die Presets form-label für kurze Texte mit fett, kursiv und Link und form-content mit zusätzlichen Listen. Von Haus aus haben StaticText, die Beschriftung der Checkbox und der Confirmation-Finisher einen Rich-Text-Editor.
Datei-Uploads
Interessenten sollen Noten als PDF mitschicken können. Dafür gibt es FileUpload und ImageUpload. Seit TYPO3 14.2 erlauben beide mehrere Dateien in einem Feld:
- Mit
multiple: truewählt man mehrere Dateien auf einmal aus. Im Form-Editor ist das eine Checkbox. - Mit
allowRemoval: truekönnen Besucher einzelne Dateien vor dem Absenden wieder entfernen. - Die Eigenschaft
saveToFileMountlegt den Ordner fest, in dem die Uploads landen, zum Beispiel den Ordner user_upload im ersten Speicher. - Der Validator Count begrenzt die Zahl der Dateien.
Jede Einsendung legt dort einen Unterordner an, dessen Name mit form und einem Unterstrich beginnt. Die Dateien werden beim Absenden nicht verschoben. Darum sammeln sich diese Ordner an, auch von abgebrochenen Einsendungen.
Zum Aufräumen gibt es seit 14.2 den Befehl form:cleanup:uploads. Du gibst ihm die Upload-Ordner als Argument. Er löscht die Unterordner, die älter als die Aufbewahrungszeit sind. Standard sind zwei Wochen, also 336 Stunden. Mit der Option dry-run siehst du vorher, was betroffen wäre. Der Befehl lässt sich auch als Scheduler-Task regelmäßig ausführen.
vendor/bin/typo3 form:cleanup:uploads 1:/user_upload/ --dry-run
vendor/bin/typo3 form:cleanup:uploads 1:/user_upload/ --retention-period=48Speichern, einbinden und weitergeben
Wo Formulare liegen: Seit TYPO3 14.2 kennt EXT:form drei Speicherarten.
- Datenbank: Der Form Manager speichert neue Formulare als Datensätze in der Tabelle form_definition. Das ist seit 14.2 der empfohlene Standardweg.
- Extension-Pfade: Formulare liegen als YAML-Datei in einer Extension. Erlaubt werden die Ordner mit
persistenceManager.allowedExtensionPaths. - File Mounts: Formulare liegen als YAML-Datei in fileadmin. Dieser Weg ist seit 14.2 veraltet und fällt mit TYPO3 15 weg.
Die Tabelle form_definition hat drei Inhaltsfelder: Beschriftung, Kennung und die Definition als JSON. Sie ersetzt nichts in tt_content, das Plugin verweist nur auf das Formular. Im normalen Bearbeitungsformular sind die Felder schreibgeschützt, bearbeitet wird im Form-Editor. Klickst du im Modul Records auf den Titel eines Formulars, öffnet sich der Form-Editor. Löschen geht nur im Form Manager, und neue Datensätze über den normalen Assistenten sind per Page TSconfig gesperrt. Alle Änderungen laufen über den DataHandler. Damit gelten die Rechteprüfung, der Verlauf und die Hooks. Backend-Benutzer brauchen Tabellenrechte für form_definition.
Einbinden: Mara legt auf der Seite „Probestunde“ ein Inhaltselement mit dem Formular-Plugin an und wählt dort das Formular aus. Dasselbe Formular kann sie auf beliebig vielen Seiten einbinden, mit je einem eigenen Plugin. Definiert wird es nur einmal.
Weitergeben: Für Formulare, die versioniert in mehreren Projekten gleich ausgeliefert werden sollen, passt ein Extension-Pfad. Die YAML-Datei liegt dann im Git-Repository und kommt mit jedem Deployment mit. Die Datenbank passt für Formulare, die Redakteure im Projekt selbst pflegen.
Übertragen zwischen Speicherarten: Dafür gibt es zwei Werkzeuge.
- Der Upgrade Wizard „Migrate file-based forms to database storage“ verschiebt alle Formulare aus File Mounts in die Datenbank. Er passt die Verweise in den Plugins an und löscht danach die YAML-Dateien. Dateien in Extensions lässt er unberührt.
- Der Konsolenbefehl
form:definition:transferkopiert Formulare zwischen den Speicherarten filemount, extension und database. Mit der Option move wird die Quelle nach erfolgreicher Übertragung entfernt.
vendor/bin/typo3 form:definition:transfer --source=filemount --target=database --moveÜbersetzen mit XLIFF
Die Musikschule hat auch englische Seiten. Formulare übersetzt du nicht mit einer Kopie der YAML-Datei je Sprache, sondern mit XLIFF-Dateien. EXT:form übersetzt dabei Eigenschaften, Fehlermeldungen der Validatoren und Finisher-Optionen.
Registrieren: Eigene Sprachdateien trägst du in der Form-Konfiguration unter translationFiles ein. Sie stehen bei den Rendering-Optionen des Elements Form, im Bereich translation. Die Liste wird vom höchsten Schlüssel zum niedrigsten abgearbeitet. Maras Datei mit dem Schlüssel 20 wird also vor der Datei von EXT:form mit 10 durchsucht.
prototypes:
standard:
formElementsDefinition:
Form:
renderingOptions:
translation:
translationFiles:
20: 'EXT:lindenau_site/Resources/Private/Language/Form/locallang.xlf'Eigenschaften von Feldern: EXT:form sucht für eine Beschriftung drei Schlüssel, vom spezifischsten zum allgemeinsten. Zuerst Formular plus Feld, dann nur das Feld, zuletzt der Elementtyp. Der spezifischste Schlüssel, der existiert, gewinnt. Findet sich keiner, bleibt der Text aus der Definition.
Fehlermeldungen von Validatoren erkennst du an der Fehlernummer. Extbase gibt jeder Meldung eine feste Nummer, NotEmpty meldet zum Beispiel 1221560910. Für ein Feld LastName im Formular ContactForm prüft EXT:form vier Schlüssel in dieser Reihenfolge:
ContactForm.validation.error.LastName.1221560910
ContactForm.validation.error.1221560910
validation.error.LastName.1221560910
validation.error.1221560910Findet sich keiner davon, erscheint die Standardmeldung von Extbase. Der Name des Validators kommt in keinem Schlüssel vor.
Finisher-Optionen haben zwei Stufen: zuerst Formular, finisher, Finisher-Kennung und Option, dann dasselbe ohne Formular. Wichtig ist die Reihenfolge: Erst gilt der Wert aus der Definition, dann ein überschriebener Wert aus dem Plugin, zuletzt die Übersetzung.
HTML und Platzhalter: Die Beschriftung der Checkbox zur Datenschutzerklärung soll einen Link enthalten. Dann muss das HTML in der XLIFF-Datei in einem CDATA-Abschnitt stehen, damit der Parser es nicht auswertet. Im Fluid-Template gibst du die Beschriftung mit dem ViewHelper f:format.raw aus, sonst erscheinen die Tags als Text. Dynamische Teile wie die URL der Datenschutzseite setzt du mit dem Platzhalter Prozent s in den Text und übergibst den Wert unter translation.arguments.
Eigene Templates
Die mitgelieferten Fluid-Templates bauen auf Bootstrap auf. Die Musikschule hat ein eigenes Design. Mara ändert die Templates aber nicht im Ordner vendor, typo3, cms-form. Dort gehen Änderungen beim nächsten Update verloren. Sie kopiert die nötigen Dateien in ihr Sitepackage und trägt die Pfade in der Form-Konfiguration ein.
prototypes:
standard:
formElementsDefinition:
Form:
renderingOptions:
templateRootPaths:
20: 'EXT:lindenau_site/Resources/Private/Templates/Form/'
partialRootPaths:
20: 'EXT:lindenau_site/Resources/Private/Partials/Form/'
layoutRootPaths:
20: 'EXT:lindenau_site/Resources/Private/Layouts/Form/'Das Element Form ist das Hauptelement. Für das Formular sucht EXT:form die Datei Form.html in den Template-Pfaden. Alle anderen Elemente sind Partials und heißen wie ihr Elementtyp. Ein Textfeld nutzt also das Partial Text.html.
Was sich in TYPO3 14 geändert hat: Früher gab es zwei Template-Sätze, die alten Templates und die neueren, barrierearmen Bootstrap-5-Templates im Ordner FrontendVersion2. Mit der Option templateVariant schaltete man um. In TYPO3 14 sind die alten Templates entfernt. Die neueren liegen jetzt unter den ursprünglichen Pfaden, und die Option templateVariant gibt es nicht mehr.
E-Mail-Templates: Die E-Mail-Finisher rendern mit FluidEmail. Unter dem konfigurierten Template-Namen, Standard ist Default, erwarten sie eine HTML- und eine Text-Fassung. Eigene E-Mail-Templates legst du ebenfalls im Sitepackage ab und registrierst die Pfade in den Optionen des Finishers. Zusätzliche Werte übergibst du mit der Option variables. Alles darunter steht im Template als Variable bereit. Die Formularwerte sind dort ohnehin zugänglich. Pfade und variables stehen in YAML, nicht im Form-Editor.
finishers:
- identifier: EmailToReceiver
options:
templateRootPaths:
20: 'EXT:lindenau_site/Resources/Private/Templates/Email/'
variables:
schulname: 'Musikschule Lindenau'Das Wichtigste in Kürze
- EXT:form ist das Formular-Framework im Core mit Form Manager, Form-Editor und Formular-Plugin im Modul Content, Forms.
- Die Form-Konfiguration ist der Baukasten in Prototypen, meist standard. Die Formulardefinition beschreibt ein einzelnes Formular.
- Seit TYPO3 14.2 liegt eigene Konfiguration in Form Sets mit einer Datei config.yaml. Sie werden nach aufsteigender priority zusammengeführt, und der höhere Wert gewinnt.
- Die Registrierung über yamlConfigurations in TypoScript ist seit 14.2 veraltet.
- Eine Definition hat identifier, label, prototypeName und type. Felder stehen unter renderables einer Seite, Validatoren am Feld, Finisher am Formular.
- Varianten ändern Eigenschaften wie label, enabled oder validators unter einer Bedingung, aber nie Kennung oder Typ.
- From gehört zur eigenen Domain, die Adresse des Besuchers gehört in Reply-To.
- Seit 14.2 speichert der Form Manager Formulare als JSON in der Tabelle form_definition. File Mounts sind veraltet, Extension-Pfade bleiben.
- Übersetzungen kommen aus XLIFF-Dateien. Der spezifischste Schlüssel gewinnt, und XLIFF schlägt die FlexForm.
- Eigene Templates gehören ins Sitepackage. In TYPO3 14 gibt es nur noch einen Template-Satz und keine Option templateVariant mehr.
Begriffe
- EXT:form
- System-Extension von TYPO3, mit der man Formulare baut, konfiguriert und erweitert.
- Form-Konfiguration
- Beschreibt in Prototypen, welche Elemente, Validatoren und Finisher es gibt und wie sie dargestellt werden.
- Formulardefinition
- Beschreibt ein einzelnes Formular mit Seiten, Feldern, Validatoren und Finishern.
- Prototyp
- Benannte Sammlung der Konfiguration, auf die eine Definition verweist, meist standard.
- Form Set
- Ordner mit einer Datei config.yaml in einer Extension, der seit TYPO3 14.2 automatisch geladen wird.
- Finisher
- Aktion nach dem erfolgreichen Absenden, etwa E-Mail, Bestätigung oder Weiterleitung.
- Validator
- Prüfung einer Eingabe am Feld, etwa NotEmpty oder EmailAddress.
- Variante
- Bedingte Änderung von Eigenschaften eines Elements zur Laufzeit.
- form_definition
- Datenbanktabelle, in der der Form Manager seit TYPO3 14.2 Formulare als JSON speichert.
- FluidEmail
- E-Mail-Klasse von TYPO3, die eine HTML- und eine Text-Fassung aus Fluid-Templates rendert.