Study guide · TypoScript
Understanding TypoScript: syntax, conditions, data sources and page TSconfig
TypoScript is the language you use to tell TYPO3 how to output a website. On this page you follow the integrator Mara at the Lindenau music school. She sets the page title, fetches data from the site and tidies up the backend for the editors. Afterwards you can read TypoScript, track down errors and you know what changed in TYPO3 14.
What TypoScript is
TypoScript is a configuration language. It describes how TYPO3 generates the output of a page. TYPO3 reads the text and converts it internally into a large PHP array. So TypoScript does not run in the browser. It is not a programming language with loops and your own functions either, and it does not query a database.
Mara works in a Composer project with TYPO3 14.3. Her site package is called lindenau_site, as a Composer package lindenau/site. It contains a site set with the TypoScript for the frontend. The music school website includes this set.
In the TypoScript tree you tell three things apart:
- An object has a type, for example
PAGE,TEXT,COAorIMAGE. These types are called content objects, or cObjects for short, because they produce output. - A property configures an object. For example,
valueis a property of theTEXTobject. - A function such as
stdWrap,typolinkorparseFuncprocesses values. It has properties of its own, forstdWrapthese includewrapanddata.
You address properties with dots. There is no arrow like in PHP. You do not call functions with parentheses either. Parentheses after a function name only appear with the operator that modifies values, which you will meet further down.
The syntax: paths, values, brackets
Every line consists of a path, an operator and a value. Dots separate the levels of the path. The equals sign assigns the rest of the line as the value. The double equals sign, on the other hand, is a comparison and only belongs in conditions.
page = PAGE
page.10 = TEXT
page.10.value = Welcome to the music school
page.10.wrap = <p>|</p>
# Same effect, written shorter
page {
10 = TEXT
10.value = Welcome to the music school
}Curly braces group assignments under a common path. If the braces after page contain the line 10 equals TEXT, that is the same as the line page dot 10 equals TEXT.
Parentheses enclose multi-line values. Square brackets stand for conditions. Do not mix up these three kinds of brackets.
Comments for a single line start with a hash sign or with two slashes. A comment block across several lines sits between slash-asterisk and asterisk-slash. Careful: if these characters come after an equals sign, they are part of the value. That is why you write comments on a line of their own.
# Comment with a hash sign
// Comment with two slashes
/*
Comment block across several lines
*/
page.20 = TEXT
page.20.value (
Lessons for children and adults.
Trial lessons at any time.
)Constants are written in setup as a dollar sign with the name of the constant in curly braces. TYPO3 replaces them before evaluating the setup. If the constant is missing, nothing is replaced. The placeholder then shows up literally in the frontend. You will learn how to find such problems in the section on debugging.
lib.phone = TEXT
lib.phone.value = {$lindenau.telefon}Copying, referencing, deleting, modifying
Besides assignment, TypoScript knows four more operators.
Copying with the less-than sign takes over a path with its value and all sub paths. The copy is made exactly at the line where it stands. Later changes to the original do not reach the copy.
Referencing with an equals sign followed by a less-than sign copies nothing. It points to the original instead. TYPO3 only resolves the reference when it renders a content object. That is why later changes to the original also reach the target. This happens for every content object in setup, for example below lib or tt_content, and also for parseFunc. Plain values such as a wrap, and constants, are not resolved.
Deleting with the greater-than sign removes a path with everything below it. This lets you remove, for example, an object that an included set brings along.
Modifying with a colon and an equals sign calls a function on the existing value. The function addToList adds an item to a comma-separated list. Other functions include removeFromList and 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(new)So if lib.b and lib.c are output as content objects, lib.b shows A and lib.c shows X.
# Wrong: read as a reference
lib.nav.wrap =<ul>|</ul>
# Right
lib.nav.wrap = <ul>|</ul>Where TypoScript comes from: sets, site and imports
Since TYPO3 13, a site set ships its TypoScript as files. The files setup.typoscript and constants.typoscript sit next to the set's config.yaml. Not inside the config.yaml itself and not in composer.json. TYPO3 loads them for every site that uses the set. A sys_template record on the home page is then no longer needed, but still possible.
The site itself is also a source of TypoScript. If a setup.typoscript sits next to the site's config.yaml, TYPO3 loads it automatically. The site has its own scope. It does not inherit TypoScript from a parent site in the page tree.
Site settings override constants of the same name from the sets. So every site can set a value such as the phone number differently, without changing the set.
Further files are included with @import, followed by the path in single quotes. Wildcards such as an asterisk before the file extension typoscript are allowed. The old syntax with INCLUDE_TYPOSCRIPT no longer exists in TYPO3 14.
@import 'EXT:lindenau_site/Configuration/TypoScript/setup.typoscript'
@import 'EXT:lindenau_site/Configuration/TypoScript/Parts/*.typoscript'Other sets, however, are not pulled in by import. If Mara's set should bring along the TypoScript of Fluid Styled Content, she adds the Fluid Styled Content set as a dependency in her set's config.yaml. TYPO3 orders the dependencies and loads a set that several others need only once. This is the recommended way. Copying files or importing someone else's files makes the project hard to maintain. Import is meant for your own local files.
name: lindenau/site
label: Lindenau Music School
dependencies:
- typo3/fluid-styled-contentData types and top-level objects
Every property expects a certain data type. The TypoScript Reference lists it for each property. The most important ones:
- string is plain text, such as the value of a TEXT object.
- integer is a whole number.
- boolean stands for true or false and is written as 1 or 0.
- list is a comma-separated list.
- wrap is an envelope with a vertical bar. TYPO3 inserts the content where the bar is. A wrap with a paragraph tag before and after the bar therefore puts a paragraph around the content.
- getText is an expression that fetches values from a source, such as a field of the record, the page or the site. The
dataproperty ofstdWrapexpects this type. - imgResource describes an image including its processing, for example size and cropping.
Top-level objects, TLO for short, are the names on the top level of the TypoScript tree. Some have a fixed type and already exist, others you must create yourself:
- You must create
pageexplicitly by assigning it the typePAGE. Any other name does not turn into a page by itself. confighas the typeCONFIGand already exists. It holds global output settings.pluginis pre-initialized as well. It holds the settings of frontend plugins, for each extension under tx and its name.libis the place for reusable building blocks such aslib.mainMenu, which you include by copy or reference. It has nothing to do with PHP libraries.moduleis meant for backend modules.stylesand the names starting with tt, such astt_content, are reserved too.resourcesandsitetitleare read-only according to the reference.
The config object and the page title
Below config you find settings that affect the whole output. Database connection, user permissions or Composer packages do not belong here. Typical properties are:
config.cache_periodsets the lifetime of the page cache.config.admPanelswitches the Admin Panel in the frontend on or off.config.additionalHeaderssets additional HTTP headers.config.pageTitleProvidersdefines where the page title comes from.config.contentObjectExceptionHandlercontrols what happens on errors in content objects.
You do not configure backend layouts or sitemaps below config, but elsewhere.
Additional headers are a numbered array. Each entry needs header and can have replace and httpResponseCode. Do not confuse this with headerData of the page object. That writes HTML into the head of the page, but no HTTP header.
config.additionalHeaders.10.header = X-Frame-Options: SAMEORIGIN
config.admPanel = 1Errors in plugins: If a content object throws an exception while rendering, usually a plugin, the contentObjectExceptionHandler steps in when the context is Production. It catches the error. Instead of the object, a short notice appears at this spot, and the rest of the page stays intact. Since TYPO3 13 the notice shows the request ID. TYPO3 writes the error to the log with the same request ID, so you can find it again. In the Development context the handler does not step in by default. There the whole page stops with the exception, so you see the error and can fix it. With the value 0 you also switch the handler off in Production.
The page title in the HTML title tag can come from several sources, for example from the SEO field of the page or from a record. Each source is a page title provider. TYPO3 asks them in order. The first one that delivers a title wins. You define the order in config.pageTitleProviders with the properties before and after. Extensions can ship their own providers.
config.pageTitleProviders {
seo {
provider = TYPO3\CMS\Seo\PageTitle\SeoTitlePageTitleProvider
before = record, recordTitle
}
}The music school has a detail page for its courses. There, the course name should appear in the page title. TYPO3 14 offers two ways. The new ViewHelper f:page.title sets the title directly in the Fluid template. It uses the new provider recordTitle and so respects the order of the providers. Or the extension registers its own provider, which Mara places with before and after. Hard-coding the title in the configuration or writing it into the navigation title field does not solve the problem.
Conditions
Conditions are written in square brackets. What follows only applies if the condition is true. With ELSE you write the other case, with END or GLOBAL you close the condition. Since TYPO3 9, conditions are evaluated with the Symfony Expression Language. It knows operators such as the double equals sign, logical and, and logical or, plus functions such as site(), date() or traverse().
For the English website Mara needs a different footer text, and she wants to show some things to logged-in members only.
[frontend.user.isLoggedIn]
lib.memberHint.value = Hello member
[END]
[site("identifier") == "lindenau"]
lib.footer.value = Lindenau Music School
[END]
[tree.pagelayout == "pagets__home"]
page.10.value = Home page
[END]
[request && request.getNormalizedParams().getHttpHost() == "www.lindenau.example"]
config.admPanel = 0
[END]What the conditions check:
frontend.user.isLoggedInis true when a frontend user is logged in. You check groups withfrontend.user.userGroupIds.backend.user.isAdminchecks whether an admin is logged in to the backend.- The function
site()returns values from the site configuration such as identifier, base or rootPageId. For the language there issiteLanguage(). tree.pagelayoutalso takes into account the backend layout that a parent page passes on to its subpages. The backend_layout field of the page itself, by contrast, only checks that page.- The function
traverse()reads values from arrays such as page, for example the uid of the current page. - The function
session()reads values from the frontend session. A vertical bar goes one level deeper into the stored structure. - The normalized parameters of the request return the host, the HTTPS status and more.
New in TYPO3 14: The function getTSFE() has been removed. Conditions using it never match anymore. You now get the page ID from the PageArguments of the request.
The old syntax from before the Expression Language, for example with globalVar, globalString, usergroup or loginUser, has not worked since TYPO3 10.
[request?.getPageArguments()?.getPageId() == 42]
[traverse(page, "uid") in [17,24]]
[session("foo|bar") == 1234567]Data sources with getText
The data property fetches a value from a data source. Its value is a getText expression made of a key, a colon and a code. The key page with the code title, for example, returns the title of the current page. Not the title of the website and not the one of the home page.
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, slideThe most important keys:
fieldreads a field of the current record. That is the record being rendered right now, such as a content element or the page.pagereads a field of the current page.DBreads a field of a specific record from any TCA table. The code names table, uid and field, for example tt_content, 12 and header. Deleted records return nothing.levelfieldfetches a field from the rootline. Minus one is the current page. With slide, TYPO3 goes up until a value is not empty. This way you take over, for example, a backend layout from parent pages. Similarly,leveltitlereturns page titles from the rootline.sitereturns values from the site configuration such as base or identifier.siteLanguagereturns values of the current language.siteSettingsreads a value from the site settings, such as Mara's phone number.requestreads attributes of the PSR-7 request.assetreturns the URL of a public file with cache busting.applicationcontextreturns the application context, such as Production.
Two slashes chain getText expressions as fallbacks. The first value that is not empty wins. In the example you get the header, and only if it is empty, the title. Here the two slashes are not a comment.
Field value or record? With data and field you fetch a single value. Whole records, by contrast, are fetched by content objects such as CONTENT and RECORDS or by a data processor.
parseFunc: outputting text from the editor
Text from the rich text editor, RTE for short, is HTML. Before it appears in the frontend, the function parseFunc processes it. The usual configuration for this is called lib.parseFunc_RTE. It converts links with typolink, for example internal links starting with t3 and a colon, into real URLs. It allows, removes or changes HTML tags, controlled by properties such as tags, allowTags, denyTags and externalBlocks. Finally it sends the text through the HTML Sanitizer. parseFunc does not execute PHP code, and it does not translate or upload anything.
New in TYPO3 14: Neither the frontend extension nor Fluid Styled Content presets allowTags anymore. All tags are allowed at first. The HTML Sanitizer decides which tags and attributes remain. The allowTags property still exists, though. If you set it, you restrict the output on purpose.
# Behaves differently in TYPO3 14: allows only wbr
lib.parseFunc_RTE.allowTags := addToList(wbr)Debugging: Active and Included TypoScript
TypoScript is assembled from many sources and conditions. To see what really applies on a page, you open the module “Sites” and there “TypoScript”. It has two important views.
- Active TypoScript shows the constants and setup of a page as a tree. This is the result after all includes and conditions have been applied.
- Included TypoScript shows the includes with their origin and order. Here you see which sets, files and records are loaded. This view also warns about syntax errors.
- In the frontend, the placeholder of a constant appears literally instead of the phone number.
- In Active TypoScript, Mara checks whether the constant is defined on this page at all and what exactly it is called.
- In Included TypoScript, she checks whether the file with the constant is loaded, in which order, and whether a syntax warning appears.
- She finds a typo in the name and fixes it.
Clearing the browser cache does not help here. A placeholder that was not replaced means TYPO3 does not know the constant.
Page TSconfig: adapting the backend
Page TSconfig has the same syntax as TypoScript, but a different job. It controls the backend per page or page tree, for example visible fields, default values or the wizard for new content elements. It does not control the frontend, the web server or the permissions of frontend users. Page TSconfig does not end up in the frontend page cache either.
There are three usual places:
- A file
page.tsconfigin theConfigurationfolder of an extension applies globally to the whole installation. - A file
page.tsconfigin the folder of a site set only applies to the pages of the sites that use the set. The file for the frontend, by contrast, is calledsetup.typoscript. - The TSconfig field in the page properties applies to the page and is inherited by all subpages.
Mara wants to tidy up the form for the editors. With TCEFORM she adjusts form fields. The property disabled with the value 1 hides a field. Labels and selectable values can be changed this way too. TCEMAIN, by contrast, concerns saving, not the form.
She sets default values with TCAdefaults. Since TYPO3 14 this also works depending on the record type, through the sub key types. A type-specific value takes precedence over the general value of the field. Page TSconfig overrides User TSconfig here.
TCEFORM.tt_content.layout.disabled = 1
TCAdefaults.tt_content.header_layout = 2
TCAdefaults.tt_content.header_layout.types.textmedia = 3Key points
- TypoScript is a configuration language and becomes a PHP array internally.
- The equals sign assigns, less-than copies, equals followed by less-than references, greater-than deletes, colon followed by equals calls a function.
- A copy freezes the state of its line. A reference is only resolved when a content object is rendered.
- Sets ship their TypoScript in
setup.typoscriptnext to theirconfig.yaml. Sets the site depends on come first, site settings override constants. - Conditions use the Symfony Expression Language. The function
getTSFE()no longer exists in TYPO3 14. - The
dataproperty fetches values with getText, for example from page, field, siteSettings or request. allowTagsis no longer preset in TYPO3 14.- Active TypoScript shows the result, Included TypoScript shows the includes.
- Page TSconfig controls the backend and is inherited down the page tree.
Terms
- Content object
- Object that produces output, such as TEXT, COA or IMAGE.
- getText
- Expression made of a key and a code that fetches a value from a data source.
- Constant
- Placeholder that TYPO3 inserts into the setup before evaluating it.
- Page title provider
- Source for the page title, whose order config.pageTitleProviders defines.
- Page TSconfig
- Configuration of the backend per page or page tree.
- Site set
- Package of TypoScript, settings and page TSconfig that a site includes.
- Top-level object
- Name on the top level of the TypoScript tree, such as page, config or lib.