TypoScript ist kein Programm, sondern ein Objektbaum
Wer die Sprache wie PHP liest, sucht nach Schleifen und findet keine. Wer sie als Baum aus Objekten liest, versteht in einer Stunde, warum die Reihenfolge alles entscheidet.
KI-generiertDieses Bild wurde mit KI erzeugt · Yves Hoppe / KI / cmt
Der Fehler steckt fast nie in der Zeile, die du gerade schreibst
TypoScript sieht aus wie Code, verhält sich aber nicht so. Es gibt keinen Ablauf von oben nach unten, der irgendwann endet. Jede Zeile setzt eine Eigenschaft an einem Pfad, und was am Ende gilt, ist die Summe aller Zeilen, die für diese eine Seite zusammengetragen wurden. Die Frage bei einem Problem lautet deshalb selten, was deine Zeile tut, sondern welche Zeile danach noch kommt.
Unangenehm daran ist, dass nichts abstürzt. Ein Tippfehler im Objektpfad wirft keine Meldung, er legt still eine Eigenschaft an, die niemand liest. Eine doppelt gesetzte Einstellung meldet keinen Konflikt, sie gewinnt oder verliert einfach. Wer dann Zeilen umstellt, bis das Ergebnis stimmt, hinterlässt eine Konfiguration, die beim nächsten Upgrade niemand mehr auseinandernehmen kann, weil auch der eigene Zustand von damals nicht mehr begründbar ist.
Dazu kommt die Verwechslung mit TSconfig. Beide sehen identisch aus, beide vererben sich im Seitenbaum, beide heißen im Gespräch gern einfach TypoScript. Nur konfiguriert das eine die Ausgabe im Frontend und das andere das Backend. Eine Einstellung an der falschen Stelle tut schlicht nichts, und weil sie nichts tut, sucht man den Fehler in der Einstellung selbst statt am Ort.
KI-generiertDieses Bild wurde mit KI erzeugt · Yves Hoppe / KI / cmt
Eine Zeile TypoScript, Bestandteil für Bestandteil
Fast jede Zeile im Setup ist nach demselben Muster gebaut. Wenn du die fünf Bestandteile einmal auseinandergenommen hast, liest sich auch fremde Konfiguration ohne Nachschlagen.
Der Aufbau
page.10 = FLUIDTEMPLATE
page.10.settings.farbe = {$sitepackage.farbe} - 01 Das Objekt an der Wurzel
pagepage ist das Objekt, aus dem TYPO3 die Seite baut, angelegt mit page = PAGE. Alles, was im Frontend erscheint, hängt irgendwo darunter. Ein Tippfehler an dieser Stelle erzeugt keinen Fehler, sondern nur einen neuen Zweig, den nie jemand ausliest.
- 02 Der Nummernschlüssel und der Typ
.10Zahlen sortieren die Kindobjekte, sie zählen nichts. page.10 wird vor page.20 ausgegeben, und die Lücken dazwischen sind Absicht: So lässt sich später etwas dazwischenschieben, ohne alles neu zu nummerieren. Die erste Zeile legt den Typ fest, und erst dadurch kennt page.10 überhaupt eine Eigenschaft namens settings.
- 03 Die Eigenschaft
settings.farbePunkte trennen die Ebenen. Welche Eigenschaften zulässig sind, hängt allein am Typ des Objekts, nicht am Pfad. Deshalb wirkt dieselbe Eigenschaft an einer Stelle und an einer anderen nicht, ohne dass irgendwo eine Warnung erscheint.
- 04 Der Zuweisungsoperator
=Er setzt den Wert neu. Daneben gibt es das Kleinerzeichen für eine einmalige Kopie, die Schreibweise mit Gleich und Kleiner für eine Referenz, das Größerzeichen zum Löschen und die Schreibweise mit Doppelpunkt für eingebaute Funktionen wie addToList.
- 05 Der Verweis in die Constants
{$sitepackage.farbe}Geschweifte Klammer mit Dollarzeichen holt einen Wert aus den Constants. Damit steht die Stellschraube an einer Stelle, an der sie auch jemand ändern kann, der das Setup nie geöffnet hat.
Wenn es nicht funktioniert
Das siehst du
Deine Zeile steht im Setup, im Objektbrowser taucht sie auf der betroffenen Seite trotzdem nicht auf.
Warum
Die Vererbung ist unterwegs abgeschnitten, weil eine Seite dazwischen einen eigenen Template-Datensatz mit gesetztem Clear-Feld trägt.
Was hilft
Den Objektbrowser von der betroffenen Seite aus öffnen statt von der Startseite und im Seitenbaum nach dem zweiten Template-Datensatz suchen.
Das siehst du
Der Wert ist gesetzt, im Frontend gilt trotzdem ein anderer.
Warum
Eine später eingebundene Konfiguration setzt denselben Pfad noch einmal. Es gewinnt nicht die speziellere Zeile, sondern die letzte.
Was hilft
Die eigene Konfiguration hinter den mitgelieferten einbinden und den Endzustand im Objektbrowser prüfen, nicht die eigene Datei.
Das siehst du
Eine Backend-Einstellung, etwa ein ausgeblendetes Feld im Formular, bleibt wirkungslos.
Warum
Sie steht im TypoScript-Setup statt in der Seiten-TSconfig. Beide Sprachen sehen gleich aus, greifen aber an völlig verschiedenen Stellen.
Was hilft
Alles mit TCEFORM, TCEMAIN oder mod. in die Seiten-TSconfig verschieben und dort erneut testen.
Das siehst du
Nach einer Änderung am Original ändert sich auch die vermeintliche Kopie mit.
Warum
Kopiert wurde mit der Schreibweise aus Gleich und Kleiner, und das ist eine Referenz, kein Duplikat.
Was hilft
Für eine echte Kopie nur das Kleinerzeichen verwenden, das übernimmt den Zweig einmalig beim Einlesen und koppelt ihn danach ab.
Das siehst du
Alles unterhalb einer Bedingung verhält sich, als wäre sie dauerhaft aktiv.
Warum
Der Block ist nicht geschlossen, deshalb hängt der gesamte Rest der Datei mit in der Bedingung.
Was hilft
Jede Condition mit dem Schlüsselwort END abschließen und den Objektbaum einmal mit und einmal ohne erfüllte Bedingung vergleichen.
Vom Seitenaufruf zum fertigen Objektbaum in fünf Schritten
- 01 TYPO3 sammelt alle Constants und ersetzt damit die Platzhalter im Setup.
- 02 Das Setup wird in der Reihenfolge der Einbindung von oben nach unten zusammengelegt.
- 03 Conditions schalten einzelne Blöcke je nach Sprache, Kontext oder Anmeldung frei.
- 04 Übrig bleibt ein Objektbaum, den du im Backend vollständig durchklicken kannst.
- 05 Erst danach rendert TYPO3 das Objekt unter page und baut daraus die Seite.
Was du danach am Objektbaum ablesen kannst
Der Sprung passiert nicht beim Auswendiglernen von Eigenschaften, sondern in dem Moment, in dem du eine Zeile nicht mehr als Befehl liest, sondern als Pfad, Eigenschaft und Wert. Ab da beantwortest du die meisten Fragen im Backend statt im Editor.
Objekte statt Anweisungen lesen
Jede Zeile setzt an einem Pfad eine Eigenschaft. Der Typ des Objekts entscheidet, welche Eigenschaften es überhaupt kennt: Ein FLUIDTEMPLATE kennt file und settings, ein TEXT kennt value und stdWrap. Erraten lässt sich das nicht, die Liste steht in der TypoScript-Referenz.
Die fünf Operatoren auseinanderhalten
Das Gleichheitszeichen setzt einen Wert, das Kleinerzeichen kopiert einen ganzen Zweig einmalig, die Kombination aus Gleich und Kleiner legt eine Referenz, die spätere Änderungen mitnimmt, das Größerzeichen löscht, und die Kombination aus Doppelpunkt und Gleichheitszeichen ruft eine der wenigen eingebauten Funktionen auf, geschrieben als pfad := addToList(15).
Constants als Stellschrauben begreifen
In die Constants gehört alles, was jemand später ändern will, ohne das Setup zu öffnen: Farben, Pfade, Anzahl der Treffer pro Seite. Im Setup steht die Maschine, in den Constants stehen die Regler dafür.
TypoScript von TSconfig trennen
Alles, was mit TCEFORM, TCEMAIN oder mod. beginnt, konfiguriert das Backend und gehört in die Seiten-TSconfig. Alles unter page, lib oder config beschreibt die Ausgabe und gehört ins Setup. Die beiden haben getrennte Referenzhandbücher, das ist der schnellste Test.
Conditions ohne Nebenwirkung schreiben
Eine Bedingung schaltet einen Block frei, sie verzweigt nicht innerhalb eines Werts. Wird sie nicht wieder geschlossen, hängt der gesamte Rest der Datei mit darin, und die Wirkung zeigt sich an Stellen, an denen niemand sucht.
Im Objektbrowser nachsehen statt raten
Der aufgelöste Objektbaum lässt sich im Backend für jede einzelne Seite durchklicken. Damit siehst du den Endzustand nach allen Einbindungen, Constants und Bedingungen, und nicht das, was in deiner Datei steht.
KI-generiertDieses Bild wurde mit KI erzeugt · Yves Hoppe / KI / cmt
Ein Baum aus Objekten, kein Ablauf
Die Wurzel der Ausgabe heißt page. Mit page = PAGE legst du fest, dass an dieser Stelle eine Seite entsteht, darunter hängen nummerierte Kindobjekte mit eigenen Typen. Gängig sind FLUIDTEMPLATE für die Ausgabe über eine Fluid-Datei, CONTENT zum Einsammeln von Datensätzen, HMENU für Menüs, COA als Sammelobjekt und TEXT für eine einzelne Ausgabe. Ein Objekt bekommt zuerst seinen Typ, danach setzt du dessen Eigenschaften.
Schleifen und Funktionen fehlen nicht aus Nachlässigkeit, sie wären an dieser Stelle sinnlos. Die Aufzählung steckt bereits im Objekt: CONTENT läuft über die gefundenen Datensätze, HMENU über die Seiten eines Zweigs. Wenn du in TypoScript eine Schleife vermisst, suchst du in Wahrheit das Objekt, das die Wiederholung schon mitbringt.
Für die Nachbearbeitung eines einzelnen Werts gibt es stdWrap. Das ist keine Funktion im Sinn einer Programmiersprache, sondern eine lange Liste von Eigenschaften, die in einer festgelegten Reihenfolge auf den Wert angewendet werden. Genau daran scheitern die ersten Versuche: Die Reihenfolge steht fest und richtet sich nicht danach, in welcher Zeile du die Eigenschaften notiert hast.
Constants und Setup, und warum die Trennung zählt
Constants enthalten reine Werte, das Setup die Konfiguration, die diese Werte benutzt. Im Setup holst du einen Wert mit einer geschweiften Klammer und einem Dollarzeichen davor. Der Sinn ist nicht Ordnung, sondern Zuständigkeit: Wer die Hauptfarbe ändern soll, muss dafür nicht wissen, wie ein FLUIDTEMPLATE aufgebaut ist.
Im Backend gibt es dafür einen eigenen Editor, der die Constants nach Kategorien sortiert als Eingabefelder anzeigt, sofern sie im Quelltext mit den passenden Kommentaren beschrieben sind. Das ist der Unterschied zwischen einer Konfiguration, die nur ihre Autorin bedienen kann, und einer, die eine Kollegin ohne Rückfrage anpasst.
Seit TYPO3 13.1 gibt es mit den Site Sets eine zweite Bauform für dieselbe Idee. Dort übernehmen settings.definitions.yaml und settings.yaml die Rolle der Constants, während setup.typoscript und constants.typoscript daneben liegen bleiben. Der Gedanke der Trennung ist derselbe, nur die Dateien haben gewechselt.
TypoScript oder TSconfig, hier entstehen die meisten Missverständnisse
TypoScript im engeren Sinn beschreibt, wie das Frontend eine Seite ausgibt. TSconfig beschreibt, wie sich das Backend verhält, und zerfällt in zwei Teile: Die Seiten-TSconfig gilt für einen Zweig des Seitenbaums und regelt zum Beispiel, welche Backend-Layouts zur Wahl stehen, welche Felder ein Formular zeigt und welche Elementtypen der Wizard anbietet. Die Benutzer-TSconfig hängt an einem Konto oder einer Gruppe und regelt, was diese Person sieht.
Verwirrend ist die Ähnlichkeit, weil beide dieselbe Syntax und dieselbe Vererbung im Seitenbaum benutzen. Der schnellste Test ist der Anfang des Pfads. TCEFORM, TCEMAIN und mod. gehören ins Backend, page, lib, config und plugin gehören ins Frontend. Die beiden haben getrennte Referenzhandbücher, und wenn ein Pfad im einen nicht auftaucht, steht er meist im anderen.
Eingetragen wird beides an unterschiedlichen Orten. TypoScript kommt aus dem Template-Datensatz oder, in neueren Installationen, aus einem Site Set. Seiten-TSconfig steht in den Seiteneigenschaften oder wird von einer Extension mitgeliefert. Wer eine Zeile am falschen Ort einträgt, bekommt keine Fehlermeldung, sondern gar keine Reaktion.
Vererbung im Seitenbaum und die Reihenfolge des Einbindens
Ein Template-Datensatz liegt auf einer Seite und gilt ab dort für alle Unterseiten. Auf der obersten Seite ist er als Rootlevel markiert, damit er für den gesamten Baum greift. Legt jemand tiefer im Baum einen zweiten an und setzt dort das Clear-Feld für Setup oder Constants, ist die Vererbung ab dieser Stelle abgeschnitten. Das ist die häufigste Erklärung dafür, dass eine Einstellung auf der Startseite wirkt und auf einem Unterzweig nicht.
Innerhalb der zusammengesetzten Konfiguration gilt eine einfache Regel: Die letzte Zuweisung an einen Pfad gewinnt. Nicht die speziellere, nicht die längere, sondern die spätere. Deshalb gehört eigene Konfiguration hinter die mitgelieferte, und deshalb erzeugt eine Umsortierung der Einbindungen Wirkungen an Stellen, die man nicht angefasst hat.
Conditions schalten Blöcke frei, abhängig etwa vom Anwendungskontext, von der Sprache der Seite oder davon, ob eine Person im Frontend angemeldet ist. Sie werden als Ausdruck in eckigen Klammern geschrieben und mit dem Schlüsselwort END geschlossen. Fehlt der Abschluss, gilt die Bedingung für alles Folgende, auch für Dateien, die danach eingebunden werden.
Ohne Objektbrowser ist Fehlersuche Raten
Das TypoScript-Modul im Backend zeigt den fertig aufgelösten Objektbaum, den TYPO3 tatsächlich benutzt, mit ersetzten Constants und ausgewerteten Bedingungen. Der entscheidende Handgriff dabei ist die Seitenauswahl: Schau immer von der Seite aus nach, auf der das Problem auftritt, sonst siehst du eine andere Konfiguration als die betroffene.
Zwei weitere Hilfsmittel sparen viel Zeit. Der Admin-Bereich im Frontend, den die Systemextension adminpanel einblendet, zeigt für eine angemeldete Redaktion unter anderem, welche Datensätze eingesammelt wurden und wie lange das gedauert hat. Und wenn Werte in einer Fluid-Datei fehlen, klärt der ViewHelper f:debug schneller, was ankommt, als jede Vermutung über die TypoScript-Seite.
Bevor du lange suchst, lohnt der Blick auf den Cache. TYPO3 legt das Ergebnis der Auswertung ab, statt es bei jedem Aufruf neu zusammenzusetzen. Eine Änderung, die im Objektbrowser sichtbar ist, aber im Frontend nicht, ist deshalb selten ein Fehler in der Konfiguration.
Dazu passende Kurse
Wenn du den Objektbaum lieber an einer laufenden Installation aufbaust, statt Beispiele nachzulesen, kannst du TypoScript im Kurs erarbeiten .
Wie sicher bist du beim Thema wirklich?
Lesen fühlt sich schnell nach Können an. Ein kurzer Test zeigt dir, was davon schon sitzt und wo sich ein Kurs lohnt. Kostenlos, ohne Anmeldung, mit einer Erklärung zu jeder Antwort.
Wo du genau das übst
Sehr kompetente und freundliche Trainerin. Die Inhalte wurden gut strukturiert und anhand von anschaulichen Beispielen vermittelt.
Häufige Fragen
Ist TypoScript eine Programmiersprache?
Was ist der Unterschied zwischen TypoScript und TSconfig?
Brauche ich TypoScript noch, wenn ich mit Fluid arbeite?
Warum wirkt meine Änderung erst nach dem Leeren des Caches?
Deine Ansprechpartner
Du bist dir nicht sicher, welcher Kurs oder welches Level zu dir passt? Wir beraten dich persönlich und kostenlos.
Yves Hoppe
Weiterbildung & Beratung
Hilft dir, aus dem TYPO3-Programm den passenden Kurs für deinen Stand zu finden.
Norbert Jansen
Beratung & Inhouse
Plant mit dir Inhouse-Trainings, die auf eure Abläufe und euren Datenbestand zugeschnitten sind.
TypoScript liest sich leichter, wenn jemand danebensitzt
Bei cmt baust du den Objektbaum an einer echten Installation selbst auf, statt fremde Schnipsel zu übernehmen, und siehst im Objektbrowser sofort, was deine Zeile bewirkt hat.