Zum Inhalt springen

Worum geht es?

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.

Lösungsweg 1: Auswahlfeld im Form Editor

Im Form Editor kann man ein neues Auswahlfeld (Dropdown) mit Styling-Optionen für den Redakteur ergänzen. Das gewählte Styling wird als Fluid-Variable (hier: formStyleClass) im Formular-Template ergänzt. Damit lässt sich eine CSS-Klasse am Formular setzen.

<div class="form {f:if(condition: form.renderingOptions.formStyleClass, then: ' form--{form.renderingOptions.formStyleClass}')}">
   <formvh:renderRenderable renderable="{form}">
       <!-- […] -->
   </formvh:renderRenderable>
</div>

Vorteile des Auswahlfeldes

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

Empfohlener Verwendungszweck für das Styling-Auswahlfeld

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

Wie konfiguriere ich ein Styling-Auswahlfeld?

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

Lösungsweg 2: Trennung der Frontend-Konfiguration je Seitenbaum

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.

Vorteile der Trennung nach Website

  • 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

Nachteile der Trennung der YAML-Konfiguration

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

Empfohlener Verwendungszweck für die Trennung nach Website

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

Wie trenne ich die Frontend-Konfiguration von der global benötigten Konfiguration?

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.

Global benötigte Formular-Konfiguration

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.

Mögliche Formular-Konfiguration je Seitenbaum

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'

 

YAML-Registrierung

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.

Lösungsweg 3: Eigene Formular-Prototypen

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.

Vorteile selbst definierter Formular-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.

Nachteile selbst definierter Formular-Prototypen

  • 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

Empfohlener Verwendungszweck für eigene Formular-Prototypen

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

Wie konfiguriere ich einen eigenen Formular-Prototyp?

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

Fazit

Ich hoffe, diese Übersicht hilft euch bei der Entscheidung zum gewählten Ansatz. Dabei schließen sich die Lösungen nicht gegenseitig aus – wenn das TYPO3-Projekt es erfordert, können zwei oder sogar alle drei Lösungen miteinander kombiniert werden. Bedenkt dabei nur die ansteigende Komplexität.