Variable Fluid Emails im TYPO3 Form Framework

Das TYPO3 Form Framework liefert aktuell vier E-Mail-Templates mit, die ihr im Verzeichnis typo3/sysext/form/Resources/Private/Frontend/Templates/Finishers/Email/ findet:

• Default.html
  Das neue Fluid-Template im HTML-Format
• Default.txt
  Das neue Fluid-Template im Plaintext-Format
• Html.html
  Das alte Template im HTML-Format
• Plaintext.html
  Das alte Template im Plaintext-Format

Bei neu erstellten und bereits vorhandenen Formularen werden standardmäßig die alten Template-Versionen verwendet. Das erlaubt euch beim Upgrade eines bestehenden TYPO3-Projekts, eure bereits individualisierten Mail-Templates vorerst weiter zu verwenden.

In den Finisher-Optionen findet ihr die Checkbox "Use FluidEmail", mit der ihr die Verwendung der neuen Templates aktivieren könnt. In der Form-Definition sieht das dann wie folgt aus:

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

TYPO3 bietet mehrere Möglichkeiten, neue Template-Pfade zu konfigurieren. Diese haben Vor- und Nachteile.

Diese Konfiguration gilt global für alle versendeten E-Mails.

Die Registrierung erfolgt wahlweise über die LocalConfiguration.php bzw. AdditionalConfiguration.php im Verzeichnis typo3conf/ oder über die ext_localconf.php eures Sitepackages (oder eurer Extension).

Die numerischen Array-Keys unterhalb von 100 sind in TYPO3 für interne Zwecke reserviert.

$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';

Vorteile:

• Einmalige Konfiguration. Alle Mail-Finisher in euren Formularen werden diese Pfade automatisch berücksichtigen.
• Es ist weiterhin möglich, einzelnen Finishern ein abweichendes Template zuzuweisen (weiter unten erläutert).

Nachteile:

• Es gilt wirklich global. Ein so eingerichtetes Fluid-Layout mit dem Default-Namen "SystemEmail" wird auch für alle anderen aus TYPO3 heraus versendeten E-Mails verwendet (z.B. Backend-Logins, Passwort-Reset, …). Je nach Projekt kann das auch unerwünscht sein.
  Um das zu umgehen, könnt ihr euer kopiertes Layout z.B. in "FormEmail" umbenennen und in den Mail-Templates entsprechend mit <f:layout name="FormEmail" /> referenzieren.

Die Pfade können auch direkt im Mail-Finisher innerhalb der Form-Definition angegeben werden:

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

Vorteile:

• Keine Beeinflussung von System-E-Mails.
• Template-Pfade können zielgerichtet einer E-Mail zugewiesen werden.

Nachteile:

• Mail-Finisher ohne diese Angaben verwenden weiterhin den System-Default.

In der YAML-Konfiguration können wir die Pfade allgemeingültig für die beiden Mail-Finisher ergänzen.

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: Aktiviere FluidEmail für alle neu hinzugefügten Email-Finisher:
              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

Die Form-Konfiguration erweitert ihr über eine YAML-Datei in eurem Sitepackage. Die Einrichtung wird in diesem Tutorial erläutert.
Ab TYPO3 v12 können die ersten drei Zeilen mit dem Namespace TYPO3.CMS.Form entfallen.

Vorteile:

• Keine Beeinflussung von System-E-Mails.
• Die Pfade werden für alle in Form-Definitionen eingebundenen Mail-Finisher berücksichtigt.
• Innerhalb einer Form-Definition können diese Pfade immer noch überschrieben werden.

Meiner Meinung nach eignet sich eine Kombination aus Lösungsweg 2 und 3 am besten:

• Registriert in der YAML-Konfiguration neue Pfade für die E-Mail-Finisher. Diese gelten dann für alle per EXT:form versendeten E-Mails, aber nicht für System-Mails.
• In den Formular-Definitionen könnt ihr diese Pfade immer noch für einzelne E-Mails überschreiben.

Ich empfehle euch außerdem, nicht für jedes mögliche Template einen neuen Pfad einzurichten. Stattdessen solltet ihr die Möglichkeit nutzen, einen Template-Namen im Finisher zu setzen und die verschiedenen Templates in einem einzelnen oder einigen wenigen Verzeichnissen abzulegen:

finishers:
  -
    options:
      # Das Template mit diesem Namen wird in allen
      # konfigurierten templateRootPaths gesucht:
      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

Die Detailfragen hängen dann von eurem Kundenprojekt ab: konfiguriert man zwei Verzeichnisse mit unterschiedlichen Default-Templates für Sender und Receiver? Oder hat man eine Multidomain-Installation, in der mehrere Tochterunternehmen jeweils ein eigenes Mail-Layout erhalten sollen? Sollen Redakteure (die kein YAML bearbeiten können) neue Formulare einrichten können?

