Wie man benutzerdefinierte Elemente in TYPO3 erstellt

Eine Backend-Vorschau ist optional, hilft Redakteuren jedoch dabei, den Inhalt eines benutzerdefinierten Content Elements zu verstehen, ohne es öffnen zu müssen.

Es gibt zwei gängige Möglichkeiten, eine Vorschau hinzuzufügen:

Fluid Preview

Verwenden Sie ein Fluid Preview Template über PageTSconfig:

mod.web_layout.tt_content.preview.codeblock = EXT:codeblock/Resources/Private/Templates/Preview/Codeblock.html

Dies ist nützlich für einfache Vorschauen, die auf gespeicherten Feldwerten basieren.

Benutzerdefinierter Preview Renderer

Für mehr Kontrolle können Sie einen benutzerdefinierten Preview Renderer verwenden.

$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['cms/layout/class.tx_cms_layout.php']['tt_content_drawItem']['content-codeblock']
   = \Vendor\YourExtensionKey\Hooks\PageLayoutView\NewContentElementPreviewRenderer::class;

Verwenden Sie einen benutzerdefinierten Renderer, wenn die Vorschau spezielle Logik, formatierte Ausgaben oder eine individuelle Backend-Darstellung benötigt.

8. Einen DataProcessor hinzufügen

Ein DataProcessor ist hilfreich, wenn das Content Element vor dem Rendering eine zusätzliche Datenverarbeitung benötigt.

Verwenden Sie ihn für:

• Dateien
• Verknüpfte Datensätze
• Externe Daten
• Array-Transformation
• Syntax-Highlighting
• Verarbeitung benutzerdefinierter Felder

Beispiel:

public function process(
   ContentObjectRenderer $cObj,
   array $contentObjectConfiguration,
   array $processorConfiguration,
   array $processedData
) {
   $fieldName = $processorConfiguration['field'];
   $targetVariableName = $cObj->stdWrapValue('as', $processorConfiguration, 'bodytext_formatted');

   $highlight = GeneralUtility::makeInstance(Highlighter::class);

   if (!$processedData['data']['code_language']) {
       $languages = $highlight->listLanguages();
       $highlight->setAutodetectLanguages($languages);
       $highlighted = $highlight->highlightAuto($processedData['data'][$fieldName]);
   } else {
       $highlighted = $highlight->highlight(
           $processedData['data']['code_language'],
           $processedData['data'][$fieldName]
       );
   }

   $processedData[$targetVariableName]['code'] = $highlighted->value;
   $processedData[$targetVariableName]['language'] = $highlighted->language;

   return $processedData;
}

Ein DataProcessor hält die Logik außerhalb des Fluid Templates und sorgt für ein saubereres Rendering.

9. TypoScript-Konfiguration hinzufügen

TYPO3 benötigt eine TypoScript-Konfiguration, um das benutzerdefinierte Content Element im Frontend darzustellen.

tt_content.codeblock =< lib.contentElement
tt_content.codeblock {
  templateName = Codeblock
  templateRootPaths.0 = EXT:codeblock/Resources/Private/Templates

  dataProcessing.1567071612 = NITSAN\Codeblock\DataProcessing\HighlightProcessor
  dataProcessing.1567071612 {
      field = bodytext
      as = bodytext_formatted
  }
}

Dies verbindet den benutzerdefinierten CType mit seinem Fluid Template und dem optionalen DataProcessor.

10. Fluid Template hinzufügen

Erstellen Sie das Fluid Template, das die Frontend-Ausgabe steuert.

Beispiel:

<f:layout name="Default" />

<f:section name="Main">
   <pre>
       <code class="hljs {bodytext_formatted.language}">
           {bodytext_formatted.code -> f:format.raw()}
       </code>
   </pre>
</f:section>

Verwenden Sie eine rohe Ausgabe nur dann, wenn der Inhalt vertrauenswürdig oder ordnungsgemäß bereinigt wurde. Bei normalen Redakteurs-Eingaben sollte die Ausgabe standardmäßig escaped werden, um Sicherheitsprobleme zu vermeiden.

Moderne Option: Benutzerdefinierte Elemente mit TYPO3 Content Blocks erstellen

Kurze Antwort: Content Blocks sind eine vereinfachte Möglichkeit, strukturierte Content Elements in TYPO3 zu definieren.

