First steps

The basic rendering is defined in the "Setup" field of the main TypoScript record.

TypoScript essentially consists of objects, which have certain properties. Some of these properties can accept other objects, others stand for functions or simple values.

The PAGE object is responsible for the rendering of a website page in the frontend:

# The object page is defined as PAGE object.
page = PAGE

# PAGE objects have the property typeNum.
page.typeNum = 0

# page has an object "10" of type TEXT. It is a TEXT object.
page.10 = TEXT

# TEXT objects in turn have a property called "value".
page.10.value = Hello World

The PAGE object on the one hand offers numerous named properties (like typeNum). On the other hand it also has an endless number of numbered objects (a so-called content array). The names of these objects only consist of numbers and the objects are sorted accordingly when they are rendered, from the smallest number to the largest. The order of the lines in the TypoScript record is irrelevant:

# Create a PAGE object.
page = PAGE
page.typeNum = 0

page.30 = TEXT
page.30.value = This gets rendered last.

# Rendering will first output object number 10, then 20 and 30.
# An object with number 25 would logically be output between 20 and 30.
page.20 = TEXT
page.20.value = This is rendered in the middle.

# This is the first output object
page.10 = TEXT
page.10.value = This is rendered first.

# Here we create a second PAGE object, which we can use for the
# print view.
print = PAGE
print.typeNum = 98
print.10 = TEXT
print.10.value = This is the print version.

Every entry is stored in a multidimensional PHP array. Every object and every property, therefore, is unique. We could define an arbitrary number of PAGE objects; however, the typeNum has to be unique. For every typeNum, there can be only one PAGE object.

In the example, for the parameter typeNum = 98, a different output mode is created. By using typeNum, various output types can be defined. If typeNum is not set explicitly, it defaults to "0". Typically, typeNum = 0 is used for the HTML output.

When a page is requested with just index.php?id=1, typeNum = 0 will be assumed and the output will be HTML. To get the print output, the request will have to pass a "type" attribute, i.e. index.php?id=1&type=98.

It is thus possible to generate many different outputs depending on one's needs (XML, JSON, PDF, etc.). TypoScript configuration can be copied between those various views, changing only what's specific for each of them.

The previous example would look like this as a PHP array:

<?php

$TypoScript['page'] = 'PAGE';
$TypoScript['page.']['typeNum'] = 0;
$TypoScript['page.']['10'] = 'TEXT';
$TypoScript['page.']['10.']['value'] = 'This is rendered first.';
$TypoScript['page.']['20'] = 'TEXT';
$TypoScript['page.']['20.']['value'] = 'This is rendered in the middle.';
$TypoScript['page.']['30'] = 'TEXT';
$TypoScript['page.']['30.']['value'] = 'This gets rendered last.';

$TypoScript['print'] = 'PAGE';
$TypoScript['print.']['typeNum'] = 98;
$TypoScript['print.']['10'] = 'TEXT';
$TypoScript['print.']['10.']['value'] = 'This is the print version.';

Empty spaces at the start and end of values are removed by TYPO3 CMS automatically (using the PHP trim() function).

The = sign corresponds to a simple assignment. Here is an overview of the various operators:

# The object test is an object of type TEXT.
# "=" means "set value".
test = TEXT
test.value = Holla

# "<" means "copy object".
# page.10 returns "Holla"
page.10 < test

# Change the original object.
# The change has no effect on page.10; it still returns "Holla".
test.value = Hello world

# "=<" means "create an object reference (link the object)".
test.value = Holla
page.10 =< test

# Change the object which is referenced.
# Changes DO have an effect on page.10.
# page.10 will return "Hello world".
test.value = Hello world

Object types are always written with capital letters; parameters and functions typically in camel case (first word lower case, next word starts with a capital letter, no space between words). There are some exceptions to this.

With the . as a separator parameter, functions and child objects are referenced and can be assigned values accordingly:

page.10.stdWrap.wrap = <h1>|</h1>

The TypoScript Reference (TSref) is the ultimate resource to find out which objects, functions and properties exist.

Things can get more complicated when objects are nested inside each other and many properties are used:

page = PAGE
page.typeNum = 0
page.10 = TEXT
page.10.value = Hello world
page.10.stdWrap.typolink.parameter = http://www.typo3.org/
page.10.stdWrap.typolink.additionalParams = &parameter=value

# The function name "ATagParams" does not use the standardized
# "camelCase".
page.10.stdWrap.typolink.ATagParams = class="externalwebsite"
page.10.stdWrap.typolink.extTarget = _blank
page.10.stdWrap.typolink.title = The website of TYPO3
page.10.stdWrap.postCObject = TEXT
page.10.stdWrap.postCObject.value = This text also appears in the link text
page.10.stdWrap.postCObject.stdWrap.wrap = |, because the postCObject is executed before the typolink function.

To make things clearer, TypoScript code can be structured using curly braces ({}) at each nesting level:

page = PAGE
page {
  typeNum = 0

  10 = TEXT
  10 {
    value = Hello world
    stdWrap {
      typolink {
        parameter = http://www.typo3.org/
        additionalParams = &parameter=value

        # The function name "ATagParams" does not use the standardized
        # "camelCase".
        ATagParams = class="externalwebsite"

        extTarget = _blank
        title = The website of TYPO3
      }

      postCObject = TEXT
      postCObject {
        value = This text also appears in the link text
        stdWrap.wrap (
                  |, because the postCObject is executed before the typolink function.
        )
      }
    }
  }
}

Important

The opening curly brace must always be on the same line as the property.

Parenthesis (()) are used for writing text values on more than one line.

Using this style of notation reduces the danger of typographic errors and makes the script easier to read. In addition it reduces the repetition of variable names making it easier to rename an object.

The full reference for the syntax is found in the TypoScript Syntax and In-depth Study.