Introduction
When it was introduced with TYPO3 v8, the TYPO3 Form Framework came with a very minimalist email template that just rendered the form content as a table. The HTML email did not contain any further markup or styling.
Eventually, a new Mail API was implemented in TYPO3 v10. In this context, all emails sent from the TYPO3 core got new Fluid templates with consistent styling. By default, the logo of the backend login is rendered in the HTML mails.
I will show you how to use these email templates, customize them and overwrite them again for individual forms and finishers.
Table of contents
- General use of the new Fluid templates
- Configuration of the new template paths
- 1. Registration with $GLOBALS['TYPO3_CONF_VARS']
- 2. Configuration in the form definition
- 3. Extend the form configuration
- Recommended procedure
- Copy the default templates
- Template checklist
- Individual templates for selected emails
- Selecting the email template in the Form Editor
- Different mail layout
- Demo
General use of the new Fluid templates
The TYPO3 Form Framework currently provides four email templates, which you can find in the directory typo3/sysext/
- Default.html
The new Fluid template in HTML format - Default.txt
The new Fluid template in plaintext format - Html.html
The old template in HTML format - Plaintext.html
The old template in plaintext format
For newly created and already existing forms, the old template versions will be used by default. This behavior allows you to continue using your already customized mail templates for the time being when upgrading an existing TYPO3 project.
To use the new Fluid templates, activate the checkbox "Use FluidEmail" found in the finisher options. The form definition will look like this:
finishers:
-
options:
useFluidEmail: true
subject: 'E-Mail from website'
senderAddress: '{email}'
senderName: '{lastname}'
attachUploads: true
recipients:
info@example.com: 'ACME Inc.'
addHtmlPart: true
identifier: EmailToReceiver
Configuration of the new template paths
TYPO3 offers multiple ways to configure new template paths. These have advantages and disadvantages.
1. Registration with $GLOBALS['TYPO3_CONF_VARS']
This configuration applies to all emails sent with TYPO3.
The registration is done either via LocalConfiguration.php or AdditionalConfiguration.php in the typo3conf/ directory, or via ext_localconf.php of your sitepackage (or your extension).
The numeric array keys below 100 are reserved in TYPO3 for internal purposes.
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['templateRootPaths'][100] = 'EXT:your_extension/Resources/Private/Templates/Email';
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['layoutRootPaths'][100] = 'EXT:your_extension/Resources/Private/Layouts/Email';
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['partialRootPaths'][100] = 'EXT:your_extension/Resources/Private/Partials/Email';
Advantages:
- One-time configuration. All mail finishers in your forms will automatically take these paths into account.
- It is still possible to assign a different template to individual finishers (explained below).
Disadvantage:
- This really is a global configuration. If you setup a Fluid layout with the default name "SystemEmail" this way, it will be used for all emails sent with TYPO3 (e.g. Backend login, passwort reset, …). Depending on the project, this may not be desirable.
To avoid this, you could rename your copied layout to "FormEmail" and reference it accordingly in the mail templates with <f:layout name="FormEmail" />.
2. Configuration in the form definition
You can also specify the paths directly in the mail finisher within the form definition:
finishers:
-
options:
useFluidEmail: true
templateRootPaths:
100: 'EXT:your_extension/Resources/Private/Templates/Email/'
layoutRootPaths:
100: 'EXT:your_extension/Resources/Private/Layouts/Email/'
subject: 'E-Mail from website'
senderAddress: '{email}'
senderName: '{lastname}'
attachUploads: true
recipients:
info@example.com: 'ACME Inc.'
addHtmlPart: true
identifier: EmailToReceiver
Advantages:
- No interference with system emails.
- Template paths can be purposefully assigned to an email finisher.
Disadvantage:
- Email finishers without this option will continue to use the system default.
3. Extend the form configuration
You can add template paths in the YAML configuration of both email finishers:
TYPO3:
CMS:
Form:
prototypes:
standard:
finishersDefinition:
EmailToReceiver:
options:
templateRootPaths:
20: 'EXT:your_extension/Resources/Private/Templates/Email/'
layoutRootPaths:
20: 'EXT:your_extension/Resources/Private/Layouts/Email/'
partialRootPaths:
20: 'EXT:your_extension/Resources/Private/Partials/Email/'
# Optional: Enable FluidEmail for all newly added email finishers:
formEditor:
predefinedDefaults:
options:
useFluidEmail: true
EmailToSender:
options:
templateRootPaths:
20: 'EXT:your_extension/Resources/Private/Templates/Email/'
layoutRootPaths:
20: 'EXT:your_extension/Resources/Private/Layouts/Email/'
partialRootPaths:
20: 'EXT:your_extension/Resources/Private/Partials/Email/'
formEditor:
predefinedDefaults:
options:
useFluidEmail: true
You extend the form configuration with a YAML file in your site package. The setup is explained in this tutorial.
Starting with TYPO3 v12, the first three lines with the namespace TYPO3.CMS.Form can be removed.
Advantages:
- No interference with system emails.
- The template paths are considered for all email finishers used in form definitions.
- You can still overwrite these paths for a single email finisher in a form definition.
Recommended procedure
In my opinion, a combination of methods 2 and 3 is most suitable:
- Register new paths for the email finishers in the YAML configuration. These will then apply to all emails sent via EXT:form, but not to system emails.
- If needed, override these paths for individual emails in the form definitions.
I also suggest that you do not create a new path for each possible template. Instead, you should use the possibility to set a template name in the finisher and store the different templates in a single or a few directories:
finishers:
-
options:
# A template with this name will be searched
# in all configured templateRootPaths:
templateName: Newsletter
useFluidEmail: true
subject: 'E-Mail from website'
senderAddress: '{email}'
senderName: '{lastname}'
attachUploads: true
recipients:
info@example.com: 'ACME Inc.'
addHtmlPart: true
identifier: EmailToReceiver
The detailed questions will then depend on your customer project: do you configure two directories with different default templates for sender and receiver? Or do you have a multi-domain installation in which several subsidiaries should each receive their own email layout? Should editors (with no possibility to edit YAML directly) be able to configure new forms?
By combining the above-mentioned possibilities, it should be possible to find a reasonable structure for every use case.
If you want to use a global fluid layout for all system emails: extend only layoutRootPaths via $GLOBALS['TYPO3_CONF_VARS'] and define the templateRootPaths via YAML.
Copy the default templates
After we configured the paths, we now can copy the email templates from the TYPO3 core to the defined directory. The following checklist clarifies what may need to be taken into account.
Template checklist
Which templates do I need to copy?
As mentioned above, the email templates for forms are located in the directory typo3/sysext/
Relevant for FluidEmail are Default.html and Default.txt.
Do I need both templates (HTML and plain text)?
Not necessarily. If you want to send emails in only one of the two mail formats, you can configure this in LocalConfiguration.php with $GLOBALS['TYPO3_CONF_VARS']
Do I need to copy and customize the Fluid layout as well?
Not necessarily. The layout already uses the logo and background color configured for the backend login screen (Admin Tools > Settings > Extension Configuration > Backend > Login).
However, you probably want to replace the default footer ("This email was sent by ..." and the copyright notice) in the emails. And these texts are not variables but hard-coded in the layout.
What do I have to consider when customizing the "SystemEmail" layout?
The following problem seems to affect TYPO3 v10 only. I could not reproduce it in TYPO3 v11.
The "SystemEmail" layout is used for all emails sent from the TYPO3 core. In some cases, emails will be sent without a frontend context, e.g. when reporting a successful backend login (User Preferences > "Notify me by email when somebody logs in from my account"). This results in an error message if you use an f:translate Viewhelper in the fluid layout:
"Return value of TYPO3\CMS\
As soon as you want to use localized texts in the email layout, you must therefore limit the use of the fluid layout in question:
- Either: Save your "SystemEmail" layout under a new name and reference it in the fluid templates with <f:layout name="MyNewLayout" />.
- Or: Configure layoutRootPaths not globally, but specifically for the TYPO3 Form Framework (and maybe for other frontend plugins like EXT:felogin).
Where can I find the mail layout?
The main fluid layout for emails is located in the directory typo3/sysext/
Individual templates for selected emails
The Form Framework now uses your customized email template. But the sent emails will still all be identical in design and content. There may be cases where this is not desired, such as:
- The emails to sender and receiver should receive different templates, for example with different mail texts.
- The emails of your newsletter form need different texts and a different look than those of the contact form.
No problem! You can specify a different, self-selected templateName in the mail finisher:
finishers:
-
options:
templateName: Newsletter
useFluidEmail: true
subject: 'E-Mail from website'
senderAddress: '{email}'
senderName: '{lastname}'
attachUploads: true
recipients:
info@example.com: 'ACME Inc.'
addHtmlPart: true
identifier: EmailToReceiver
In that case, TYPO3 needs the templates Newsletter.html and Newsletter.txt in the same directory as your customized Default.html.
Selecting the email template in the Form Editor
We can also enable editors to select the desired email template themselves. For that, the Form Configuration of the Email Finisher is extended in the Form Editor:
TYPO3:
CMS:
Form:
prototypes:
standard:
formElementsDefinition:
Form:
formEditor:
propertyCollections:
finishers:
# "10" is the already existing key of the "EmailToSender" finisher.
# To also add the new select field for the "EmailToReceiver" finisher,
# you must define the configuration below the key "20".
10:
editors:
# Self defined key (must not be assigned yet):
1199:
identifier: templateName
templateName: Inspector-SingleSelectEditor
label: 'Email templates'
propertyPath: options.templateName
selectOptions:
# New Templates are added here with their name and a label:
10:
value: PrettyEmailToSender
label: 'Pretty email'
20:
value: SpecialEmailToSender
label: 'Special email'
The configuration and the following screenshot are taken from the extension "form_examples". There, the templates "PrettyEmailToSender" and "SpecialEmailToSender" are provided. Have a look at the screenshots in section Demo.
Different mail layout
With the additional "Newsletter" template you can adapt the content of the email. However, the default design is still used. In the f:layout Viewhelper of your email template, enter the desired name of your new Fluid layout, e.g. "NewsletterDesign":
Newsletter.html:
<f:layout name="NewsletterDesign" />
<f:section name="Title">{title}</f:section>
<f:section name="Main">
<!-- Mail content -->
</f:section>
Then, add NewsletterDesign.html and NewsletterDesign.txt with your new design in Resources/Private/
Demo
The extension form_examples offers a practice-oriented configuration for all TYPO3 versions from v10 and later, including two example forms that complement each other:
- For the first form, an individual templateName for each email finisher is already defined in the form configuration.
- In the second form, the templateName – only for EmailToSender – is then overridden again in the form definition. A new select field is added to the Form Editor so editors can choose the template themselves.
The configurations and templates contain explanatory comments in many places.