Anstatt jeden Bestandteil manuell mit TCA, PageTSconfig, TypoScript und Backend-Konfiguration einzurichten, ermöglichen Content Blocks Entwicklern, Content Elements über eine kompaktere Struktur zu definieren. Ein typischer Content Block enthält eine config.yaml-Datei, ein Fluid Template, optionale Assets und Sprachlabels.

Content Blocks sind besonders geeignet, wenn Sie schnell strukturierte Elemente wie Hero-Bereiche, CTA-Blöcke, Kartenlayouts, Slider, Teaser oder wiederverwendbare Landingpage-Abschnitte erstellen möchten. Sie sind besonders hilfreich in TYPO3 v13- und v14-Projekten, bei denen Teams einen saubereren und moderneren Workflow für benutzerdefinierte Content Elements wünschen.

Verwenden Sie die Core CType-Methode, wenn das Projekt vollständige Kontrolle, komplexe TCA-Konfiguration, individuelle Verarbeitung oder langfristige Flexibilität auf niedriger Ebene benötigt. Verwenden Sie Content Blocks, wenn das Ziel darin besteht, strukturierte Content Elements schneller mit weniger manueller Konfiguration zu erstellen.

TYPO3 v14 Hinweise: Visual Editor und Redakteurs-Erfahrung

TYPO3 v14 legt einen stärkeren Fokus auf die Redakteurs-Erfahrung. Der Visual Editor unterstützt einfachen Text und Rich-Text-Bearbeitung, das Verschieben von Inhalten per Drag & Drop, hervorgehobene bearbeitbare Felder und eine berechtigungsbasierte Bearbeitung über TYPO3-APIs.

Dies ist für benutzerdefinierte Content Elements wichtig, da Templates nicht nur korrekt im Frontend dargestellt werden sollten. Sie müssen auch für Redakteure einfach verständlich und verwaltbar sein.

Bei der Erstellung benutzerdefinierter Elemente für TYPO3 v14 sollten Sie prüfen:

• Einfache Textfelder lassen sich leicht bearbeiten
• Rich-Text-Felder werden sicher und korrekt dargestellt
• Bearbeitbare Felder sind im Bearbeitungsworkflow eindeutig erkennbar
• Content Elements können verschoben werden, ohne das Layout zu beschädigen
• Templates sind für eine redakteursfreundliche Ausgabe strukturiert
• Backend-Berechtigungen und Feldzugriffe funktionieren wie erwartet

Ein gutes benutzerdefiniertes Content Element sollte Redakteuren ermöglichen, Inhalte zu aktualisieren, ohne erraten zu müssen, wie das Layout funktioniert.

Best Practices für SEO, Barrierefreiheit und Performance

Benutzerdefinierte TYPO3 Content Elements sollten für Benutzer, Redakteure, Suchmaschinen und eine langfristige Wartung entwickelt werden.

SEO Best Practices

• Eine klare semantische Überschriftenstruktur beibehalten
• Doppelte H1-Tags innerhalb benutzerdefinierter Elemente vermeiden
• Klare und aussagekräftige Link-Bezeichnungen verwenden
• Wichtige Texte sichtbar im HTML ausgeben
• Strukturierte Inhalte anstelle von reinen Layout-Inhalten unterstützen
• Wichtige Inhalte nicht ausschließlich hinter JavaScript-basierter Ausgabe verstecken

Best Practices für Barrierefreiheit

• Semantische HTML-Elemente verwenden
• Alt-Text-Felder hinzufügen, wenn Bilder verwendet werden
• Barrierefreie Buttons und Links verwenden
• Tastaturnavigation funktional halten
• Rein visuelle Inhalte ohne Textalternativen vermeiden
• Kontraste, Fokuszustände und gut lesbare Abstände prüfen

Performance Best Practices

• CSS und JavaScript nur laden, wenn das Element verwendet wird
• Unnötige Frontend-Assets vermeiden
• Optimierte Bilder verwenden
• TYPO3-Caching korrekt einsetzen
• DataProcessor-Logik leichtgewichtig halten
• Keine umfangreichen externen Aufrufe während des Renderings durchführen

Ein benutzerdefiniertes Content Element sollte nicht nur korrekt aussehen. Es sollte schnell laden, barrierefrei bleiben, SEO unterstützen und während zukünftiger TYPO3 updates einfach wartbar sein.

