Zum Inhalt springen

Einleitung

Das TYPO3 Form Framework brachte bei seiner Einführung mit TYPO3 v8 ein sehr minimalistisch gehaltenes E-Mail-Template mit, dass die Formularinhalte als Tabelle renderte. Weitergehendes Markup oder Styling fehlten in der HTML-Version.

In TYPO3 v10 wurde dann eine neue Mail API implementiert. In diesem Zuge haben alle aus dem TYPO3-Core versendeten E-Mails neue Fluid-Templates mit einheitlichem Styling erhalten. Per Default wird z. B. das Logo des Backend-Logins in den HTML-Mails gerendert.

Ich zeige euch, wie ihr diese E-Mail-Templates verwendet, anpasst und für einzelne Formulare und Finisher erneut überschreibt.

Generelle Verwendung der neuen Fluid-Templates

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

Konfiguration der neuen Template-Pfade

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

1. Registrierung über $GLOBALS['TYPO3_CONF_VARS']

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.

2. Konfiguration in der Formular-Definition

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.

3. Ergänzen in der Form-Konfiguration

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.

Empfohlene Vorgehensweise

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.

    Kopieren der Default-Templates

    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.

    Template-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/.

    Individuelle Templates für einzelne E-Mails

    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.

    Das E-Mail-Template als Auswahl im Form Editor

    Die Auswahl des gewünschten E-Mail-Templates können wir auch für Redakteure bereitzustellen. Dazu wird die Form Configuration der Email-Finisher im Form Editor etwas erweitert:

    TYPO3:
      CMS:
        Form:
          prototypes:
            standard:
              formElementsDefinition:
                Form:
                  formEditor:
                    propertyCollections:
                      finishers:
                        # "10" ist der bereits vorhandene Key des "EmailToSender"-Finishers.
                        # Um das neue Auswahlfeld auch für den "EmailToReceiver"-Finisher zu ergänzen,
                        # musst du die Konfiguration unter dem Key "20" definieren.
                        10:
                          editors:
                            # Selbst gewählter Key (darf noch nicht vergeben sein):
                            1199:
                              identifier: templateName
                              templateName: Inspector-SingleSelectEditor
                              label: 'Email templates'
                              propertyPath: options.templateName
                              selectOptions:
                                # Neue Templates werden hier mit Name und Label gesetzt:
                                10:
                                  value: PrettyEmailToSender
                                  label: 'Pretty email'
                                20:
                                  value: SpecialEmailToSender
                                  label: 'Special email'

    Die Konfiguration sowie der nachfolgende Screenshot stammen aus der Extension "form_examples". Dort stehen die Templates "PrettyEmailToSender" und "SpecialEmailToSender" zur Verfügung. Siehe dazu auch die Screenshots unter Demo.

    Abweichendes Mail-Layout

    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.

    Demo

    Die Extension form_examples bietet für alle TYPO3-Versionen ab v10 eine praxisnahe Konfiguration mit zwei aufeinander aufbauenden Beispiel-Formularen:

    • Für das erste Formular wird bereits ein individueller templateName für beide E-Mail-Finisher in der Form Configuration definiert.
    • Im zweiten Formular wird dann der templateName – nur für EmailToSender – nochmals in der Formular-Definition überschrieben. Dies wird für den Redakteur zudem im Form Editor als neues Auswahlfeld bereitgestellt.

    Die Konfigurationen und Templates enthalten an vielen Stellen erläuternde Kommentare.