For six years (and now five LTS versions!), the Form Framework is part of the TYPO3 Core. And my three extensions "form_distribution" (07/2017), "form_examples" (01/2018), and "form_variants" (10/2018) have a few years under their belt as well.
For every TYPO3 version, there exists a separate branch of the three extensions on GitHub, optimized for that version. Furthermore, "form_examples" has been updated repeatedly with new examples.
So, everything is just fine?
In fact, while preparing a talk on "Form Framework Basics" in April, I realized that I would create the extensions differently today.
I had provisionally updated the extensions for the talk – and with the feedback I gathered there, I spent the last few weeks putting each component to the test.
My goals:
- Less complexity
- More practical orientation
- Better comprehensibility
- No impact of configurations on other forms
The following paragraphs only cover the changes, not the full extension features.
Table of contents
- TYPO3 compatibility
- The Starter Kit – EXT:form_distribution
- Simplified configuration
- Removal of the custom form prototype
- Logical template structure
- Prepared translation files
- The Example Collection – EXT:form_examples
- Restricting configuration with custom form prototypes
- Individual FluidEmail templates – universal and for selected forms
- New basic configuration
- Selecting the email template in the Form Editor
- Extended template structure
- Translation files
- Documentation
- The Condition Examples – EXT:form_variants
- Translating with variants
- Finisher overrides
- Miscellaneous
- Next steps
TYPO3 compatibility
The revision was based on TYPO3 v12. For all three extensions, I created backports for TYPO3 v11 and v10 and made version-specific adjustments in configurations and templates. The branches for TYPO3 v8 and v9 will remain in the GitHub repositories but are obsolete.
The Starter Kit – EXT:form_distribution
The Starter Kit has been simplified in multiple ways. Rarely needed complexity was removed.
Simplified configuration
The Starter Kit allowed separate form templates in the frontend per page tree. This way, you could have used the Bootstrap framework for Site A and a different HTML markup for Site B. In the same way, you could have loaded different translations for each page tree.
I often needed this type of separation in my own projects. But many TYPO3 projects only have a single page tree. Therefore, the Starter Kit now loads all configurations globally, which makes the setup easier.
I will describe this way of separation in a new tutorial soon. And I will compare it with two other solutions.
Removal of the custom form prototype
The previously existing prototype "basicContactForm" was superfluous and therefore removed.
Logical template structure
There is now an official recommendation for the directory structure in site packages. I followed this recommendation, created folders and preconfigured template paths.
Prepared translation files
If you maintain a multilingual website, you can now easily enable the usage of XLIFF files in the form configuration.
XLIFF files in German and English language already provide the labels for the included contact form.
Restricting configuration with custom form prototypes
So far, I had extended the "standard" prototype of the Form Framework. However, this had an impact on all forms in the TYPO3 installation. The same was true for additional fields in the Form Editor of the TYPO3 backend.
Prototypes can also be used to influence the Form Editor and plugin overrides: for a specific prototype, you can, for example:
- make only text fields and checkboxes available in the Form Editor and
- remove all finishers except the SaveToDatabase finisher;
- allow the override of a new finisher in the plugin
Therefore, all form configurations are now defined in the new prototype "standardExamples". Its name suggests that you are encouraged to set the included configurations directly in the "standard" prototype of your TYPO3 project.
There are also separate prototypes for the FluidEmail examples and for a complaint form. Again, the idea was to limit the configuration to certain forms.
To help you understand how to work with different prototypes, I added them to the Form Manager:
Individual FluidEmail templates – universal and for selected forms
I added a second sample form to the existing one to demonstrate several procedures separately. The configurations now should be more clearly structured.
New basic configuration
- Custom prototype to limit the configuration
- Individual email templates for EmailToSender and EmailToReceiver
- Multilingual forms and emails
Both sample forms send different email templates to the sender and recipients. It enables individual content and design for each email.
A new "Footer" section allows to set the content of the email footer over the mail template (instead of the underlying email layout).
By taking a look at the templates and configurations, much will be self-explanatory. In addition, there is a tutorial on how to use FluidEmail in the Form Framework.
Selecting the email template in the Form Editor
Through the form configuration, a custom templateName is already set for both email finishers. In the second example form, we will override its value in the form definition to send an email with different content to the sender.
The assigned email template will also use a second email layout with a different color scheme.
To avoid having to set the templateName override manually in YAML, I added a selection field for the EmailToSender finisher in the Form Editor with little effort. This way, editors can select the email template themselves in the backend.
Only in TYPO3 v12, a problem currently exists with the language handling in e-mails. Form field labels and email subjects are translated correctly by the Form Framework's own translation handling. But the custom email texts are translated directly with the f:translate ViewHelper – and the given frontend language is currently not applied.
I suspect a core bug due to the adjustments made to the translation behavior. However, I have to investigate this further.
Extended template structure
As in the Starter Kit, I have again followed the official recommendation. Additionally, I separate templates by form prototype, as you can see in the new complaint form example.
Translation files
All forms for which the provided XLIFF translation files are applied are now also fully translated. Labels within the XLIFF files are organized more practically.
Documentation
I added a number of comments in Templates and Configurations that identify features and explain possible working methods.
In the XLIFF files, the comments on possible translation keys have been extended.
The README.md has been completely revised and restructured.
Translating with variants
In the conditions I had read the current frontend language from the locale:
condition: 'siteLanguage("locale") == "de_DE.UTF-8"'However, since the spelling may differ between systems (e.g. de_DE), I now read the ISO-639-1 code of the language from the Site Configuration:
condition: 'siteLanguage("twoLetterIsoCode") == "de"'Finisher overrides
Finisher can be customized with form variants as well – but the method is different here. I have added a new example form to illustrate the process.
Next steps
The extensions have been revamped. Now the tutorials are due:
My first tutorial on the Form Framework (from 2017) currently explains the entire form configuration in your site package. Based on that, it then describes how to set up different templates using a new form prototype.
However, a prototype is only one of three ways to get individual/different templates within the same TYPO3 installation. Therefore, I will modify the existing tutorial to specifically cover working with multiple form prototypes.
In a new article already in the works, I will then compare the three possible solutions (and link to existing tutorials which show the configuration). After all, in the TYPO3 Form Framework, there are always several ways to get there – and the best one will depend on your project.
Addendum: the article "TYPO3 Form Framework: 3 solutions for individual templates" is now available, and the existing tutorial is revised.