Study guide · Form Framework
Building, configuring and translating forms with the Form Framework
Almost every website needs forms: contact, registration, applications. TYPO3 ships the Form Framework for this. On this page, the integrator Mara builds a sign-up form for trial lessons for the Lindenau Music School. Afterwards you will know how configuration and form fit together, where forms are stored, what happens after submission, and how to adapt texts and templates.
What the Form Framework is
The Form Framework is the system extension EXT:form. It is part of the Core and costs nothing extra. Three groups work with it: editors build forms in the backend, integrators configure the framework, and developers extend it with their own code.
In the backend, EXT:form consists of three parts:
- The form manager lists all forms. Here you create, duplicate or delete forms.
- The form editor edits a single form. There you arrange elements by drag and drop.
- The form plugin, named "Form", places a finished form on a page as a content element.
In TYPO3 14 you find the form manager and the form editor in the module Content, Forms. You pick the plugin on the page like any other content element. You do not copy any HTML code for it.
Two terms come up all the time. Validators check the input before the form counts as submitted. Finishers are the actions after a successful submission, for example sending an email or redirecting to a thank-you page. On top of that there are variants: they change an element at runtime when a condition is met.
Everything is described in YAML, the configuration of the framework as well as the forms themselves.
Toolkit and form
The most important thing about the Form Framework is one distinction.
- The form configuration describes the framework. It defines which elements, validators and finishers exist, how they are preset, and how they appear in the frontend and the backend.
- The form definition describes one single form: its pages, its fields in a given order, the validators on the fields, and the finishers.
So the element type Text lives in the configuration, while the text field "Name" in the trial lesson form lives in the definition. The configuration sits as YAML in an extension and is not edited in the form editor. The definition is usually created in the form editor.
The configuration is organised in prototypes. A prototype bundles all elements, validators, finishers, rendering options and translation files under one name. The default prototype is called standard. Almost every form definition refers to it with the key prototypeName. Several prototypes are possible, but no form needs its own.
Form sets: configuration from your extension
Mara wants to adapt the form configuration, for example to add her own templates and translations. That belongs in her site package lindenau_site. Since TYPO3 14.2 this works through form sets. A form set is a subfolder inside the folder Configuration/Form/ of an extension, containing a file config.yaml. You can name the subfolder freely, and one extension may ship several sets.
# EXT:lindenau_site/Configuration/Form/LindenauForm/config.yaml
name: lindenau/form
label: 'Lindenau Music School: forms'
priority: 200
persistenceManager:
allowedExtensionPaths:
10: 'EXT:lindenau_site/Resources/Private/Forms/'The three keys name, label and priority are reserved metadata. The name follows the pattern vendor, slash, name, just like Composer packages. The label is only for display. The priority sets the load order. All other keys are form configuration.
TYPO3 finds form sets automatically in all active extensions, for frontend and backend at once. You do not register anything in PHP or TypoScript.
Order: Sets are loaded by ascending priority. Each set is laid over the previous one with the PHP function array_replace_recursive. The base set from the Core is called typo3/form-base and has priority 10. A set without a value gets 100. A higher value is loaded later and therefore overrides.
The old way: Up to TYPO3 14.1 you registered YAML files with TypoScript under settings.yamlConfigurations, in the plugin tx_form and, for the backend, also under module. Since 14.2 this is deprecated. It still works for frontend and backend, but it triggers a deprecation notice and will be removed in TYPO3 15.
Structure of a form definition
Now to the actual form. At the top level, every definition has four entries: identifier as a unique ID, label as its title, prototypeName for the prototype, and type with the value Form. Below them come the pages under renderables and the finishers under finishers.
identifier: probestunde
label: 'Trial lesson sign-up'
prototypeName: standard
type: Form
renderables:
- identifier: seite-1
type: Page
label: 'Your details'
renderables:
- identifier: name
type: Text
label: 'Name'
validators:
- identifier: NotEmpty
- identifier: email
type: Email
label: 'Email'
validators:
- identifier: NotEmpty
- identifier: EmailAddress
finishers:
- identifier: EmailToReceiver
options:
subject: 'New sign-up'The nesting is always the same. Under renderables, a form contains one or more pages of type Page, and each page contains its fields under its own renderables. A field needs at least an identifier and a type, and usually a label.
Validators belong to the field, as a list under validators. Each entry refers with its identifier to a validator from the configuration, such as NotEmpty, EmailAddress or StringLength. If an input is invalid, an error message appears right at the field.
Finishers, in contrast, belong to the form, under finishers at the top level. They only run once all validators are satisfied.
Conditions with variants
The music school also takes children. For a child, the name of a parent must be given; for adults it is optional. A second form would be clumsy, and a finisher would come too late, because it only runs after successful validation. The solution is a variant.
A variant belongs to an element. It has its own identifier, a condition, and the values that should apply when the condition is met. At runtime EXT:form evaluates the condition and then overrides the listed properties.
- identifier: elternteil
type: Text
label: 'Name of a parent'
variants:
- identifier: pflicht-fuer-kinder
condition: 'traverse(formValues, "kind") == 1'
validators:
- identifier: NotEmptyVariants can change properties such as label, enabled, validators, defaultValue and the values under properties. With enabled you hide or show an element entirely. The identifier and the type of an element stay fixed, though. A variant does not turn a text field into a select field.
Finishers and emails
After submission, the music school should get an email, the applicant a confirmation, and the browser should show a thank-you page. There are ready-made finishers for this:
- Email to receiver, internally EmailToReceiver, sends the input to the receiver, usually the website owner.
- Email to sender, internally EmailToSender, sends an email to the person who filled in the form.
- Confirmation shows a confirmation message.
- Redirect redirects to another page.
- SaveToDatabase stores the data in a table.
- DeleteUploads removes uploaded files again.
Inserting field values: In finisher options you insert a field value by writing the field's identifier in curly braces. For the field email-1, which is how the form editor names fields, you write email-1 in curly braces. Other notations, such as a dollar sign or percent signs, do not work here.
options:
subject: 'Trial lesson for {name}'
senderAddress: 'anmeldung@musikschule-lindenau.de'
senderName: 'Lindenau Music School'
recipients:
'sekretariat@musikschule-lindenau.de': 'Office'
replyToRecipients:
'{email-1}': ''The address fields of an email have different jobs:
- From is the sender. Use an address on your own domain. A foreign sender address, such as the visitor's or one from a free mail provider, is often detected as forged by checks like SPF and DMARC. The mail then ends up in spam or is rejected.
- To names the recipients.
- Reply-To decides where a reply goes. This is where the visitor's address belongs. When the office clicks Reply, the answer reaches the applicant.
- Cc sends a copy. All recipients can see the Cc addresses.
- Bcc sends a blind copy. These recipients are not visible to the others.
- Return-Path collects bounce messages, that is, the notices when a mail cannot be delivered. The email finisher has no option of its own for it.
New since 14.2: a custom message. EmailToSender and EmailToReceiver have an optional message field with a rich text editor. It uses the RTE preset form-content. A special placeholder decides where the table of submitted values appears: the word formValues in curly braces. Text before it appears above the table, text after it below. If the placeholder is missing, the email contains only the message, and the table of values is hidden. The message field is available in the form editor and in the finisher settings of the plugin.
What the editor cannot do: In the form editor you edit the subject, recipients, sender, Reply-To, Cc, Bcc, title and language. You also switch the HTML part and attachments there. The template, partial and layout paths of the email finisher and the option variables, however, can only be set in YAML or PHP.
The form editor
In the module Content, Forms, Mara clicks "Create new form". The wizard asks for the prototype, a template and the storage location. Then the form editor opens. She adds new fields with the button "Create new element". A dialog shows the elements in groups such as basic elements, select elements, advanced elements and container elements. With drag and drop she moves existing elements into the right position. You do not drag new elements from a palette into the form. In the inspector on the right she sets the label, placeholder, validators and other properties. She does not write any HTML.
Dates: For the preferred date Mara uses the element Date. It uses the native HTML input of type date, so the browser brings its own calendar. The older element DatePicker depended on jQuery and has been deprecated since TYPO3 14.2; it will be removed in TYPO3 15. Since 14.2 there is a date editor in the backend for Date. With it you set the default value and the limits of the DateRange validator comfortably, also relative values like "today" or "in one month".
Rich text in the editor: Since 14.2 the form editor supports CKEditor 5. Every textarea field in the inspector can get a rich text editor. You switch it on in the form configuration, with the option enableRichtext and an RTE preset under richtextConfiguration. Any registered preset works. The new presets are form-label, for short texts with bold, italic and links, and form-content, which adds lists. Out of the box, StaticText, the label of the Checkbox and the Confirmation finisher have a rich text editor.
File uploads
Applicants should be able to send sheet music as a PDF. That is what FileUpload and ImageUpload are for. Since TYPO3 14.2 both allow several files in one field:
- With
multiple: truevisitors select several files at once. In the form editor this is a checkbox. - With
allowRemoval: truevisitors can remove single files again before submitting. - The property
saveToFileMountsets the folder where uploads are stored, for example the folder user_upload in the first storage. - The validator Count limits the number of files.
Each submission creates a subfolder there whose name starts with form and an underscore. The files are not moved on submission. That is why these folders pile up, including those from abandoned submissions.
For cleaning up, there is the command form:cleanup:uploads since 14.2. You pass it the upload folders as arguments. It deletes the subfolders that are older than the retention period. The default is two weeks, that is, 336 hours. With the option dry-run you see beforehand what would be affected. The command can also run regularly as a scheduler task.
vendor/bin/typo3 form:cleanup:uploads 1:/user_upload/ --dry-run
vendor/bin/typo3 form:cleanup:uploads 1:/user_upload/ --retention-period=48Storing, embedding and passing on
Where forms live: Since TYPO3 14.2, EXT:form knows three storage types.
- Database: The form manager stores new forms as records in the table form_definition. Since 14.2 this is the recommended default.
- Extension paths: Forms are YAML files inside an extension. The folders are allowed with
persistenceManager.allowedExtensionPaths. - File mounts: Forms are YAML files in fileadmin. This way has been deprecated since 14.2 and will be removed in TYPO3 15.
The table form_definition has three content fields: label, identifier and the definition as JSON. It does not replace anything in tt_content; the plugin only refers to the form. In the normal editing form the fields are read-only, and editing happens in the form editor. If you click the title of a form in the module Records, the form editor opens. Deleting only works in the form manager, and new records via the normal wizard are blocked by page TSconfig. All changes go through the DataHandler. So permission checks, the history and hooks all apply. Backend users need table permissions for form_definition.
Embedding: On the page "Trial lesson", Mara adds a content element with the form plugin and selects the form there. She can place the same form on as many pages as she likes, each with its own plugin. It is defined only once.
Passing on: For forms that should ship identically and under version control to several projects, an extension path fits. The YAML file then lives in the Git repository and arrives with every deployment. The database fits forms that editors maintain within the project.
Transferring between storage types: There are two tools for this.
- The upgrade wizard "Migrate file-based forms to database storage" moves all forms from file mounts into the database. It updates the references in the plugins and then deletes the YAML files. It leaves files in extensions untouched.
- The console command
form:definition:transfercopies forms between the storage types filemount, extension and database. With the option move, the source is removed after a successful transfer.
vendor/bin/typo3 form:definition:transfer --source=filemount --target=database --moveTranslating with XLIFF
The music school also has English pages. You do not translate forms with a copy of the YAML file per language, but with XLIFF files. EXT:form translates properties, error messages of validators and finisher options.
Registering: You add your own language files in the form configuration under translationFiles. They sit in the rendering options of the element Form, in the section translation. The list is processed from the highest key to the lowest. So Mara's file with key 20 is searched before the EXT:form file with key 10.
prototypes:
standard:
formElementsDefinition:
Form:
renderingOptions:
translation:
translationFiles:
20: 'EXT:lindenau_site/Resources/Private/Language/Form/locallang.xlf'Field properties: For a label, EXT:form looks for three keys, from the most specific to the most general. First form plus field, then the field alone, finally the element type. The most specific key that exists wins. If none is found, the text from the definition stays.
Validator error messages are identified by their error code. Extbase gives each message a fixed number; NotEmpty, for example, reports 1221560910. For a field LastName in the form ContactForm, EXT:form checks four keys in this order:
ContactForm.validation.error.LastName.1221560910
ContactForm.validation.error.1221560910
validation.error.LastName.1221560910
validation.error.1221560910If none of them is found, the default Extbase message appears. The name of the validator does not appear in any of the keys.
Finisher options have two levels: first form, finisher, finisher identifier and option, then the same without the form. The order of precedence matters: first the value from the definition applies, then an overridden value from the plugin, and last the translation.
HTML and placeholders: The label of the checkbox for the privacy policy should contain a link. Then the HTML in the XLIFF file must sit in a CDATA section, so the parser does not interpret it. In the Fluid template you output the label with the ViewHelper f:format.raw; otherwise the tags appear as text. Dynamic parts such as the URL of the privacy page go into the text with the placeholder percent s, and you pass the value under translation.arguments.
Custom templates
The templates that ship with EXT:form are based on Bootstrap. The music school has its own design. But Mara does not change the templates in the folder vendor, typo3, cms-form. Changes there are lost with the next update. She copies the files she needs into her site package and registers the paths in the form configuration.
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/'The element Form is the main element. For the form itself, EXT:form looks for the file Form.html in the template paths. All other elements are partials named after their element type. A text field therefore uses the partial Text.html.
What changed in TYPO3 14: There used to be two template sets: the old templates and the newer, accessible Bootstrap 5 templates in the folder FrontendVersion2. You switched between them with the option templateVariant. In TYPO3 14 the old templates have been removed. The newer ones now live under the original paths, and the option templateVariant no longer exists.
Email templates: The email finishers render with FluidEmail. Under the configured template name, which is Default by default, they expect an HTML and a plain text version. You also put your own email templates into the site package and register the paths in the finisher options. You pass extra values with the option variables. Everything under it is available as a variable in the template. The form values are accessible there anyway. Paths and variables live in YAML, not in the form editor.
finishers:
- identifier: EmailToReceiver
options:
templateRootPaths:
20: 'EXT:lindenau_site/Resources/Private/Templates/Email/'
variables:
schulname: 'Lindenau Music School'Key points
- EXT:form is the Core's form framework, with form manager, form editor and form plugin in the module Content, Forms.
- The form configuration is the toolkit, organised in prototypes, usually standard. The form definition describes one single form.
- Since TYPO3 14.2, your own configuration lives in form sets with a config.yaml file. They are merged by ascending priority, and the higher value wins.
- Registration via yamlConfigurations in TypoScript has been deprecated since 14.2.
- A definition has identifier, label, prototypeName and type. Fields sit under renderables of a page, validators on the field, finishers on the form.
- Variants change properties such as label, enabled or validators under a condition, but never the identifier or the type.
- From belongs to your own domain; the visitor's address belongs in Reply-To.
- Since 14.2, the form manager stores forms as JSON in the table form_definition. File mounts are deprecated, extension paths remain.
- Translations come from XLIFF files. The most specific key wins, and XLIFF beats the FlexForm.
- Custom templates belong in the site package. TYPO3 14 has only one template set and no option templateVariant any more.
Terms
- EXT:form
- TYPO3 system extension for building, configuring and extending forms.
- Form configuration
- Describes, in prototypes, which elements, validators and finishers exist and how they are rendered.
- Form definition
- Describes one single form with pages, fields, validators and finishers.
- Prototype
- Named collection of configuration that a definition refers to, usually standard.
- Form set
- Folder with a config.yaml file in an extension, loaded automatically since TYPO3 14.2.
- Finisher
- Action after a successful submission, such as an email, a confirmation or a redirect.
- Validator
- Check of an input on a field, such as NotEmpty or EmailAddress.
- Variant
- Conditional change of an element's properties at runtime.
- form_definition
- Database table in which the form manager has stored forms as JSON since TYPO3 14.2.
- FluidEmail
- TYPO3 email class that renders an HTML and a plain text version from Fluid templates.