Über Kombination der oben genannten Möglichkeiten sollte es möglich sein, für jeden Anwendungsfall eine sinnvolle Struktur zu finden.

Falls ihr ein allgemeingültiges Fluid-Layout für alle System-E-Mails nutzen wollt: erweitert nur layoutRootPaths über $GLOBALS['TYPO3_CONF_VARS'] und definiert die templateRootPaths über YAML.

Nachdem wir die Pfade konfiguriert haben, können wir die E-Mail-Templates aus dem TYPO3-Core in das definierte Verzeichnis kopieren. Was dabei ggf. zu beachten ist, klärt die nachfolgende Checkliste.

Welche Templates muss ich kopieren?

Wie oben genannt, liegen die Mail-Templates für Formulare im Verzeichnis typo3/sysext/form/Resources/Private/Frontend/Templates/Finishers/Email/.

Relevant für FluidEmail sind Default.html und Default.txt.

Benötige ich beide Templates (HTML und Plaintext)?

Nicht unbedingt. Falls ihr E-Mails nur in einem der beiden Mailformate versenden möchtet, könnt ihr dies in der LocalConfiguration.php mit $GLOBALS['TYPO3_CONF_VARS']['MAIL']['format'] konfigurieren (both/html/plain).

Muss ich das Fluid-Layout auch kopieren und anpassen?

Nicht unbedingt. Im Layout wird bereits das Logo und die Hintergrund­farbe verwendet, die für die Backend-Loginmaske konfiguriert wurden (Admin Tools > Settings > Extension Configuration > Backend > Login).

Allerdings möchtet ihr wahrscheinlich den Standard-Footer ("This email was sent by …" sowie den Copyright-Hinweis) in den E-Mails ersetzen. Und diese Texte sind keine Variablen, sondern fest im Layout hinterlegt.

Was ist bei der Anpassung des "SystemEmail"-Layouts zu beachten?

Das folgende Problem scheint nur TYPO3 v10 zu betreffen. In TYPO3 v11 konnte ich es nicht nachstellen.

Das "SystemEmail"-Layout wird für alle E-Mails verwendet, die vom TYPO3-Core verschickt werden. In manchen Fällen werden E-Mails ohne einen Frontend-Kontext verschickt, z.B. bei der Meldung eines erfolgten Backend-Logins (User Preferences > "Notify me by email when somebody logs in from my account"). Das führt zu einer Fehlermeldung, wenn ihr im Fluid-Layout einen f:translate Viewhelper verwendet:

"Return value of TYPO3\CMS\Extbase\Utility\LocalizationUtility::getLanguageService() must be an instance of TYPO3\CMS\Core\Localization\LanguageService, null returned"

Sobald ihr lokalisierte Texte im E-Mail-Layout verwenden möchtet, müsst ihr daher die Verwendung des betreffenden Fluid-Layouts beschränken:

• Entweder: Speichert euer "SystemEmail"-Layout unter neuem Namen und referenziert es in den Fluid-Templates mit <f:layout name="MyNewLayout" />.
• Oder: Konfiguriert layoutRootPaths nicht global, sondern speziell für das TYPO3 Form Framework (oder auch für andere Frontend-Plugins wie EXT:felogin).

Wo finde ich das Mail-Layout?

Das zentrale Fluid-Layout für E-Mails liegt im Verzeichnis typo3/sysext/core/Resources/Private/Layouts/.

Das Form Framework nutzt jetzt euer neues, individuelles E-Mail-Template. Die versendeten E-Mails sehen aber trotzdem alle gleich aus. Es mag Fälle geben, wo das nicht gewünscht ist, z. B.:

• E-Mails an Sender und Empfänger sollen unterschiedliche Templates erhalten, etwa mit abweichenden Mailtexten.
• Die E-Mails eures Newsletter-Formulars benötigen andere Texte und ein anderes Aussehen als etwa die des Kontaktformulars.

Kein Problem! Ihr könnt einen abweichenden, selbst gewählten templateName im Mail-Finisher angeben:

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

TYPO3 benötigt in dem Fall ein Newsletter.html und Newsletter.txt im selben Verzeichnis wie euer Default.html.

Mit dem zusätzlichen "Newsletter"-Template habt ihr die Möglichkeit erhalten, den Inhalt der E-Mail zu adaptieren. Als Design wird aber noch der Default verwendet. Gebt im f:layout-Viewhelper eures E-Mail-Templates den gewünschten Namen eures neuen Fluid-Layouts an, z.B. "NewsletterDesign":

Newsletter.html:

<f:layout name="NewsletterDesign" />

<f:section name="Title">{title}</f:section>
<f:section name="Main">
    <!-- Mail content -->
</f:section>

Unter Resources/Private/Layouts/Email/ ergänzt ihr dann NewsletterDesign.html und NewsletterDesign.txt mit eurer neuen Gestaltung.