Styleguide für TYPO3

Warum Styleguide die wichtigste QA-Extension für TYPO3-Template-Entwickler ist

Template-Entwicklung in TYPO3 hat ein systematisches Qualitätsproblem: Entwickler testen ihre Fluid-Templates mit den Daten, die gerade auf der Website existieren. Aber Content-Elemente haben Dutzende Varianten - Headlines mit und ohne Subheadline, Textblöcke mit 3 Wörtern oder 3 Absätzen, Bilder im Hoch- und Querformat, Tabellen mit 2 oder 20 Spalten. Wer nur die aktuelle Seite prüft, verpasst die Edge Cases, die erst nach dem Launch auffallen.

Die Styleguide-Extension löst dieses Problem, indem sie automatisch einen Demo-Seitenbaum anlegt, der jedes Content-Element des Core auf einer eigenen Seite zeigt. Damit sieht der Entwickler sofort, ob sein CSS und seine Templates alle Varianten korrekt abbilden.

Typische Einsatzszenarien

Template-Entwicklung bei Relaunch-Projekten. Ein Unternehmen beauftragt einen TYPO3-Relaunch mit neuem Corporate Design. Der Frontend-Entwickler erstellt Fluid-Templates für alle Content-Elemente. Ohne Styleguide muss er für jedes Element Testdaten im Backend anlegen - ein Prozess, der bei 30+ Content-Elementen Stunden dauert. Styleguide generiert alle Testdaten automatisch: Text-Elemente in verschiedenen Längen, Bilder in verschiedenen Seitenverhältnissen, Listen, Tabellen, Uploads, Formulare. Der Entwickler klickt sich durch die Demo-Seiten und sieht jedes Element im Frontend.

Regressionstests nach TYPO3-Updates. Ein TYPO3-Update von v11 auf v12 ändert das Rendering einzelner Content-Elemente subtil. Ein Textmedia-Element rendert plötzlich ein zusätzliches Wrapper-Div, das das CSS-Layout bricht. Ohne Styleguide fällt das erst auf, wenn ein Redakteur den Fehler auf einer Live-Seite meldet. Mit Styleguide sieht der Entwickler nach dem Update sofort, welche Elemente sich verändert haben.

Abstimmung zwischen Design- und Entwicklungs-Team. Designer liefern Figma-Mockups für 10 Content-Elemente. Aber wie sehen die restlichen 25 Standard-Elemente im neuen Design aus? Styleguide macht diese Lücke sichtbar: Jedes Element hat seine eigene Demo-Seite, fehlende Gestaltungen fallen sofort auf. Gosign nutzt Styleguide in jedem Relaunch-Projekt als Abnahme-Tool für das Design-Team.

Technische Architektur

Styleguide ist eine offizielle TYPO3 Core System Extension, die seit v13 im Core-Repository liegt, aber nicht zum Quellpaket gehört. Sie wird über Composer (typo3/cms-styleguide), bis v12 auch aus dem TER, installiert und dann aktiviert.

Die Extension arbeitet auf zwei Ebenen:

• TCA-Generator: Styleguide legt für seine eigenen Demo-Tabellen (tx_styleguide_*) Testdatensätze an, die nahezu alle TCA-Feldtypen des Backends zeigen. Für jedes Feld wird ein sinnvoller Testwert erzeugt - Texte in verschiedenen Längen, Bilder aus dem FAL, Relationen zu anderen Records.
• Backend-Modul: Über das Backend-Modul kann der Administrator die Testdaten anlegen und wieder löschen. Die Daten liegen in eigenen Seitenbäumen („styleguide TCA demo“, „styleguide frontend demo“) und beeinflussen den regulären Content nicht.
• Frontend-Rendering: Ein eigener Seitenbaum zeigt die generierten Content-Elemente im Frontend-Layout an, je Inhaltstyp eine Seite. Der Entwickler sieht die Elemente genau so, wie sie auf der Live-Website erscheinen würden.

Styleguide hat keine externen Abhängigkeiten. Da es eine Core-Extension ist, wird es automatisch mit jedem TYPO3-Update aktualisiert und ist immer kompatibel mit der jeweiligen TYPO3-Version.

Wichtig: Styleguide generiert keine Testdaten für Custom Content Elements (z.B. Mask oder DCE). Es deckt nur die Core-Content-Elemente ab. Für Custom Elements muss der Entwickler eigene Testdaten anlegen oder ein ergänzendes Tool verwenden.

Häufige Probleme und Lösungen

Problem: Styleguide-Seite zeigt leere Bereiche. Die Testdaten wurden generiert, aber die Frontend-Seite zeigt nicht alle Elemente. Ursache: Die Demo-Seiten laufen als eigene Site mit eigenem Root-Template statt mit dem der Website, oder das TypoScript-Setup für die Styleguide-Seite fehlt. Die Lösung: Im Backend-Modul prüfen, ob der Seitenbaum korrekt angelegt wurde, und sicherstellen, dass das Root-Template der Styleguide-Seite das gleiche TypoScript wie die reguläre Website verwendet.

Problem: Bilder fehlen in den generierten Testdaten. Styleguide versucht, Testbilder über das FAL (File Abstraction Layer) einzubinden. Die Beispielbilder bringt Styleguide selbst mit und kopiert sie in den Speicher mit der UID 1; fehlt dieser oder stimmt seine Konfiguration nicht, bleiben Bildfelder leer. Die Lösung: Den Speicher fileadmin (UID 1) prüfen, bevor die Testdaten generiert werden.

Problem: Performance-Probleme bei der Styleguide-Seite. Das Anlegen der Demo-Seitenbäume erzeugt viele Datensätze auf einmal und dauert laut Doku einige Sekunden. Das ist für QA akzeptabel, kann aber den Server bei gleichzeitigem Zugriff belasten. Die Lösung: Styleguide nur auf der Entwicklungs- oder Staging-Umgebung aktivieren, nie auf dem Live-System.

Migration und Versions-Kompatibilität

Styleguide liegt seit TYPO3 v13 im Core-Repository und erscheint seitdem mit jeder TYPO3-Version. Bis v12 hatte es eigene Versionsnummern, zuletzt 12.0.5; seit v13 folgen sie dem Core-Release.

Bei einem TYPO3-Upgrade sollten die Styleguide-Testdaten nach dem Update neu generiert werden. Die alten Testdaten können auf dem neuen System inkonsistent sein, weil sich TCA-Definitionen zwischen TYPO3-Versionen ändern. Das Backend-Modul bietet dafür je eine Schaltfläche zum Löschen und zum Neuanlegen der Demo-Seitenbäume.

Für TYPO3 v12 und v13 ist Styleguide ohne Einschränkungen verfügbar. Die Extension zieht mit neuen Core-Features mit: Laut README halten die Core-Entwickler sie aktuell, wenn der Core Funktionen hinzufügt oder abkündigt.

Gosign integriert Styleguide in jeden TYPO3-Relaunch als festen Bestandteil des QA-Prozesses. Die Styleguide-Seite wird auf der Staging-Umgebung als permanente Referenz angelegt und dient dem Design-Team als Abnahme-URL. Änderungen an Fluid-Templates oder CSS werden dort sofort sichtbar, ohne dass jemand Testcontent auf einzelnen Seiten anlegen muss. Für Enterprise-Kunden mit mehreren Marken oder Mandanten wird pro Mandant eine eigene Styleguide-Seite generiert, um markenspezifische Template-Varianten zu vergleichen.