Individuelle Inhaltselemente in TYPO3 mit Mask (Leitfaden für 2026)

composer require mask/mask

Im Composer-Modus deklarierst du Mask bereits in der composer.json, daher musst du es nicht zusätzlich in ext_emconf.php eintragen.

Hinweis: Wenn du die Abhängigkeit nachträglich hinzufügst, nachdem TYPO3 Mask bereits installiert und aktiviert wurde, musst du die Lade-Reihenfolge neu aufbauen, indem du deine Extension erneut installierst.

Erforderliches statisches TypoScript und fluid_styled_content

TYPO3 Mask benötigt fluid_styled_content. Stelle sicher, dass es in deinen statischen TypoScript-Bindings im TYPO3 Template Modul eingebunden ist.

Im Composer-Modus kannst du es so installieren:

bash

composer require typo3/cms-fluid-styled-content

Nach der Installation von TYPO3 Mask:

1. Öffne das Template-Modul im TYPO3 Backend
2. Wähle das Template deiner Website aus
3. Füge das statische TypoScript von TYPO3 Mask zu deinem Template hinzu
4. Stelle sicher, dass fluid_styled_content in den statischen Bindings enthalten ist

Diese Schritte stellen sicher, dass die Konfiguration und das Rendering der Inhalte von Mask korrekt funktionieren.

Vorbereiten deines Sitepackages für Mask

Bevor Sie TYPO3 Mask verwenden, richten Sie ein Sitepackage ein (Ihre eigene TYPO3 Extension für Vorlagen und Konfiguration). Dort speichert Mask die generierten Konfigurationen, Vorlagen und Überschreibungen, wodurch Ihr Projekt übersichtlich und leicht zu warten bleibt.

Dein Sitepackage sollte enthalten:

• Einen Extension-Key (z. B. site_vendor oder site_project)
• Eine grundlegende Ordnerstruktur für Configuration, Resources und TCA-Overrides
• Ein registriertes TypoScript-Template für deine Website

Versionierung von LocalConfiguration.php und Mask-Konfiguration für Teams

TYPO3 Mask speichert Konfigurationen in der LocalConfiguration.php sowie in JSON-Dateien innerhalb deines Sitepackages. Für Teams und mehrere Umgebungen (Local, Staging, Production) sollten diese Versionierung unterstützen.

• Lege Mask-Konfigurationsdateien (JSON/YAML/TS) in deinem Sitepackage ab und versioniere sie mit Git
• Vermeide es, dich ausschließlich auf LocalConfiguration.php zu verlassen; dokumentiere Mask-spezifische Einstellungen zusätzlich
• Nutze einen klaren Workflow:
• Workflow:
  • Erstelle oder bearbeite Mask-Elemente in einer lokalen Entwicklungsumgebung
  • Exportiere die Änderungen in dein Sitepackage (Konfiguration + Templates)
  • Committe und deploye sie in andere Umgebungen
• Dies sorgt für konsistente Mask-Setups und erleichtert das Onboarding neuer Teammitglieder.

Schritt-für-Schritt: Dein erstes individuelles Inhaltselement mit Mask 3

Öffne das Mask Backend-Modul

• Finde das Mask-Modul im TYPO3 Backend (unterhalb des Extension Managers)
• Öffne es und gib deinen Sitepackage-Extension-Key ein, falls du dazu aufgefordert wirst
• Stelle sicher, dass dein Sitepackage geladen ist

Definiere das Inhaltselement (Name und Key)

1. Klicke auf „Neues Inhaltselement erstellen“
2. Gib folgende Informationen ein:
   1. Name: z. B. „Teaser Box“, „Hero Banner“
   2. Schlüssel: eindeutig und kleingeschrieben (z. B. teaser_box, hero_banner)
3. Klicke auf „Fertig“. Der Mask-Builder öffnet sich automatisch mit dem Tab „Fields“.

Felder per Drag-and-Drop hinzufügen

• Wechsle zum Tab „Fields“
• Ziehe einen Feldtyp per Drag-and-Drop oder klicke ihn an, um ihn hinzuzufügen
• Konfiguriere das Feld auf der rechten Seite (Label, Beschreibung, Typ)
• Feld-Schlüssel beginnen mit tx_mask_ (z. B. tx_mask_title, tx_mask_teaser_image)

Häufige Optionen:

• Feldschlüssel: Spaltenname in tt_content.
• Bezeichnung: Was die Redakteure sehen.
• Beschreibung: Hilfstext.
• Auf Standard zurücksetzen: Setzt die TCA-Optionen zurück.

Beispiel „Teaser Box“ Felder:

