TypoScript

What TypoScript is for

In TYPO3, TypoScript answers the question of what appears on a page. Which templates apply, how content elements are rendered, which menus exist, how images are processed, what metadata ends up in the head of the page: all of that sits in TypoScript.

The structure is a nested arrangement of keys and values. Anyone who has edited a configuration file before finds their way quickly; what takes getting used to is how much can be steered from there.

Setup and constants

TypoScript has two areas. The setup holds the actual configuration. The constants hold values needed in several places: paths, page IDs, basic settings.

The point of the split is maintainability. When the ID of a page changes, it should change in one place and not in seven. The same reasoning sits behind variables in any other configuration.

Conditions

Conditions let parts of the configuration activate depending on context: by language, by area of the site, by user group. This is powerful and readily overused.

As a rule of thumb: when a configuration contains more conditions than values, the structure of the site is usually the real problem rather than the configuration.

Where it turns up in a project

TypoScript appears in almost every TYPO3 project that goes beyond the default output. It is the place where the sitepackage is connected to the system, and usually the first place you look when the frontend does not look the way you expected.

How TypoScript reaches the installation

Historically, TypoScript hangs off a record in the page tree. It points at files in the sitepackage and defines from which page the configuration applies. Further down the tree a second record can extend or override it.

Since TYPO3 13 there is a second route, Site Sets: an extension declares a set, the site configuration includes it, and TypoScript, page TSconfig and settings all come along together. The advantage is that the assignment sits in files rather than in the database. More on that under Site Set.

Objects rather than instructions

TypoScript describes objects, not procedures. A PAGE object stands for the page to be output, a FLUIDTEMPLATE brings in a Fluid template along with its variables, a COA groups several parts, HMENU builds a menu, CONTENT fetches records from the database.

These objects nest inside each other. That is where the impression comes from that TypoScript is a programming language. It is not: there are no loops in the usual sense and no functions of your own, but a large set of ready-made objects with a great many properties.

stdWrap

Many properties can be post-processed with stdWrap: shorten text, format a date, set a default, wrap something, strip HTML. The same collection of functions is available in a very large number of places.

That explains why TypoScript examples found online are often surprisingly short. What looks like a special function is usually stdWrap on yet another property.

What TypoScript is not

TypoScript configures the frontend. For the backend there is TSconfig, which uses the same syntax but steers different things: which content elements are on offer, what the page tree looks like, which fields an editor sees.

The similarity of the names causes confusion reliably. Look for a backend setting and change it in TypoScript, and you will wait a long time for an effect.

When something does not take

The backend has a module of its own for TypoScript. It shows the assembled configuration for a particular page, and that is exactly the decisive point when something goes wrong: what applies is the result of several inclusions, of conditions, and of the position in the page tree.

The second most common reason is mundane. The configuration is correct but is not included on the page you are looking at.