Häufige Fehler bei der Erstellung benutzerdefinierter TYPO3 Elemente

Benutzerdefinierte TYPO3 Content Elements funktionieren häufig nicht, weil kleine Einrichtungsschritte übersehen werden. Dies sind die häufigsten Fehler, die vermieden werden sollten:

• CType ist nicht korrekt registriert
• Element erscheint nicht im Backend-Wizard
• TCA-Override-Datei befindet sich im falschen Pfad
• TYPO3-Cache wurde nach Änderungen nicht geleert
• TypoScript-Setup wurde nicht eingebunden
• Fluid Template-Pfad ist falsch
• Datenbankfeld wurde im Code hinzugefügt, aber nicht in der Datenbank angewendet
• Frontend-Ausgabe wird nicht gerendert
• Backend-Vorschau fehlt oder funktioniert nicht
• Sprachlabels fehlen
• Rohe Ausgabe wird ohne korrekte Escape- oder Bereinigungsmaßnahmen verwendet

Diese Probleme lassen sich normalerweise leicht beheben, wenn Dateistruktur, CType-Key, TCA-Setup, TypoScript-Konfiguration und Template-Pfade Schritt für Schritt überprüft werden.

Fehlerbehebung: Benutzerdefiniertes Element wird nicht angezeigt oder gerendert

Beispiel für ein benutzerdefiniertes Element: CTA-Box

Eine CTA-Box ist ein praktisches TYPO3 Content Element, da sie für Agenturen, Marketingteams und Redakteure nützlich ist. Sie bietet Redakteuren eine feste Struktur, anstatt dass sie denselben Bereich auf jeder Seite manuell erstellen müssen.

Eine einfache CTA-Box kann Folgendes enthalten:

• Überschrift
• Fließtext
• Button-Text
• Button-Link
• Bild
• Hintergrundstil

Diese Art von benutzerdefiniertem Content Element eignet sich besonders für Landingpages, Serviceseiten, Kampagnenseiten und Blog-CTAs. Entwickler können die Frontend-Ausgabe mit einem Fluid Template steuern, während Redakteure nur die benötigten Felder verwalten.

Checkliste für benutzerdefinierte Elemente vor dem Go-Live

Bevor ein benutzerdefiniertes TYPO3 Content Element veröffentlicht wird, prüfen Sie den vollständigen Workflow von der Backend-Bearbeitung bis zur Frontend-Ausgabe.

• CType funktioniert im TYPO3-Backend
• Element erscheint im Assistenten „Neues Inhaltselement“
• Felder werden korrekt gespeichert
• Frontend wird korrekt gerendert
• Fluid Template-Pfad ist korrekt
• Backend-Vorschau ist für Redakteure verständlich
• Sprachlabels sind hinzugefügt
• Ausgabe ist escaped oder bereinigt
• Barrierefreiheit wurde getestet
• Mobile Darstellung wurde getestet
• Cache-Verhalten wurde geprüft
• Redakteurs-Workflow wurde getestet
• TYPO3 v13/v14-Kompatibilität wurde geprüft

Ein benutzerdefiniertes Content Element ist erst dann bereit für den Go-Live, wenn Entwickler und Redakteure es fehlerfrei verwenden können.

Fazit

Die Erstellung eines benutzerdefinierten Content Elements in TYPO3 gibt Entwicklern bessere Kontrolle über Struktur, Felder, Frontend-Ausgabe und Redakteurs-Erfahrung.

Verwenden Sie die Core CType-Methode, wenn das Projekt vollständige Kontrolle über TCA, TypoScript, Fluid Templates, Backend-Vorschau und individuelle Verarbeitung benötigt. Verwenden Sie Content Blocks, wenn Sie schneller strukturierte Content Elements mit einer einfacheren Einrichtung erstellen möchten. Verwenden Sie Plugins oder Extensions, wenn die Funktion dynamische Logik, Datensätze, Formulare, Filter, Listen oder Workflows benötigt.

Das beste benutzerdefinierte TYPO3 Content Element ist nicht nur technisch korrekt. Es sollte einfach für Redakteure nutzbar, sicher für zukünftige Upgrades, leistungsoptimiert, barrierefrei und für SEO richtig strukturiert sein.