• tx_mask_title (Text)
• tx_mask_teaser_text (Textbereich)
• tx_mask_image (Bild)

Generiertes TCA speichern und prüfen

Beim Speichern:

• Mask generiert automatisch TCA für deine Felder in tt_content
• Das TCA definiert Datenbankspalten, Backend-Darstellung und Validierung

Du schreibst kein TCA manuell, aber es ist wichtig zu wissen, dass es im Hintergrund generiert wird (für Debugging hilfreich)

Element auf einer Seite platzieren und Frontend testen

1. Gehe in das Seitenmodul
2. Klicke auf „Neues Inhaltselement erstellen“ und wähle dein Element aus
3. Füge es hinzu, fülle die Felder aus und speichere
4. Klicken Sie auf „Webseite anzeigen“, um das Frontend zu testen.

Falls es nicht angezeigt wird:

• Prüfe den Fluid-Template-Pfad
• Stelle sicher, dass Mask TypoScript und fluid_styled_content eingebunden sind
• Leere TYPO3 und PHP-Caches

Arbeiten mit TCA und erweiterten Feldoptionen in Mask

Bei der Erstellung individueller Inhaltselemente in TYPO3 geht es nicht nur darum, Felder visuell zu definieren; TYPO3 benötigt TCA (Table Configuration Array), um zu wissen, wie diese gespeichert und angezeigt werden sollen. Mask generiert dieses TCA automatisch für Sie und gibt Ihnen dennoch Kontrolle über wichtige Feldoptionen. Dieser Abschnitt erklärt, was TCA ist, wie Mask es verwendet und welche Feldoptionen Sie konfigurieren können.

Was ist TCA und warum ist es für Mask wichtig?

Das Table Configuration Array (TCA) ist ein zentrales Konzept in der TYPO3-Entwicklung. Es definiert die Struktur und das Verhalten von Datenbanktabellen, die von TYPO3 verwendet werden, um Inhaltselemente zu speichern, einschließlich individueller Inhaltselemente, die mit TYPO3 Mask erstellt wurden. Für Mask teilt TCA TYPO3 mit, wie Ihre individuellen Felder im Backend und Frontend angezeigt und verarbeitet werden sollen.

Wie Mask TCA für Ihre Inhaltselemente verwendet

Wenn Sie individuelle Inhaltselemente mit Mask erstellen, wird TCA automatisch generiert und auf mehrere wichtige Arten verwendet:

• Datenbankstruktur
  TCA definiert die Struktur der Tabelle tt_content, in der Ihre Inhaltselemente gespeichert werden. Für individuelle Felder in Mask definiert TCA, wie Daten gespeichert werden: Spaltennamen, Typen und Beziehungen.
• Feldkonfiguration
  Mit TCA können Sie Feldeigenschaften konfigurieren:
  • Feldtyp: Text, Zahl, Bild, Auswahl usw.
  • Label und Beschreibung
  • Validierungsregeln und Standardwerte
  • Dies gewährleistet Datenkonsistenz und Integrität.
• Integration mit dem TYPO3-Kern
  TCA integriert Ihre von Mask generierten Elemente mit TYPO3-Kern-Funktionen wie Übersetzungen, Versionierung und Zugriffskontrolle.
• Anpassung und Erweiterbarkeit
  TCA bietet umfangreiche Anpassungsoptionen, mit denen Sie das Verhalten und Erscheinungsbild von Elementen anpassen können, ohne TCA manuell zu schreiben.

Kurz gesagt, Mask generiert das gesamte notwendige TCA für Sie, während Sie die wichtigsten Feldoptionen über die Backend-UI steuern.

Häufige Feldoptionen und Zurücksetzen auf Standard

Die meisten Felder in Mask haben diese gemeinsamen Optionen:

• Feldschlüssel
  Eindeutiger Schlüssel für das Feld. Er bestimmt den neuen Spaltennamen in tt_content und muss eindeutig sowie in Kleinbuchstaben geschrieben sein.
• Label
  Das, was Redakteure beim Bearbeiten des Inhaltselements sehen. Es kann für Übersetzungen lokalisiert werden.
• Beschreibung
  Optionaler Hilfetext unter dem Label, der Redakteuren Orientierung gibt.
• Zurücksetzen auf Standard
  Setzt alle TCA-Optionen für das Feld auf die Standardwerte zurück, mit Ausnahme von Label und Beschreibung. Verwenden Sie dies, um Änderungen schnell rückgängig zu machen, ohne das Feld neu zu erstellen.

Diese Optionen erleichtern es, Felder für Redakteure zu konfigurieren und gleichzeitig das zugrunde liegende TCA konsistent und wartbar zu halten.

