TypoScript is the configuration language of TYPO3. It is (especially in the beginning) hard to understand and to get the big picture, how it works. In this post I will try to shed some light on it and will help to understand whats happening.
What is TypoScript?
TypoScript is not scripting language, even if the name suggests it. But it has some components, which apply functionality onto content objects. This is confusing at the first sight, but opens a lot of possibilities. 🙂
The second main thing is, that all TypoScript is collected down to the page where it is used. All TypoScript is collected and a plain array is build. This array is built in a certain order. The order is
1) TypoScript constants from extensions
2) TypoScript from ext_typoscript_constants.txt
3) TypoScript setup from extensions
4) TypoScript from ext_typoscript_setup.txt
5) TypoScript (constants and setup) from database entries
The database entries are collected from the top of the page tree until the page, where the output is created. All set values overwrite the prior ones.
Top level elements
There are only four main top level objects:
* plugin and
This namespace is reserved for plugins.
plugin is followed by a unique key. Usually it is
tx_ followed by the the name of the extension, like
The key value pairs beneath this construct is in the responsibility of the extension author.
The top level object
config contains configuration values, which are valid for each page object in the same page tree.
meta defines the meta tags which appear in the head of the website, like description, keywords, author et al.
In each TYPO3 website, there must be at least one of these objects. Usually this object defines how a website looks like. It can also output RSS feeds, json array or whatever format the website should deliver.
The default typeNum value is
0. All other values must be set explicitly. Settings from the config and the meta object can be overwritten in this area of TypoScript.
Here a (very) short code example:
page = PAGE
typeNum = 0
# This section overrides the top config values
# This section override the top meta values
10 = TEXT
10.value = Hello World
The code example above shows also the number “10” with the content object “TEXT”. There can be any number of content objects. The content objects are sorted by the number, the placement in the code does not play any role.
There are 18 content objects available. The complete list is available on docs.typo3.org
Each of them has a set of properties, which define their rendering. Each property can be a data type or a function. The applicable data types and functions are linked in the documentation right after the property.
Data types are string or number values, which are interpreted in the context of the content object.
A special data type is “getText”, which allows to retrieve values from from a variety of sources like the page title, variables from GET and POST requests or environment variables.
The other type of properties are functions. Functions do something with the value of the property. The main functions to deal with are
if poses a condition on the parent. The parent is only rendered, if the condition returns true.
typolink renders any link around content objects or return just the url.
A special case is the
stdWrap. It is some kind of a swiss knife regarding TypoScript, as is is available on many content objects properties.
If there is a value and also a
stdWarp, the output of the
stdWrap has many many properties, which I did not count. All these properties have also datatypes, as any other content object. It has also the property
stdWrap. Saying that means that it allows a infinite recursion, if done right.
With all these properties, it is sometimes hard to understand the outcome. The reason is, that all instructions are interpreted in a certain order. This order is not the same as with the numeric ordering of the content objects. The ordering is defined in the source code of TYPO3. The following picture lists all stdWrap functions and order, in which they are .
Not every TypoScript configuration is valid under all circumstances. This is where TypoScript conditions help to apply other than the default values. All possible conditions are documented under https://docs.typo3.org/typo3cms/TyposcriptReference/Conditions/Reference/Index.html
There are two possible endings for a condition.
[global]. The last statement ends all open conditions, whereas
[end] only terminates the last condition. I like the
end-version more because an error may occur earlier than with the
If a site uses much TypoScript, it can be quite confusing which value is used on a certain page and where it is set. Fortunately TYPO3 offers two tools for debugging TypoScript.
TypoScript Object Browser
The TypoScript Object Browser shows a tree representation of the constants or setup with all values. Values, which are are valid on the selected page are shown. All elements can be (un-)collapsed for better navigation.
Furthermore, at the bottom of page it is possible to activate the conditions, which shall apply on this page.
If there is a template on the page, it is possible to change the value with a click on the property. The new value is written at the end of the TypoScript template in the database. (Tipp: Be careful and cleanup the template afterwards 😉 )
The Template Analyzer displays portions of or the complete TypoScript. This helps to identify in which file or in which template record a value is set. The loading order is the same as TYPO3 loads it in the rendering process.
If you are starting with TypoScript, it is hard to get the big picture. I hope, I succeeded in creating an understanding how TypoScript works.
I want to thank my supporters via patreon.com, who make this blog post possible. Last week a new silver sponsor hit my patreon list.
Thank you, Falk Röder for becoming a patreon. 🙂
If you also appreciate my blog and want to support me, you can say “Thank You!”. Find out the possibilities here: