9 things I didn't know about the finishers in the TYPO3 form framework

The title sounds like cheap clickbait, but the content is what I had to learn the hard way last week.

Scenario: bilingual TYPO3 site with a contact form from a configuration file. Doesn't sound exciting at first, but it will be when we want to configure the mails in the finisher in different languages. So because we want to do something trivial like send the customer a confirmation in their language. Or we want to forward the entries in an international context to a contact person who does not speak all possible languages of their target market.
The following text is not a tutorial for multilingual forms or emails. Sebastian at sebkln.de has already described this absolutely first-class.

1 - The form framework is absolutely unforgiving when it comes to mis­con­fig­ur­a­tion.

What has been configured at some point and then saved in a finisher override remains and can only be removed by taking tough measures
Possible solution 1: I know what I have changed and overwrite it manually in the finisher.
Possible solution 2: I either delete the pi_flexform field or simply delete the entire form.

The form framework is ignorant of the TYPO3 language settings.

You can set the target language in the Finsher overrides. Unfortunately, you will initially only find the entry ‘Default’ there, because the framework obviously cannot determine the active languages of the instance here. And ‘Default’ is also not the ‘default’ language of the instance, but ‘TYPO3-Default’, namely English. This means that even on a German page with an English translation, all labels are initially in English if they come from translation files. Solution: The other languages must be registered in /f7forms/Configuration/Yaml/Finishers/EmailToReceiver.yaml:

prototypes:
  standard:
    finishersDefinition:
      EmailToReceiver:
        FormEngine:
          elements:
            translation:
              language:
                config:
                  items:
                    20:
                      label: Deutsch
                      value: de

3 - You cannot use field names as e-mail addresses in the finisher overrides.

In the definition files and in the form editor, you can use field names as the source for all possible values in the finisher. senderName: ‘{first_name} {last_name}’ , senderAddress: {email}. This is practical and can also be used by editors who want to click together forms themselves. In the finisher overrides, the entry of {email} in the sender (or any other field) is acknowledged with the message that only email addresses can be entered in the fields. Field validation in the wrong place. Solution: The corresponding fields must be reconfigured in /f7forms/Configuration/Yaml/Finishers/EmailToReceiver.yaml:

prototypes:
  standard:
    finishersDefinition:
      EmailToReceiver:
        FormEngine:
          elements:
            recipients:
              el:
                _arrayContainer:
                  el:
                    email:
                      config:
                        type: input
            replyToRecipients:
            carbonCopyRecipients:
            blindCarbonCopyRecipients:

4 - Only text but no HTML mails are sent.

This may only happen to developers who (like me) are of the opinion that ‘addHtmlPart’ is defined as ‘true’ in the documentation and that the corresponding line in the configuration file can be omitted. It is also in the code of EmailFinisher.php in the $defaultOptions. However, for reasons unknown to me, this does not work. Solution: addHtmlPart must be defined in the configuration file, otherwise the value is ‘false’

finishers:
  - identifier: EmailToReceiver
    options:
      addHtmlPart: true

5 - No attachments are attached to the mails.

See the previous point and replace addHtmlPart with attachUploads.

6 - The HTML e-mail sent always has the TYPO3 logo at the top and an orange background.

Here, the form framework makes email creation very easy and simply adopts the TYPO3 system settings. For the sake of simplicity, TYPO3 uses the values that are also used for the backend login because it has no need for customised emails. Possible solution 1: In the file /config/system/settings.php, the following fields must be defined with customised values:

 [
        'backend' => [
            'loginHighlightColor' => '#...',
            'loginLogo' => 'EXT:...',
        ],
    ],
];

This also has the pleasant side effect that the backend login is also branded to the customer, which is perceived positively. Possible solution 2: Overwrite the email layout -> see next point.

7 - The e-mails sent always have a ‘TYPO3 dis­claim­er’ at the end.

As a system-loyal developer, I am of course happy about any attention that my favourite CMS gets, but I can understand if customers don't like the fact that every email sent from the professional-looking website has a text from this ‘obscure TYPO3’ at the end. Solution: A customised email layout is needed. This is then registered in /f7forms/Configuration/Yaml/Finishers/EmailToReceiver.yaml

prototypes:
  standard:
    finishersDefinition:
      EmailToReceiver:
        options:
          layoutRootPaths:
            20: 'EXT:f7forms/Resources/Private/Layouts/Form/Frontend/Finishers/Email/'
          templateRootPaths:
            20: 'EXT:f7forms/Resources/Private/Templates/Form/Frontend/Finishers/Email/'
          partialRootPaths:
            20: 'EXT:f7forms/Resources/Private/Partials/Form/Frontend/Finishers/Email/'

For inspiration, you can find TYPO3's own “SystemEmail” layout both as HTML and as TXT in vendor/typo3/cms-core/Resources/Private/Layouts. And the ‘Default’ template in vendor/typo3/cms-core/Resources/Private/Templates/Email.

8 - The mail to the recipient is not sent. The error message says something about wrong domain or wrong region.

So that recipients can simply reply to the incoming email, senderAddress is often set to {email}. The sender's address then appears in the email and when you click on Reply, you immediately have the correct address in the program. However, it is becoming increasingly common for email servers to be configured cleanly and securely and only send emails with known senders. In other words, they usually have a sender domain that is set up on the server. As very few contact requests are sent from your own domain, the finisher must be configured differently:

finishers:
  - identifier: EmailToReceiver
    options:
      senderAddress: no_reply@eigenerserver.tld
      replyToRecipients:
        '{email}': '{firstname} {lastname}'

9 - The form framework needs help.

Now that you've hopefully either learnt or at least refreshed a few things above, let's move on to the click-bait. The TYPO3 form framework is, in my opinion, an extremely powerful piece with many features. Unfortunately, it also has a few nasty bugs (I would classify a lot of the above as such), which sometimes spoil the fun of the system, especially for developers. In addition, the framework has lost a lot of developer power in recent months and has therefore received little love. Hence my appeal to all readers: Take a look at Forge to see what there is to do and help move the system forward.