Verwendung des Tabs „Element-Metadaten“ für eine bessere Redakteurserfahrung

Der Tab Element-Metadaten ist nicht nur für technische Details gedacht; hier machen Sie Ihre Inhaltselemente klar und einfach für Redakteure. Durch das Ausfüllen der Metadaten verbessern Sie, wie Ihre Elemente im Erstellungsassistenten und Backend erscheinen, und helfen Redakteuren dabei, das richtige Element korrekt auszuwählen und zu verwenden.

Was Sie in den Element-Metadaten konfigurieren können

• Kurztitel
  Ein kurzer Titel, der angezeigt wird, wenn Redakteure den Elementtyp auswählen. Wenn er leer bleibt, wird der Standardtitel verwendet.
• Beschreibung
  Eine kurze Erklärung, wofür das Element gedacht ist. Sie erscheint neben dem Titel und Vorschaubild im Erstellungsassistenten und hilft Redakteuren, den Zweck des Elements zu verstehen.
• Icon
  Wählen Sie ein Vorschau-Icon aus FontAwesome. Sie können aus verschiedenen Kategorien auswählen oder per Keyword suchen. Wenn kein Icon festgelegt ist, generiert Mask ein Ersatzsymbol mit dem ersten Buchstaben Ihres Labels.
• Farbe
  Passen Sie die Icon-Farbe an, um die visuelle Unterscheidung zwischen verschiedenen Elementtypen zu verbessern.

Ein paar Minuten, die Sie in das Ausfüllen dieser Felder investieren, machen Ihre Inhaltselemente deutlich redakteurfreundlicher, besonders in größeren Projekten mit vielen Elementen.

Page Templates und Mask (optional, aber leistungsstark)

Mask kann Seitendatensätze und Backend-Layouts (Page Templates) erweitern, sodass Sie Felder zu Seiten hinzufügen können, nicht nur zu Inhaltsbereichen.

• Definieren Sie Felder in der Tabelle pages.
• Felder erscheinen in den Seiteneigenschaften basierend auf dem Backend-Layout.
• Verwenden Sie dies für seitenweite oder seitenspezifische Einstellungen.

Häufige Anwendungsfälle:

• Globales Hero-Bild oder Banner
• seitenspezifische Umschalter („News anzeigen“, „Sidebar ausblenden“)
• seitenspezifische SEO-Überschreibungen
• Seitentyp-Auswahlfelder („Landingpage“, „Blogbeitrag“)

Ideal für Agenturen, die konsistente Seitenstrukturen über Kundenseiten hinweg benötigen.

Mask für Agenturen und größere Projekte strukturieren

Organisieren Sie Mask für die Wiederverwendung über mehrere Kundenseiten hinweg:

• Speichern Sie die Mask-Konfiguration (JSON/YAML) und Templates in Ihrem Sitepackage.
• Verwenden Sie eine klare Ordnerstruktur: Resources/Private/Templates/Content/.
• Exportieren Sie die Mask-Konfiguration nach JSON und committen Sie sie in Git, um sie über verschiedene Umgebungen hinweg zu teilen.
• Verwenden Sie Präfixe:
  • CTypes: site_feature_hero, site_feature_teaser
  • Felder: tx_mask_hero_title, tx_mask_teaser_text
• Gruppieren Sie nach Funktion: Hero, Teaser, FAQ, Formular.

Häufige Probleme und Fehlerbehebung mit TYPO3 Mask

Element nicht sichtbar:

• Prüfen Sie CType in Mask.
• Leeren Sie die Caches.
• Binden Sie das TypoScript von Mask ein.
• Laden Sie Ihr Sitepackage.

Felder werden nicht angezeigt:

• Überprüfen Sie, ob die Feldschlüssel korrekt/eindeutig sind.
• Leeren Sie die Caches und laden Sie die Mask-Konfiguration neu.
• Prüfen Sie TCA-Overrides.
• Laden Sie das Sitepackage vor Mask.

Template wird nicht gerendert:

• Bestätigen Sie den Fluid-Template-Pfad.
• Stimmen Sie den Template-Namen mit der Konfiguration ab.
• Leeren Sie Caches und opcache.
• Binden Sie das TypoScript von Mask ein.

Composer-/Abhängigkeitsprobleme:

• Installieren Sie die Extension erneut, wenn die Abhängigkeit später hinzugefügt wurde.
• Prüfen Sie composer.json.
• Stellen Sie sicher, dass Mask vor dem Sitepackage geladen wird.

Leeren Sie Caches, prüfen Sie die Ladereihenfolge und verifizieren Sie die Konfiguration, um die meisten Probleme zu beheben.

