TYPO3 Form Framework: 3 Lösungen für individuelle Templates

In diesem Tutorial geht es nicht einfach nur darum, die Standard-Templates des Form Frameworks im Sitepackage zu überschreiben. Ich möchte stattdessen beschreiben, wie man innerhalb einer TYPO3-Installation verschieden aussehende Formulare bereitstellen kann.

Mögliche Aufgabenstellungen:

1. Das Styling des Newsletter-Formulars soll sich vom Kontaktformular unterscheiden.
2. Die TYPO3-Installation enthält die Websites von drei verschiedenen Tochter­unternehmen, dessen Formulare jeweils abweichende Templates benötigen.
3. Redakteure sollen im Form Editor neue Formulare erstellen können; je nach Formular-Typ müssen andere Templates oder auch Felder bereitstehen.

• Mit wenig Aufwand technisch einzurichten
• Das Styling ist vom Redakteur im TYPO3-Backend selbständig wählbar

• Kleinere Styling-Anpassungen, bei denen das HTML-Markup der Formularfelder nicht verändert werden muss

Diesen exakten Fall habe ich bereits in diesem Tutorial Schritt für Schritt beschrieben.

Die Konfiguration des Form Frameworks wird meist in einer einzelnen YAML-Datei im Sitepackage angepasst.

Wenn wir ein paar einfache Grundregeln beachten, lassen sich die Template-Pfade und andere Frontend-bezogene Konfigurationen aber getrennt je Seitenbaum laden, ohne Probleme im Backend zu verursachen.

• Durch Template-Pfade oder CSS-Klassen in YAML könnt ihr unterschiedliches HTML-Markup in Formularen verwenden
• Mit XLIFF-Übersetzungsdateien könnt ihr auch unterschiedliche Formular-Labels je Seitenbaum definieren

• Ihr müsst darauf achten, im Backend benötigte Konfigurationen des Form Frameworks in der global geladenen Konfigurationsdatei zu pflegen

• TYPO3-Installationen mit mehreren Seitenbäumen, die jeweils abweichende Formular-Templates oder Labels nutzen sollen (z.B. bei Tochter­gesellschaften mit eigenem Markenauftritt)

Diesen Fall habe ich in keinem bestehenden Tutorial beschrieben, daher erfolgt die Anleitung direkt hier. Außerdem habe ich ein Proof of Concept als Extension auf Github bereitgestellt:

EXT:form_configsplit auf GitHub

Die Extension ist zwar nur für TYPO3 v12 erstellt, das Konzept lässt sich aber in allen TYPO3-Versionen mit dem Form Framework anwenden.

FormSetup.yaml:

persistenceManager:
  allowedExtensionPaths:
    500: EXT:form_configsplit/Resources/Private/Forms/
  allowSaveToExtensionPaths: true
  allowDeleteFromExtensionPaths: true

TYPO3 muss zu jedem Zeitpunkt wissen, wo es Formulare finden kann: zur Bearbeitung im Form Editor, für die Auswahl im Plugin und natürlich auch für die Ausgabe im Frontend.

Außerdem müssen die weiteren Einstellungen zum persistenceManager im Backend verfügbar sein. Also werden wir diese Einstellungen in der FormSetup.yaml global im TYPO3 laden.

In den nachfolgenden Beispielen setzen wir jeweils eine individuelle XLIFF-Übersetzungsdatei und eigene Template-Pfade. Außerdem vergeben wir per YAML auch eine Klasse für <textarea>-Elemente.

Zur Unterscheidung der Seitenbäume sollen uns die Laurel Corp. und die Hardy Ltd. dienen.

FrontendLaurelCorporation.yaml:

prototypes:
  standard:
    formElementsDefinition:
      Form:
        renderingOptions:
          translation:
            translationFiles:
              501: 'EXT:form_configsplit/Resources/Private/Language/locallang_laurel.xlf'
          templateRootPaths:
            501: 'EXT:form_configsplit/Resources/Private/Frontend/Laurel/Templates/'
          partialRootPaths:
            501: 'EXT:form_configsplit/Resources/Private/Frontend/Laurel/Partials/'
          layoutRootPaths:
            501: 'EXT:form_configsplit/Resources/Private/Frontend/Laurel/Layouts/'
      Textarea:
        properties:
          elementClassAttribute: 'textarea--laurel'

