Unterschiedliche Templates per Prototype im TYPO3 Form Framework

Dieses Tutorial hat in seiner Ursprungsversion von 2017 die ersten Schritte mit dem damals neuen TYPO3 Form Framework beschrieben: von der Grund­konfiguration im eigenen Sitepackage bis zu individuellen Formular-Templates, für die ich den Weg eines neuen Prototypen gewählt hatte.

In seiner heutigen Fassung liegt der Schwerpunkt auf der Frage, wie ihr mittels Prototypen Formular-spezifische Templates zuweist und wie ihr (und eure Redakteure) mit mehreren Prototypen arbeiten könnt.
Ich habe mich aber dagegen entschieden, die Grundkonfiguration komplett aus dem Tutorial zu entfernen.

Dieses Tutorial beschreibt eine von drei Lösungen für individuelle Formular-Templates. Zum Vergleich der Lösungswege mit Vor-/Nachteilen und passenden Anwendungsfällen.

Die Konfiguration der Form-Extension erfolgt komplett über YAML: Diese Auszeichnungs­sprache wurde mit Version 8 in TYPO3 eingeführt und ist dort auch für die Konfiguration des neuen Richtext-Editors CKEditor zuständig. Gerade für das Form Framework gibt es eine Vielzahl von Konfigurationen, da es bewusst flexibel gehalten wurde.

Ein großer Vorteil gegenüber den erprobten Formular-Extensions wie Powermail ist, dass jedes erstellte Formular inklusive Felder, Validierungen und der Verarbeitung der übermittelten Daten (über die sogenannten Finisher) als YAML-Datei exportiert wird. Diese Dateien werden vom Form-Backend-Modul per Default im fileadmin gespeichert, können aber in Template-Extensions ausgelagert und versioniert werden. So ist es einfach möglich, Formulare als Gesamtpaket in andere TYPO3-Installationen zu übertragen.

Mittels YAML-Konfiguration kann man auch einrichten, dass man die in eine Extension ausgelagerten Formulare wieder im Backend-Modul bearbeiten kann. Diese Einstellung füge ich gleich ebenfalls hinzu.

Als Speicherort dient in diesem Tutorial ein Sitepackage, dessen Ordnerstruktur auf TYPO3 Extbase-Extensions beruht:

• ext_typoscript_setup.typoscript
  Die hier enthaltenen Konfigurationen werden direkt nach Installation der Extension verwendet.
• Configuration/Yaml/CustomFormSetup.yaml
  Mit dieser Datei konfigurieren wir das Form Framework nach unseren Vorstellungen.
• Resources/Private/Forms/
  Hier werden die erstellen Formulare gespeichert.
• Resources/Private/Frontend/Partials/
  Speicherort für angepasste Frontend Partials.
• Resources/Private/Frontend/Templates/
  Speicherort für angepasste Frontend Templates.

Analog hierzu speichert man geänderte Templates für das Backend-Modul im Unterordner Resources/Private/Backend/Templates/. Beachtet bitte, dass ihr innerhalb dieser Ordner weiterhin die Ordnerstruktur und Dateibezeichnung von EXT:form beibehaltet: Das kleine Partial für den Pflichtfeld-Hinweis müsste im Ordner Resources/Private/Frontend/Partials/Field/Required.html gespeichert werden.

Anmerkung: Die für ein Sitepackage notwendige Extension-Konfiguration (z.B. composer.json) ist hier nicht extra beschrieben.

Jedes Formular basiert auf einem sogenannten Prototyp. Für diesen Prototyp werden alle erforderlichen Formularfelder, Validatoren und Finisher konfiguriert. Auch die Pfade zu Frontend-Templates und XLIFF-Sprachdateien werden im Prototyp definiert.

Alle im Form Framework mitgelieferten Konfigurationen beziehen sich auf den standard-Prototyp.

Die Konfiguration eigener Prototypen hat diverse Vorteile. Prototypen beeinflussen nicht nur das Frontend, sondern auch den Form Editor im Backend sowie die Plugin-Overrides.
Für Formulare, die auf einem eigenen Prototyp basieren, könnt ihr beispielsweise:

• abweichende Template-Pfade und CSS-Klassen definieren
• im Form Editor nur noch Textfelder und Checkboxen zur Verfügung stellen und
• alle Finisher bis auf den SaveToDatabase-Finisher entfernen;
• im Plugin den Override eines neuen Finishers erlauben

Die Grundeinrichtung steht, im nächsten Schritt ergänzen wir in der CustomFormSetup.yaml einen eigenen Prototyp:

TYPO3:
  CMS:
    Form:
      prototypes:
        complaintForm:
          __inheritances:
            10: 'TYPO3.CMS.Form.prototypes.standard'
          formElementsDefinition:
            Form:
              renderingOptions:
                templateRootPaths:
                  100: 'EXT:form_examples/Resources/Private/Frontend/Templates/ComplaintForm/'
                partialRootPaths:
                  100: 'EXT:form_examples/Resources/Private/Frontend/Partials/ComplaintForm/'
                layoutRootPaths:
                  100: 'EXT:form_examples/Resources/Private/Frontend/Layouts/ComplaintForm/'
            SingleSelect:
              properties:
                elementClassAttribute: 'custom-select'

Dieser neue Prototyp erhält den (frei wählbaren) Namen complaintForm. Mit dem Operator __inheritances kopieren wir die aktuelle Konfiguration des Prototyp standard. Alternativ könnten wir die im eigenen Prototyp verfügbaren Formularfelder, Validatoren und Finisher selektiv ergänzen.

Anschließend definieren wir die gewünschten Template-Pfade sowie eine spezielle CSS-Klasse für Select-Felder.

Der neue Formular-Prototyp könnte ab jetzt von TYPO3-Integratoren manuell in YAML zugewiesen werden.

Den Prototypen, das Beispielformular und die weitere Konfiguration findet ihr in der TYPO3-Extension "form_examples". Für den Form Manager habe ich dort weitere Prototypen und Formularvorlagen ergänzt. Die vor kurzem aktualisierte Fassung der Extension ist für TYPO3 v10 bis v12 in eigenen, jeweils optimierten Branches verfügbar.

form_examples auf GitHub