Alternativen zu Mask und wann Kern-Methoden verwendet werden sollten

Auch wenn Mask individuelle Inhaltselemente vereinfacht, bietet TYPO3 auch eine Kern-Methode, um sie ohne zusätzliche Extensions zu erstellen.

Manuelle TYPO3 Kern-Methode

Mit der Kern-Methode erstellen Sie individuelle Inhaltselemente, indem Sie:

• Einen neuen CType definieren und ihn über Page TSconfig zum Assistent für neue Inhaltselemente hinzufügen.
• TCA in Configuration/TCA/Overrides/tt_content.php hinzufügen.
• TypoScript und statische Templates in Ihrem Sitepackage registrieren.
• Fluid-Templates, Partials und Layouts für das Rendering erstellen.

Dies gibt Ihnen volle Kontrolle, indem Sie nur den TYPO3 Kern verwenden, aber Sie müssen die gesamte Konfiguration manuell schreiben und pflegen.

Offizielle Dokumentation:

• Individuellen Inhaltselementtyp erstellen (neueste Version): t3coreapi:adding-your-own-content-elements
• TYPO3 11.5-/12.4-Seiten zu „Individuellen Inhaltselementtyp erstellen“.

Wann Mask zu viel ist

Mask könnte mehr sein, als Sie benötigen, wenn:

• Sie eine sehr kleine Website mit nur ein oder zwei einfachen Elementen haben.
• Ihr Team mit TCA, TypoScript und Fluid vertraut ist und Code bevorzugt.
• Sie wünschen einen minimalen, extension-freien Stack (aus Richtliniengründen).
• Sie eine einmalige Funktion erstellen, die wahrscheinlich nicht wiederverwendet oder von Nicht-Entwicklern gepflegt wird.

In diesen Fällen können die Kern-Methode oder einfache Content Blocks ausreichend sein.

Wann Mask ein klarer Vorteil ist

Mask ist besonders stark für Agenturen und Teams, wenn:

• Sie viele TYPO3-Projekte erstellen und wiederverwendbare Muster wünschen.
• Sie haben Nicht-PHP-Integratoren oder Redakteure, die TCA/TypoScript/PHP nicht anfassen sollten.
• Sie einen visuellen Builder mit Drag-and-drop, JSON-Konfiguration und automatisch generiertem Code wünschen.
• Sie schnell an Inhaltsstrukturen arbeiten möchten, ohne Boilerplate refaktorieren zu müssen.

Verwenden Sie die Kern-Methode, wenn Sie maximale Kontrolle mit minimalen Abhängigkeiten wünschen; verwenden Sie Mask, wenn Sie Geschwindigkeit, Sicherheit und redakteurfreundliche Workflows im großen Maßstab wünschen.

Zusammenfassung und nächste Schritte

Die Verwendung von TYPO3 Mask für individuelle Inhaltselemente ermöglicht es Ihnen, den größten Teil der Low-Level-Arbeit mit TCA und TypoScript zu überspringen und dennoch saubere, flexible Strukturen zu erstellen. Es beschleunigt die Entwicklung, verbessert die Redakteurserfahrung mit besseren Labels, Icons und Metadaten und reduziert Boilerplate im Vergleich zur manuellen Kern-Methode.

Wenn Sie mit Mask und TYPO3 weitergehen möchten, sind gute nächste Themen:

• Mehrsprachige Inhaltselemente mit Mask
  Wie Sie Felder, Labels und Templates so konfigurieren, dass Ihre individuellen Elemente sauber über mehrere Sprachen hinweg funktionieren.
• Mask + KI-Content-Workflows in TYPO3
  Wie Sie Mask-basierte Elemente mit KI-gestützter Inhaltserstellung und Bearbeitung kombinieren, z. B. strukturierte Inhaltsfelder, die KI-Tools speisen.

Fazit

TYPO3 Mask revolutioniert die Inhaltserstellung in TYPO3, indem es eine benutzerfreundliche Möglichkeit bietet, individuelle Inhaltselemente zu erstellen, ohne das gesamte TCA und TypoScript von Hand zu schreiben. Mit seiner intuitiven Oberfläche, flexiblen Konfigurationsoptionen und nahtlosen Integration in den TYPO3 Kern hilft Mask Entwicklern und Agenturen dabei, dynamische, redakteurfreundliche Websites effizient zu erstellen.

Wenn Sie fachkundige Unterstützung bei der Planung oder Umsetzung von Mask in größeren TYPO3-Projekten wünschen, können Sie NITSAN als Ihren TYPO3 Agentur-Partner kontaktieren, um Beratung, Best Practices und langfristige Wartungsstrategien zu erhalten.