Lernseite · TypoScript
TypoScript verstehen: Syntax, Bedingungen, Datenquellen und Page TSconfig
TypoScript ist die Sprache, mit der du TYPO3 sagst, wie es eine Website ausgeben soll. Auf dieser Seite begleitest du die Integratorin Mara, die für die Musikschule Lindenau den Seitentitel setzt, Daten aus der Site holt und das Backend für die Redaktion vereinfacht. Danach kannst du TypoScript lesen, Fehler finden und weißt, was sich in TYPO3 14 geändert hat.
Was TypoScript ist
TypoScript ist eine Konfigurationssprache. Sie beschreibt, wie TYPO3 die Ausgabe einer Seite erzeugt. TYPO3 liest den Text ein und wandelt ihn intern in ein großes PHP-Array um. TypoScript läuft also nicht im Browser. Es ist auch keine Programmiersprache mit Schleifen und eigenen Funktionen, und es fragt keine Datenbank ab.
Mara arbeitet in einem Composer-Projekt mit TYPO3 14.3. Ihr Sitepackage heißt lindenau_site, als Composer-Paket lindenau/site. Darin liegt ein Site Set mit dem TypoScript für das Frontend. Die Website der Musikschule bindet dieses Set ein.
Im TypoScript-Baum unterscheidest du drei Dinge:
- Ein Objekt hat einen Typ, zum Beispiel
PAGE,TEXT,COAoderIMAGE. Diese Typen heißen Content-Objekte, kurz cObjects, denn sie erzeugen Ausgabe. - Eine Eigenschaft konfiguriert ein Objekt. So ist
valueeine Eigenschaft des ObjektsTEXT. - Eine Funktion wie
stdWrap,typolinkoderparseFuncverarbeitet Werte. Sie hat selbst Eigenschaften, beistdWrapetwawrapoderdata.
Eigenschaften sprichst du mit Punkten an. Einen Pfeil wie in PHP gibt es in TypoScript nicht. Funktionen rufst du auch nicht mit runden Klammern auf. Klammern hinter einem Funktionsnamen gibt es nur beim Operator zum Ändern von Werten, den du weiter unten kennenlernst.
Die Syntax: Pfade, Werte, Klammern
Jede Zeile besteht aus einem Pfad, einem Operator und einem Wert. Punkte trennen die Ebenen des Pfads. Das Gleichheitszeichen weist den Rest der Zeile als Wert zu. Das doppelte Gleichheitszeichen ist dagegen ein Vergleich und gehört nur in Bedingungen.
page = PAGE
page.10 = TEXT
page.10.value = Willkommen in der Musikschule
page.10.wrap = <p>|</p>
# Gleiche Wirkung, kürzer geschrieben
page {
10 = TEXT
10.value = Willkommen in der Musikschule
}Geschweifte Klammern bündeln Zuweisungen unter einem gemeinsamen Pfad. Steht in der Klammer hinter page die Zeile 10 gleich TEXT, ist das gleichbedeutend mit der Zeile page Punkt 10 gleich TEXT.
Runde Klammern umschließen mehrzeilige Werte. Eckige Klammern stehen für Bedingungen. Diese drei Klammerarten solltest du nicht verwechseln.
Kommentare für eine Zeile beginnen mit einer Raute oder mit zwei Schrägstrichen. Ein Kommentarblock über mehrere Zeilen steht zwischen Schrägstrich-Stern und Stern-Schrägstrich. Achtung: Stehen diese Zeichen hinter einem Gleichheitszeichen, gehören sie zum Wert. Kommentare schreibst du deshalb in eine eigene Zeile.
# Kommentar mit Raute
// Kommentar mit zwei Schrägstrichen
/*
Kommentarblock über mehrere Zeilen
*/
page.20 = TEXT
page.20.value (
Unterricht für Kinder und Erwachsene.
Probestunde jederzeit möglich.
)Konstanten schreibst du im Setup als Dollarzeichen mit dem Namen der Konstante in geschweiften Klammern. TYPO3 ersetzt sie vor dem Auswerten. Fehlt die Konstante, wird nichts ersetzt. Dann steht der Platzhalter wörtlich im Frontend. Wie du so etwas findest, liest du im Abschnitt über die Fehlersuche.
lib.phone = TEXT
lib.phone.value = {$lindenau.telefon}Kopieren, Referenzieren, Löschen, Ändern
Neben der Zuweisung kennt TypoScript vier weitere Operatoren.
Kopieren mit dem Kleiner-als-Zeichen übernimmt einen Pfad samt Wert und allen Unterpfaden. Die Kopie entsteht genau in der Zeile, in der sie steht. Spätere Änderungen am Original erreichen die Kopie nicht.
Referenzieren mit Gleichheitszeichen und Kleiner-als-Zeichen kopiert nichts, sondern verweist auf das Original. TYPO3 löst die Referenz erst beim Rendern eines Content-Objekts auf. Deshalb kommen spätere Änderungen am Original auch beim Ziel an. Das geschieht bei jedem Content-Objekt im Setup, zum Beispiel unter lib oder tt_content, und außerdem bei parseFunc. Für einfache Werte wie einen Wrap und für Konstanten gibt es keine Auflösung.
Löschen mit dem Größer-als-Zeichen entfernt einen Pfad mit allem, was darunter hängt. So entfernst du zum Beispiel ein Objekt, das ein eingebundenes Set mitbringt.
Ändern mit Doppelpunkt und Gleichheitszeichen ruft eine Funktion auf den vorhandenen Wert auf. Die Funktion addToList ergänzt ein Element in einer kommagetrennten Liste. Weitere Funktionen sind etwa removeFromList und replaceString.
lib.a = TEXT
lib.a.value = A
lib.b < lib.a
lib.c =< lib.a
lib.a.value = X
page.30 >
lib.list.value := addToList(neu)Werden lib.b und lib.c als Content-Objekte ausgegeben, zeigt lib.b also A und lib.c zeigt X.
# Falsch: wird als Referenz gelesen
lib.nav.wrap =<ul>|</ul>
# Richtig
lib.nav.wrap = <ul>|</ul>Woher TypoScript kommt: Sets, Site und Imports
Seit TYPO3 13 bringt ein Site Set sein TypoScript als Datei mit. Die Dateien setup.typoscript und constants.typoscript liegen neben der config.yaml des Sets. Nicht in der config.yaml selbst und nicht in der composer.json. TYPO3 lädt sie für jede Site, die das Set nutzt. Ein sys_template-Datensatz auf der Startseite ist dann nicht mehr nötig, aber weiter möglich.
Auch die Site selbst ist eine Quelle für TypoScript. Liegt eine setup.typoscript neben der config.yaml der Site, lädt TYPO3 sie automatisch. Die Site hat einen eigenen Gültigkeitsbereich. Sie erbt kein TypoScript von einer übergeordneten Site im Seitenbaum.
Site Settings überschreiben gleichnamige Konstanten aus den Sets. So kann jede Site eine Einstellung wie die Telefonnummer anders setzen, ohne das Set zu ändern.
Weitere Dateien bindest du mit @import ein, gefolgt vom Pfad in einfachen Anführungszeichen. Platzhalter wie ein Stern vor der Endung typoscript sind erlaubt. Die alte Schreibweise mit INCLUDE_TYPOSCRIPT gibt es in TYPO3 14 nicht mehr.
@import 'EXT:lindenau_site/Configuration/TypoScript/setup.typoscript'
@import 'EXT:lindenau_site/Configuration/TypoScript/Parts/*.typoscript'Fremde Sets holst du dagegen nicht per Import. Soll Maras Set das TypoScript von Fluid Styled Content mitbringen, trägt sie das Set von Fluid Styled Content als Abhängigkeit in die config.yaml ihres Sets ein. TYPO3 ordnet die Abhängigkeiten und lädt ein Set, das mehrere brauchen, nur einmal. Das ist der empfohlene Weg. Dateien kopieren oder fremde Dateien importieren macht das Projekt schwer wartbar. Der Import ist für die eigenen, lokalen Dateien gedacht.
name: lindenau/site
label: Musikschule Lindenau
dependencies:
- typo3/fluid-styled-contentDatentypen und Top-Level-Objekte
Jede Eigenschaft erwartet einen bestimmten Datentyp. Welcher das ist, steht bei jeder Eigenschaft in der TypoScript-Referenz. Die wichtigsten:
- string ist einfacher Text, etwa der Wert eines TEXT-Objekts.
- integer ist eine ganze Zahl.
- boolean steht für wahr oder falsch und wird als 1 oder 0 geschrieben.
- list ist eine kommagetrennte Liste.
- wrap ist ein Umschlag mit einem senkrechten Strich. An der Stelle des Strichs setzt TYPO3 den Inhalt ein. Aus dem Wrap mit einem Absatz-Tag vor und nach dem Strich wird so ein Absatz um den Inhalt.
- getText ist ein Ausdruck, der Werte aus einer Quelle holt, etwa ein Feld des Datensatzes, der Seite oder der Site. Die Eigenschaft
datavonstdWraperwartet diesen Typ. - imgResource beschreibt ein Bild samt Verarbeitung, zum Beispiel Größe und Zuschnitt.
Top-Level-Objekte, kurz TLO, sind die Namen auf der obersten Ebene des TypoScript-Baums. Manche haben einen festen Typ und sind schon angelegt, andere musst du selbst anlegen:
pagemusst du ausdrücklich anlegen, indem du ihm den TypPAGEzuweist. Ein beliebiger anderer Name wird nicht von selbst zu einer Seite.confighat den TypCONFIGund ist bereits vorhanden. Es enthält globale Einstellungen der Ausgabe.pluginist ebenfalls vorbelegt. Darunter stehen die Einstellungen von Frontend-Plugins, für jede Extension unter tx und ihrem Namen.libist der Platz für wiederverwendbare Bausteine wielib.mainMenu, die du per Kopie oder Referenz einbindest. Mit PHP-Bibliotheken hat es nichts zu tun.moduleist für Backend-Module gedacht.stylesund die Namen, die mit tt beginnen, wiett_content, sind ebenfalls reserviert.resourcesundsitetitlesind laut Referenz nur lesbar.
Das Objekt config und der Seitentitel
Unter config stehen Einstellungen, die die ganze Ausgabe betreffen. Datenbankverbindung, Benutzerrechte oder Composer-Pakete gehören nicht dazu. Typische Eigenschaften sind:
config.cache_periodlegt die Lebensdauer des Seitencaches fest.config.admPanelschaltet das Admin Panel im Frontend ein oder aus.config.additionalHeaderssetzt zusätzliche HTTP-Header.config.pageTitleProviderslegt fest, woher der Seitentitel kommt.config.contentObjectExceptionHandlerregelt, was bei Fehlern in Content-Objekten passiert.
Backend-Layouts und Sitemaps konfigurierst du nicht unter config, sondern an anderer Stelle.
Zusätzliche Header sind ein nummeriertes Array. Jeder Eintrag braucht header und kann replace und httpResponseCode haben. Verwechsle das nicht mit headerData des Objekts page. Das schreibt HTML in den Kopf der Seite, aber keinen HTTP-Header.
config.additionalHeaders.10.header = X-Frame-Options: SAMEORIGIN
config.admPanel = 1Fehler in Plugins: Wirft ein Content-Objekt beim Rendern eine Exception, meist ein Plugin, greift im Kontext Production der contentObjectExceptionHandler. Er fängt den Fehler ab. Statt des Objekts erscheint an dieser Stelle ein kurzer Hinweis, der Rest der Seite bleibt stehen. Seit TYPO3 13 nennt der Hinweis die Request-ID. Den Fehler schreibt TYPO3 mit derselben Request-ID ins Log, so findest du ihn wieder. Im Kontext Development greift der Handler standardmäßig nicht. Dort bricht die ganze Seite mit der Exception ab, damit du den Fehler siehst und beheben kannst. Mit dem Wert 0 schaltest du den Handler auch in Production ab.
Der Seitentitel im HTML-Tag title kann aus mehreren Quellen kommen, etwa aus dem SEO-Feld der Seite oder aus einem Datensatz. Jede Quelle ist ein Page Title Provider. TYPO3 fragt sie der Reihe nach. Der erste, der einen Titel liefert, gewinnt. Die Reihenfolge legst du in config.pageTitleProviders mit den Eigenschaften before und after fest. Extensions können eigene Provider mitbringen.
config.pageTitleProviders {
seo {
provider = TYPO3\CMS\Seo\PageTitle\SeoTitlePageTitleProvider
before = record, recordTitle
}
}Die Musikschule hat eine Detailseite für ihre Kurse. Dort soll der Kursname im Seitentitel stehen. In TYPO3 14 gibt es dafür zwei Wege. Der neue ViewHelper f:page.title setzt den Titel direkt im Fluid-Template. Er nutzt dafür den neuen Provider recordTitle und respektiert so die Reihenfolge der Provider. Oder die Extension registriert einen eigenen Provider, den Mara mit before und after einordnet. Den Titel hart in die Konfiguration oder in das Feld für den Navigationstitel zu schreiben, löst das Problem nicht.
Bedingungen
Bedingungen stehen in eckigen Klammern. Was danach folgt, gilt nur, wenn die Bedingung zutrifft. Mit ELSE schreibst du den anderen Fall, mit END oder GLOBAL beendest du die Bedingung. Seit TYPO3 9 wertet TYPO3 Bedingungen mit der Symfony Expression Language aus. Sie kennt Operatoren wie das doppelte Gleichheitszeichen, logisches Und und logisches Oder, dazu Funktionen wie site(), date() oder traverse().
Mara braucht für die englische Website einen anderen Footer-Text und will einige Dinge nur für angemeldete Mitglieder zeigen.
[frontend.user.isLoggedIn]
lib.memberHint.value = Hallo Mitglied
[END]
[site("identifier") == "lindenau"]
lib.footer.value = Musikschule Lindenau
[END]
[tree.pagelayout == "pagets__home"]
page.10.value = Startseite
[END]
[request && request.getNormalizedParams().getHttpHost() == "www.lindenau.example"]
config.admPanel = 0
[END]Was die Bedingungen prüfen:
frontend.user.isLoggedInist wahr, wenn ein Frontend-Benutzer angemeldet ist. Gruppen prüfst du mitfrontend.user.userGroupIds.backend.user.isAdminprüft, ob ein Admin im Backend angemeldet ist.- Die Funktion
site()liefert Werte der Site-Konfiguration wie identifier, base oder rootPageId. Für die Sprache gibt essiteLanguage(). tree.pagelayoutberücksichtigt auch das Backend-Layout, das eine übergeordnete Seite an ihre Unterseiten vererbt. Das Feld backend_layout der Seite selbst prüft dagegen nur die Seite.- Die Funktion
traverse()liest Werte aus Arrays wie page, zum Beispiel die uid der aktuellen Seite. - Die Funktion
session()liest Werte aus der Frontend-Sitzung. Ein senkrechter Strich steigt dabei tiefer in die gespeicherte Struktur. - Die normalisierten Parameter des Requests liefern den Host, den HTTPS-Status und mehr.
Neu in TYPO3 14: Die Funktion getTSFE() ist entfernt. Bedingungen damit treffen nie mehr zu. Die Seiten-ID holst du jetzt aus den PageArguments des Requests.
Die alte Syntax aus der Zeit vor der Expression Language, etwa mit globalVar, globalString, usergroup oder loginUser, funktioniert schon seit TYPO3 10 nicht mehr.
[request?.getPageArguments()?.getPageId() == 42]
[traverse(page, "uid") in [17,24]]
[session("foo|bar") == 1234567]Datenquellen mit getText
Die Eigenschaft data holt einen Wert aus einer Datenquelle. Ihr Wert ist ein getText-Ausdruck aus einem Schlüssel, einem Doppelpunkt und einem Code. Der Schlüssel page mit dem Code title liefert zum Beispiel den Titel der aktuellen Seite. Nicht den Titel der Website und nicht den der Startseite.
lib.pageTitle = TEXT
lib.pageTitle.data = page:title
lib.headline = TEXT
lib.headline.data = field:header // field:title
lib.phone = TEXT
lib.phone.data = siteSettings:lindenau.telefon
lib.userName = TEXT
lib.userName.data = request:frontend.user|username
lib.layout = TEXT
lib.layout.data = levelfield:-1, backend_layout_next_level, slideDie wichtigsten Schlüssel:
fieldliest ein Feld des aktuellen Datensatzes. Das ist der Datensatz, der gerade gerendert wird, etwa ein Inhaltselement oder die Seite.pageliest ein Feld der aktuellen Seite.DBliest ein Feld eines bestimmten Datensatzes aus einer beliebigen TCA-Tabelle. Der Code nennt Tabelle, uid und Feld, also etwa tt_content, 12 und header. Gelöschte Datensätze liefern dabei nichts.levelfieldholt ein Feld aus der Rootline. Minus eins ist die aktuelle Seite. Mit slide geht TYPO3 nach oben, bis ein Wert nicht leer ist. So übernimmst du etwa ein Backend-Layout von Elternseiten. Ähnlich liefertleveltitleSeitentitel aus der Rootline.siteliefert Werte der Site-Konfiguration wie base oder identifier.siteLanguageliefert Werte der aktuellen Sprache.siteSettingsliest eine Einstellung aus den Site Settings, etwa Maras Telefonnummer.requestliest Attribute des PSR-7-Requests.assetliefert die URL einer öffentlichen Datei mit Cache-Busting.applicationcontextliefert den Anwendungskontext, etwa Production.
Zwei Schrägstriche verketten getText-Ausdrücke als Rückfall. Der erste nicht leere Wert gewinnt. Im Beispiel kommt also die Überschrift, und nur wenn sie leer ist, der Titel. Hier sind die zwei Schrägstriche kein Kommentar.
Feldwert oder Datensatz? Mit data und field holst du einen einzelnen Wert. Ganze Datensätze holen dagegen Content-Objekte wie CONTENT und RECORDS oder ein Data Processor.
parseFunc: Text aus dem Editor ausgeben
Text aus dem Rich-Text-Editor, kurz RTE, ist HTML. Bevor er im Frontend erscheint, verarbeitet ihn die Funktion parseFunc. Die übliche Konfiguration dafür heißt lib.parseFunc_RTE. Sie wandelt Links mit typolink um, zum Beispiel interne Links, die mit t3 und Doppelpunkt beginnen, in echte URLs. Sie erlaubt, entfernt oder verändert HTML-Tags, gesteuert über Eigenschaften wie tags, allowTags, denyTags und externalBlocks. Zum Schluss schickt sie den Text durch den HTML Sanitizer. PHP-Code führt parseFunc nicht aus, und es übersetzt oder lädt auch nichts hoch.
Neu in TYPO3 14: Weder die Extension frontend noch Fluid Styled Content setzen allowTags noch vor. Alle Tags sind zunächst erlaubt. Der HTML Sanitizer entscheidet, welche Tags und Attribute übrig bleiben. Die Eigenschaft allowTags gibt es aber weiter. Wer sie setzt, beschränkt die Ausgabe gezielt.
# Wirkt in TYPO3 14 anders: erlaubt nur noch wbr
lib.parseFunc_RTE.allowTags := addToList(wbr)Fehlersuche: Active und Included TypoScript
TypoScript entsteht aus vielen Quellen und Bedingungen. Um zu sehen, was auf einer Seite wirklich gilt, öffnest du das Modul „Sites“ und dort „TypoScript“. Es hat zwei wichtige Ansichten.
- Active TypoScript zeigt Konstanten und Setup einer Seite als Baum. So sieht das Ergebnis aus, nachdem alle Einbindungen und Bedingungen angewendet sind.
- Included TypoScript zeigt die Einbindungen samt Herkunft und Reihenfolge. Hier erkennst du, welche Sets, Dateien und Datensätze geladen werden. Diese Ansicht warnt auch bei Syntaxfehlern.
- Im Frontend steht wörtlich der Platzhalter einer Konstante statt der Telefonnummer.
- Mara prüft in Active TypoScript, ob die Konstante auf dieser Seite überhaupt definiert ist und wie sie genau heißt.
- In Included TypoScript prüft sie, ob die Datei mit der Konstante geladen wird, in welcher Reihenfolge und ob eine Syntaxwarnung erscheint.
- Sie findet einen Tippfehler im Namen und korrigiert ihn.
Den Browser-Cache zu leeren hilft hier nicht. Ein nicht ersetzter Platzhalter bedeutet, dass TYPO3 die Konstante nicht kennt.
Page TSconfig: das Backend anpassen
Page TSconfig hat dieselbe Syntax wie TypoScript, aber eine andere Aufgabe. Es steuert das Backend je Seite oder Seitenbaum, etwa sichtbare Felder, Standardwerte oder den Assistenten für neue Inhaltselemente. Das Frontend, den Webserver oder die Rechte von Frontend-Benutzern steuert es nicht. Page TSconfig landet auch nicht im Seitencache des Frontends.
Es gibt drei übliche Orte:
- Eine Datei
page.tsconfigim OrdnerConfigurationeiner Extension gilt global für die ganze Installation. - Eine Datei
page.tsconfigim Ordner eines Site Sets gilt nur für die Seiten der Sites, die das Set nutzen. Die Datei für das Frontend heißt dagegensetup.typoscript. - Das Feld TSconfig in den Seiteneigenschaften gilt für die Seite und vererbt sich auf alle Unterseiten.
Mara will das Formular für die Redaktion aufräumen. Mit TCEFORM passt sie Formularfelder an. Die Eigenschaft disabled mit dem Wert 1 blendet ein Feld aus. Auch Beschriftungen und Auswahlwerte lassen sich so ändern. TCEMAIN betrifft dagegen das Speichern, nicht das Formular.
Standardwerte setzt sie mit TCAdefaults. Seit TYPO3 14 geht das auch abhängig vom Typ des Datensatzes, über den Unterschlüssel types. Ein typabhängiger Wert hat Vorrang vor dem allgemeinen Wert des Felds. Page TSconfig überschreibt dabei User TSconfig.
TCEFORM.tt_content.layout.disabled = 1
TCAdefaults.tt_content.header_layout = 2
TCAdefaults.tt_content.header_layout.types.textmedia = 3Das Wichtigste in Kürze
- TypoScript ist eine Konfigurationssprache und wird intern zu einem PHP-Array.
- Gleichheitszeichen weist zu, Kleiner-als kopiert, Gleich und Kleiner-als referenziert, Größer-als löscht, Doppelpunkt und Gleich ruft eine Funktion auf.
- Eine Kopie friert den Stand ihrer Zeile ein. Eine Referenz wird erst beim Rendern eines Content-Objekts aufgelöst.
- Sets bringen ihr TypoScript in
setup.typoscriptneben ihrerconfig.yamlmit. Abhängige Sets kommen zuerst, Site Settings überschreiben Konstanten. - Bedingungen nutzen die Symfony Expression Language. Die Funktion
getTSFE()gibt es in TYPO3 14 nicht mehr. - Die Eigenschaft
dataholt Werte mit getText, zum Beispiel aus page, field, siteSettings oder request. allowTagsist in TYPO3 14 nicht mehr vorbelegt.- Active TypoScript zeigt das Ergebnis, Included TypoScript die Einbindungen.
- Page TSconfig steuert das Backend und vererbt sich im Seitenbaum nach unten.
Begriffe
- Content-Objekt
- Objekt, das Ausgabe erzeugt, etwa TEXT, COA oder IMAGE.
- getText
- Ausdruck aus Schlüssel und Code, der einen Wert aus einer Datenquelle holt.
- Konstante
- Platzhalter, den TYPO3 vor dem Auswerten in das Setup einsetzt.
- Page Title Provider
- Quelle für den Seitentitel, deren Reihenfolge config.pageTitleProviders festlegt.
- Page TSconfig
- Konfiguration des Backends je Seite oder Seitenbaum.
- Site Set
- Paket aus TypoScript, Settings und Page TSconfig, das eine Site einbindet.
- Top-Level-Objekt
- Name auf der obersten Ebene des TypoScript-Baums, etwa page, config oder lib.