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 alle Content-Elemente des TYPO3-Systems in jeder verfügbaren Konfiguration auf einer einzigen Seite darstellt. 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 öffnet eine URL und sieht alles auf einen Blick.

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: Alle Elemente sind auf einer Seite dargestellt, 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 mit dem TYPO3-Quellcode ausgeliefert wird. Sie muss lediglich im Extension Manager aktiviert werden, eine separate Installation ist nicht nötig.

Die Extension arbeitet auf zwei Ebenen:

• TCA-Generator: Styleguide analysiert die Table Configuration Array (TCA) Definitionen aller registrierten Content-Elemente und generiert daraus Testdatensätze. 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 generieren, aktualisieren und wieder löschen. Die Daten werden in einem eigenen Sys-Folder gespeichert und beeinflussen den regulären Content nicht.
• Frontend-Rendering: Eine spezielle Seite im Seitenbaum zeigt alle generierten Content-Elemente im Frontend-Layout an. 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: Der Sys-Folder mit den Testdaten ist nicht korrekt als Startpunkt konfiguriert, 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. Wenn der Fileadmin-Ordner leer ist oder die Default-Storage-Konfiguration nicht stimmt, bleiben Bildfelder leer. Die Lösung: Mindestens ein Bild manuell in den Fileadmin hochladen, bevor die Testdaten generiert werden.

Problem: Performance-Probleme bei der Styleguide-Seite. Wenn alle Content-Elemente auf einer Seite gerendert werden, kann die Ladezeit bei komplexen Templates 10 bis 15 Sekunden betragen. 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 ist seit TYPO3 v8 als Core System Extension verfügbar und wird mit jeder TYPO3-Version automatisch aktualisiert. Es gibt keine separaten Versionsnummern oder Kompatibilitätsprobleme, da die Extension Teil des Core-Release-Prozesses ist.

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 eine “Reset”-Funktion, die alle Testdaten löscht und neu anlegt.

Für TYPO3 v12 und v13 ist Styleguide ohne Einschränkungen verfügbar. Die Extension profitiert sogar von neuen Core-Features: In v12 wurden zusätzliche Content-Elemente (z.B. verbesserte Textmedia-Varianten) eingeführt, die Styleguide automatisch abdeckt.

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.