FrontendHardyLimited.yaml:

prototypes:
  standard:
    formElementsDefinition:
      Form:
        renderingOptions:
          translation:
            translationFiles:
              502: 'EXT:form_configsplit/Resources/Private/Language/locallang_hardy.xlf'
          templateRootPaths:
            502: 'EXT:form_configsplit/Resources/Private/Frontend/Hardy/Templates/'
          partialRootPaths:
            502: 'EXT:form_configsplit/Resources/Private/Frontend/Hardy/Partials/'
          layoutRootPaths:
            502: 'EXT:form_configsplit/Resources/Private/Frontend/Hardy/Layouts/'
      Textarea:
        properties:
          elementClassAttribute: 'textarea--hardy'

Die drei YAML-Konfiguration müssen jetzt mit TypoScript registriert werden.

Im ersten Schritt laden wir die global benötigten Konfigurationen in TYPO3.

ext_localconf.php:

ExtensionManagementUtility::addTypoScriptSetup(
    trim('
         module.tx_form.settings.yamlConfigurations {
            500 = EXT:form_configsplit/Configuration/Form/FormSetup.yaml
        }

        plugin.tx_form.settings.yamlConfigurations {
            // Wichtig: hier nur das globale YAML laden!
            500 = EXT:form_configsplit/Configuration/Form/FormSetup.yaml
        }
    ')
);

Dann erstellen wir zwei TypoScript-Dateien für die Frontend-Konfigurationen. Hier laden wir das YAML nur für plugin.tx_form.

Configuration/TypoScript/Laurel/setup.typoscript:

plugin.tx_form.settings.yamlConfigurations {
    501 = EXT:form_configsplit/Configuration/Form/FrontendLaurelCorporation.yaml
}

Configuration/TypoScript/Hardy/setup.typoscript:

plugin.tx_form.settings.yamlConfigurations {
    502 = EXT:form_configsplit/Configuration/Form/FrontendHardyLimited.yaml
}

Diese beiden TypoScripts stellen wir anschließend als Static Includes in TypoScript-Datensätzen bereit.

Configuration/TCA/Overrides/sys_template.php:

ExtensionManagementUtility::addStaticFile(
    'form_configsplit',
    'Configuration/TypoScript/Laurel/',
    'Form frontend setup: Laurel Corporation'
);

ExtensionManagementUtility::addStaticFile(
    'form_configsplit',
    'Configuration/TypoScript/Hardy/',
    'Form frontend setup: Hardy Limited'
);

Das genügt schon! Ab jetzt sollten alle Formulare in den jeweiligen Seitenbäumen die definierten Template-Pfade, Übersetzungen und Eigenschaften berücksichtigen.

Das TYPO3 Form Framework bringt das Konzept der sogenannten Prototypen mit. Jedes Formular basiert auf einem Prototypen, standardmäßig ist dies der "standard"-Prototyp.
Eigene Prototypen können per YAML konfiguriert und im Form Editor bereitgestellt werden. 

Im Backend kann man einen Prototyp nur beim Anlegen eines neuen Formulars zuweisen, und das hat den folgenden Grund: je Prototyp lässt sich konfigurieren, welche Formularfelder oder Finisher im Form Editor zur Verfügung stehen.

Beachte hierzu auch die offizielle Dokumentation zu Prototypen.

• Prototypen können ihre Basis-Eigenschaften vom "standard"-Prototype erben
• Konfiguration eigener Template-Pfade, CSS-Klassen und XLIFF-Sprachdateien
• Konfiguration der zur Verfügung stehenden Formularfelder, Finisher etc.

• Der Prototyp eines Formulars kann im Form Editor des TYPO3-Backends nicht mehr nachträglich gewechselt werden (da die im Formular verfügbaren Felder auf ihm basieren)
• Die Einrichtung erfordert eine vergleichsweise umfangreiche YAML-Konfiguration

• Komplexere TYPO3-Installationen
• Projekte, in denen Redakteure selbständig Formulare erstellen dürfen

Auch zu diesem Thema habe ich bereits ein eigenes Tutorial verfasst und nachträglich erweitert.