Frontend TypoScript

Frontend TypoScript is mainly used to configure which data should be send to the Fluid templates.

It can also be used to define settings send to Extbase plugins, metadata for a whole page etc.

In the beginning of TYPO3, TypoScript was used as templating language. In modern project it is not common to do that anymore.

For an introduction see Getting started: A quick introduction into TypoScript.

Backend TypoScript / TSconfig

Backend TypoScript, also called TSconfig, can be used to configure the output of certain forms etc in the TYPO3 backend.

Backend configuration

TypoScript influences many aspects of a TYPO3 site:

TypoScript can be used in the TSconfig field of a backend user or a backend user group or in the TSconfig field of a page. It will then change the look and behavior of forms in the backend.

The frontend rendering in contrast is defined by the TypoScript used in TypoScript records. This document covers only frontend rendering.

Prerequisites

It is assumed that you have a running TYPO3 installation. See TYPO3 Getting Started Tutorial, installing TYPO3 with DDEV.

and that you have been through the TYPO3 - Getting Started Tutorial in order to have a general idea of how the TYPO3 CMS backend operates.

A few more elements that you need to know before starting:

• all content elements are stored in a database table called tt_content
• each content element has a database field called CType in which the type of the content element is stored
• the tt_content table also has a field called pid which refers to the page the content element is on
• in general, each TYPO3 CMS table has a field called uid which contains the primary key (unique id for each record)
• you will probably find useful to have a database access to check how information is stored as we proceed along this tutorial

Why TypoScript?

Strictly speaking, TypoScript is a configuration language. We cannot program with it, but can configure a TYPO3 CMS website in a very comprehensive way. With TypoScript, we define the rendering of the website, including navigation, generic content, and how individual content elements are rendered on a page.

TYPO3 CMS is a content management system that clearly separates content and design. TypoScript is the glue that joins these two together again. TypoScript reads content which is stored in the database, prepares it for display and then renders it in the frontend.

To render a website, we only need to define what content to display and how it will be rendered.

• The "what" is controlled by the backend - where pages and content are generated.
• The "how" is controlled by TypoScript.

With TypoScript, we can define how the individual content elements are rendered in the frontend. For example, we can use TypoScript to add a <div> tag to an element, or the <h1> tag to a headline.

The main TypoScript record

The TypoScript code used to define how pages are rendered is located in the "main" TypoScript record. In this record a so-called "rootlevel flag" is set.

When the frontend renders a page, TYPO3 CMS searches along the page tree up to the root page to find a "main" TypoScript record. Normally, there are additional TypoScript records besides the "main" TypoScript record. For now, we will assume we are only using the "main" TypoScript record.

TypoScript syntax is very straightforward. On the left side, objects and properties are defined. On the right side are the assigned values. Both objects and properties can contain other objects. Object properties are defined by using the dot "." notation.

The following is a typical example of TypoScript syntax:

page = PAGE
page.10 = TEXT
page.10.value = Hello World

The term "template"

Sometimes the term "template" is used as a synonym for the TypoScript record or the combined TypoScript configuration from all sources. This has historic reasons. Until TYPO3 v11 TypoScript could be edited in a backend module called "Template". In the beginning of TYPO3 sites were build almost exclusively with TypoScript while it slowly evolved to be mainly a configuration language.

As a Fluid template is also called "template" the terms took on a double meaning in TYPO3. With TYPO3 v12 we speak about TypoScript records, TypoScript files and the complete TypoScript configuration. However you will still find the outdated term "TypoScript template" or just "template" in places.

Troubleshooting

Common mistakes made in the TypoScript configuration can cause a message like this:

If you turn on the debug mode you will get more detailed information:

No TypoScript record found!: This warning appears if no TypoScript record, with the root level flag enabled, is found in the page tree.

The page is not configured! [type=0][]. This means that there is no TypoScript object of type PAGE with typeNum=0 configured.: This warning appears if the TypoScript Configuration of the current page contains no :ref:PAGE <guide-page>` definition.

The following TypoScript setup code is enough to remove this warning:

page = PAGE
page.10 = TEXT
page.10.value = Hello World

Copied!

Do not worry about this code for now, it will be explained later.

TypoScript is just an array

Internally, TypoScript is parsed and stored as a PHP array. For example:

page = PAGE
page.10 = TEXT
page.10.value = Hello World
page.10.stdWrap.wrap = <h2>|</h2>

will be converted to the following PHP array:

<?php

$data = [
    'page' => 'PAGE',
    'page.' => [
        '10' => 'TEXT',
        '10.' => [
            'value' => 'Hello World',
            'stdWrap.' => [
                'wrap' => '<h2>|</h2>',
            ],
        ],
    ],
];

Upon evaluation, a "PAGE" object will be created first, and the parameter $data['page.'] will be assigned to it. The "PAGE" object will then search for all properties, which it knows about. In this case, it will find a numeric entry ("10"), which has to be evaluated. A new object of type "TEXT" with the parameter $data['page.']['10.'] will be created. The "TEXT" object knows the parameters value and stdWrap. It will set the content of value accordingly. The parameters from stdWrap will be passed to the "stdWrap" function. There the property 'wrap' is known, and the text "Hello world" will be inserted at the pipe (|) position and returned.

It is important to be aware of this relationship in order to understand the behaviour of TypoScript. For example, if the above TypoScript is extended with the following line:

page.10.myFunction = Magic!

the following entry will be added to the PHP array:

$data['page.']['10.']['myFunction'] = 'Magic!';

However, the "TEXT" object does not know any property called "myFunction". Consequently, the entry will have no effect.

Displaying the page body with TypoScript

Numeral indexes on the PAGE object are used to output the actual content of the page. Many integrators like to use the index 10.

As we already saw in section First steps, the following code outputs "Hello World!":

page = PAGE
page {
  10 = TEXT
  10.value = Hello World!
}

In a more common use case you want to load the page content from a Fluid template:

page = 10
page {
  10 = PAGEVIEW
  10 {
    paths {
      100 = EXT:my_site_package/Resources/Private/PageView/
    }
    dataProcessing {
      10 = page-content
    }
  }
}

You need at least a Minimal site package (see site package tutorial) to keep your templates in its private resources folder, for example /packages/site_package/Resources/Private/Templates:

<main>
    <p>Hello World!</p>
</main>

Loading CSS in TypoScript

You can write inline CSS using property cssInline.[array], or place your CSS file in the public resources of your Minimal site package:

page = PAGE
page {
  10 = TEXT
  10.value = <div class="myTodo">TODO: Add Fluid template </div>
  cssInline {
    10 = TEXT
    10.value (
      .myTodo {
        border: 2px solid #ee7600;
      }
    )
  }
  includeCSS {
    styles = EXT:site_package/Resources/Public/Css/styles.css
  }
}

Loading JavaScript in TypoScript

You can write inline JavaScript using property jsFooterInline.[array], or place your JavaScript file in the public resources of your Minimal site package:

page = PAGE
page {
  10 = TEXT
  10.value = <div class="myTodo">TODO: Add Fluid template </div>
  jsFooterInline {
    10 = TEXT
    10.value (
      alert("Hello World! ");
    )
  }
  includeCSS {
    includeJSFooter = EXT:site_package/Resources/Public/JavaScript/main.js
  }
}

Favicon / shortcut icon definition in the TypoScript PAGE

Use property shortcutIcon to define the favicon:

page = PAGE
page {
  shortcutIcon = EXT:site_package/Ressources/Public/Icons/favicon.ico
  10 = TEXT
  10.value = TODO: Add Fluid template
}

You need to have a Minimal site package (see site package tutorial) and put the favicon file in the public resources folder of that site package. If you followed the instruction from the site package tutorial that would be path /packages/site_package/Resources/Public/Icons.

Tracking code: Add content to the end of your page

You can use the property footerData.[array] to enter some HTML code just before the closing </body> tag:

page = PAGE
page {
  10 = TEXT
  10.value = TODO: Add Fluid template
  footerData {
    10 = TEXT
    10.value (
      <!-- Enter some tracking code supplied by your provider -->
      <p>My tracking code</p>
    )
  }
}

Insert content in a HTML template

Although we now know how to render content, we do not have a real website yet.

Again everything could be done using TypoScript. That would be pretty complex and error prone. Furthermore if a HTML template file is prepared by a designer for the website, it would be a shame not to reuse it as is as much as possible. It would also make further corrections to the HTML template much harder to apply.

TYPO3 CMS provides the FLUIDTEMPLATE object, with which we can use Fluid template and render our website with it:

10 = FLUIDTEMPLATE
10 {
  templateName = Default

  templateRootPaths {
    0 = EXT:site_package/Resources/Private/Templates/Pages/
  }
  partialRootPaths {
    0 = EXT:site_package/Resources/Private/Partials/Pages/
  }
  layoutRootPaths {
    0 = EXT:site_package/Resources/Private/Layouts/Pages/
  }
}

In your template file you can now replace the parts that should be filled by TYPO3 with references to the TypoScript configuration objects you defined earlier.

For example to render a template with the menu we defined add:

<nav>
    <f:cObject typoscriptObjectPath="lib.textmenu" />
</nav>

<div class="container">
    <f:cObject typoscriptObjectPath="lib.dynamicContent" data="{pageUid: '{data.uid}', colPos: '0'}" />
</div>

The various content elements

The setup we just defined is pretty basic and will work only for content elements containing text. But the content elements are varied and we also need to render images, forms, etc. and we do not want to define everything in TypoScript - using HTML templates would be more convenient.

The type of a content element is stored in the column CType of table "tt_content". We can use this information with a CASE object, which makes it possible to differentiate how the individual content element types are rendered.

The following code is the default TypoScript rendering definition as taken from the TYPO3 Core. The default renderObj of a table is a TypoScript definition named after that table. In case of content in TYPO3 the table is called tt_content therefore the default renderObj is also called tt_content:

tt_content = CASE
tt_content {
  key {
    # The field CType will be used to differentiate.
    field = CType
  }
  # Render a error message in case no specific rendering definition is found
  default = TEXT
  default {
    field = CType
    htmlSpecialChars = 1
    wrap = <p style="background-color: yellow; padding: 0.5em 1em;"><strong>ERROR:</strong> Content Element with uid "{field:uid}" and type "|" has no rendering definition!</p>
    wrap.insertData = 1
  }
}

The basic extension for rendering content in TYPO3 since TYPO3 v8 is fluid_styled_content. The example shows how fluid_styled_content is set up: It defines a basic content element based on the content object FLUIDTEMPLATE which is able to render html templates using the Fluid templating engine. For every content element, the basic template, layout and partial parts are defined. As you can see by looking at the lines starting with 10 = there is the possibility to add your own templates by setting the corresponding constant (in the Constants section of a TypoScript record):

lib.contentElement = FLUIDTEMPLATE
lib.contentElement {
  templateName = Default
  templateRootPaths {
    0 = EXT:fluid_styled_content/Resources/Private/Templates/
    10 = {$styles.templates.templateRootPath}
  }
  partialRootPaths {
    0 = EXT:fluid_styled_content/Resources/Private/Partials/
    10 = {$styles.templates.partialRootPath}
  }
  layoutRootPaths {
    0 = EXT:fluid_styled_content/Resources/Private/Layouts/
    10 = {$styles.templates.layoutRootPath}
  }
  # ...
}

Each content element inherits that configuration. As an example take a look at the content element definition of the content element of type header:

# Header Only:
# Adds a header only.
#
# CType: header
tt_content.header =< lib.contentElement
tt_content.header {
  templateName = Header
}

First, all configuration options defined in lib.contentElement are referenced. Then the templateName for rendering a content element of type header is set - in this case Header. This tells fluid to look for a Header.html in the defined template path(s) (see above, by default in EXT:fluid_styled_content/Resources/Private/Templates/).

To adjust how the default elements are rendered you can overwrite the templates in your own site package extension and set the TypoScript constants defining the paths (see above). In your own templates you have the data of the currently rendered content element available in the {data} fluid variable. For example take a look at how the text element is rendered:

<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers" data-namespace-typo3-fluid="true">
<f:layout name="Default" />
<f:section name="Main">
    <f:format.html>{data.bodytext}</f:format.html>
</f:section>
</html>

The database field bodytext from the tt_content table (which is the main text input field for content elements of type text) is available as {data.bodytext} in the Fluid template. For more information about fluid_styled_content see its manual.

Heed the order

The single most important thing to know about stdWrap is that all properties are parsed/executed exactly in the order in which they appear in the TypoScript Reference, no matter in which order you have set them in your TypoScript record.

Let's consider this example:

10 = TEXT
10 {
  value = typo3
  noTrimWrap = |<strong>Tool: |</strong>|
  case = upper
}

It results in the following:

<strong>Tool: TYPO3</strong>

The case property is executed before the noTrimWrap property. Hence only "typo3" was changed to uppercase and not the "Tool:" with which it is wrapped.

Modify the order

There is a way around this ordering restriction. stdWrap has a property called orderedStdWrap in which several stdWrap properties can be called in numerical order. Thus:

10 = TEXT
10 {
  value = typo3
  orderedStdWrap {
    10.noTrimWrap = |<strong>Tool: |</strong>|
    20.case = upper
  }
}

results in:

<strong>TOOL: TYPO3</strong>

because we explicitly specified that noTrimWrap should happen before case.

It should be noted that stdWrap itself has a stdWrap property, meaning that it can be called recursively. In most case orderedStdWrap will do the job and is much easier to understand making code easier to maintain.

The data type

While writing TypoScript, it is crucial to know what kind of data type you are handling. It is common to see beginners try to combine functions arbitrarily, until the anticipated result is finally achieved by accident.

The TypoScript reference is very clear about which properties exist and what their data type is, so please refer to that essential resource while writing your TypoScript configuration.

cObject

The stdWrap property "cObject" can be used to replace the content with a TypoScript object. This can be a COA, a plugin or a text like in this example:

10.typolink.title.cObject = TEXT
10.typolink.title.cObject {
  value = Copyright
  case = upper
}

Site as a TypoScript provider

The files setup.typoscript and constants.typoscript (placed next to the site's config.yaml file) will be loaded as TypoScript setup and constants, if available. See also Site handling.

Site dependencies (sets) will be loaded first, that means setup and constants can be overridden on a per-site basis.

base: 'http://example.com/'
rootPageId: 1
dependencies:
  - myvendor/my-sitepackage

page.headerData {
    50 = TEXT
    50.value = <!-- This is only displayed in the header of site example.org -->
}

page.trackingCode = 123456

Set as a TypoScript provider

Set-defined TypoScript can be shipped within a set. The files setup.typoscript and constants.typoscript (placed next to the config.yaml file of the set) will be loaded, if available. They are inserted into the TypoScript chain of the site TypoScript that will be defined by a site that is using sets.

Set constants will always be overruled by site settings. Since site settings always provide a default value, a TypoScript constant will always be overruled by a defined setting. This can be used to provide backward compatibility with TYPO3 v12 in extensions, where constants shall be used in v12, while v13 will always prefer defined site settings.

TypoScript dependencies dependencies to TypoScript in other extensions or other sets are to be included via site sets.

Dependencies are included recursively. Sets are automatically ordered and deduplicated. That means TypoScript will not be loaded multiple times, if a shared dependency is required by multiple sets.

name: myvendor/my-sitepackage
label: My sitepackage set

# Load TypoScript, TSconfig and settings from dependencies
dependencies:
  - typo3/fluid-styled-content
  - typo3/felogin

@import 'EXT:my_sitepackage/Configuration/TypoScript/Constants'

@import 'EXT:my_sitepackage/Configuration/TypoScript/Setup'

Provide TypoScript in your extension or site package

TypoScript files must have the ending .typoscript.

They are located in Configuration/Sets/MySet within your extension. Read more about how to provide the TypoScript as set for TYPO3 v13 and above and how to provide TypoScript for both TYPO3 v13 and v12.

• constants.typoscript contains the frontend TypoScript constants
• setup.typoscript contains the frontend TypoScript

TypoScript provided as site set (only TYPO3 v13.1 and above)

The file structure of the extension could, for example look like this:

With the extension's TypoScript residing in EXT:my_extension/Configuration/Sets/MyExtension and the TypoScript for some optional feature in EXT:my_extension/Configuration/Sets/MyExtensionWithACoolFeature. Let us assume, that the optional feature depends on the main TypoScript.

The sets can now be defined for TYPO3 v13 as follows:

name: myvendor/my-extension
label: My Extension, main set

name: myvendor/my-extension-with-a-cool-feature
label: Set for a cool feature

# This feature depends on the TypoScript and settings of the main set
dependencies:
  - myvendor/my-extension

name: my-vendor/my-site-package
label: My Set
dependencies:
  - my-vendor/my-other-set
  - some-vendor/some-extension

plugin.some_extension_pi1.settings.someSetting = Special setting

Supporting both site sets and TypoScript records

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile(
    'my_extension',
    'Configuration/TypoScript/',
    'Examples TypoScript'
);

@import 'EXT:my_extension/Configuration/TypoScript/setup.typoscript'

@import 'EXT:my_extension/Configuration/TypoScript/setup.typoscript'

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile(
    'my_extension',
    'Configuration/TypoScript/',
    'My Extension - Main TypoScript'
);

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile(
    'my_extension',
    'Configuration/TypoScript/Example1/',
    'My Extension - Additional example 1'
);

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile(
    'my_extension',
    'Configuration/TypoScript/SpecialFeature2/',
    'My Extension - Some special feature'
);

@import 'EXT:my_extension/Configuration/TypoScript/MySpecialFeature2Set/setup.typoscript'

Make TypoScript available (always load)

Use ExtensionManagementUtility::addTypoScript if the frontend TypoScript must be available in backend modules without page context, for example to register the YAML of the EXT:form system extension for the backend.

<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTypoScript(
    'my_extension',
    'setup',
    '
        module.tx_form {
            settings {
                yamlConfigurations {
                    100 = EXT:my_site_package/Configuration/Form/CustomFormSetup.yaml
                }
            }
        }
    ',
);

More information

• TypoScript imports (in "Sitepackage Tutorial")`
• Site settings: Further configuration options (in "Sitepackage Tutorial")`

Submodule "TypoScript records overview"

This submodule shows all pages that contain TypoScript either by having a TypoScript record or by having a Site Set TypoScript provider.

If TypoScript was added by a record, it is linked.

Submodule "Constant Editor"

The backend module Site Management > TypoScript > Constant Editor used a special format of Comments to display a form for editing the constants.

It is not recommended to newly introduce constants in the constant editor. The documentation of the constant editors comment format can still be found at Comment Syntax

Submodule "Edit TypoScript Record"

This can be done in the Site Management > TypoScript module in the submodule Edit TypoScript Record.

When you click on Edit the whole TypoScript record you can edit the complete record:

As the TypoScript record is just a normal record it can also be seen in and edited from the list module:

# Import a single file
@import 'EXT:my_site_package/Configuration/TypoScript/randomfile.typoscript'

# Import multiple files of a single directory in file name order
@import 'EXT:my_site_package/Configuration/TypoScript/*.typoscript'

# The filename extension can be omitted and defaults to .typoscript
@import 'EXT:my_site_package/Configuration/TypoScript/'

Include other TypoScript records

Apart from this, it is also possible to include other TypoScript template records (in the field called Include TypoScript records).

Submodule "Included TypoScript"

With all those inclusions, it may happen that you lose the overview of the template structure. The submodule Included TypoScript provides an overview of this structure. It shows all the TypoScript files that apply to the currently selected page, taking into account inclusions and inheritance along the page tree.

TypoScript definitions are taken into consideration from top to bottom, which means that properties defined in one TypoScript location may be overridden in another location, considered at a later point by the TypoScript parser.

You can click on the {+} button to see details about the TypoScript definition and its includes.

Submodule "Active TypoScript"

You can use the submodule Active TypoScript to debug the configuration array build after all TypoScript configurations are parsed and combined. TypoScript Constants and Setup are listed separately here and Constant usage is shown. However there is no information what location the setting came from. Use the Submodule "Included TypoScript" to analyze where TypoScript was set and this module to look at the result.

Extbase controllers

In Extbase controllers, Flexform settings and TypoScript settings will be merged together. If settings exists in both, the Flexform takes precedence and overrides the TypoScript setting. Note that both Flexform and TypoScript settings must use the convention of preceding the setting with settings. (for example, settings.threshold).

Extbase offers some advantages: Some things work automatically out-of-the-box. However, you must stick to the Extbase conventions ("conventions over configuration").

In order to access TypoScript settings from an Extbase controller.

1. Use the convention of defining your TypoScript settings in settings

   EXT:my_extension/Configuration/TypoScript/setup.typoscript

   plugin.tx_myextension {
      view {
         # view settings
      }
   
      settings {
         key1 = value1
         key2 = value2
      }
   }

   Copied!

2. Access them via $this->settings

   For example, in your controller:

   $myvalue1 = $this->settings['key1'] ?? 'default';

   Copied!

Fluid

If Extbase controllers are used, $this->settings is automatically passed to the Fluid template. Allowing you to access settings like this:

{settings.key1}

Defining constants

Other than constants in programming languages, values of constants in TypoScript can be overwritten. Constants in TypoScript can more be seen as variables in programming languages.

Reserved name

The object or property "file" is always interpreted as data type resource. That means it refers to a file, which has to be uploaded in the TYPO3 CMS installation.

Multi-line values: The ( ) signs

Constants do not support multiline values!

You can use environment variables to provide instance specific values to your constants. Refer to getEnv for further information.

bgCol = red
file {
  toplogo = fileadmin/logo.gif
}
topimg {
  width = 200
  file.pic2 = fileadmin/logo2.gif
}

Using constants

When a TypoScript Template is parsed by the TYPO3 CMS, constants are replaced, as one would perform any ordinary string replacement. Constants are used in the "Setup" field by placing them inside curly braces and prepending them with a $ sign:

{$bgCol}
{$topimg.width}
{$topimg.file.pic2}
{$file.toplogo}

Only constants, which are actually defined in the Constants field or an included constants.typoscript file, are substituted.

Constants from included TypoScript files are also substituted. All TypoScript constants are combined before the TypoScript Setup configuration is resolved.

A systematic naming scheme should be used for constants. As "paths" can be defined, it's also possible to structure constants and prefix them with a common path segment. This makes reading and finding of constants easier.

Example

EXT:my_sitepackage/Configuration/TypoScript/setup.typoscript

page = PAGE
page {
  typeNum = 0
  bodyTag = <body class="{$tx_my_sitepackage.bgCol}">
  10 = IMAGE
  10.file = {$tx_my_sitepackage.file.toplogo}
}

Copied!

For the above example to work, the constants from the last example have to be defined in the constants field or a file called constants.typoscript:

EXT:my_sitepackage/Configuration/TypoScript/constants.typoscript

tx_my_sitepackage {
  bgCol = bg-primary
  file.toplogo = EXT:my_sitepackage/Resources/Public/Images/Logo.png
}

Copied!

You can use the sub module Site Management > TypoScript > Active TypoScript to display which values are assigned to constants. The constant key is displayed in red, the replacement in green:

Note

The TypoScript constants are evaluated in this order:

1. $GLOBALS['TYPO3_CONF_VARS']['FE']['defaultTypoScript_constants'] via \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTypoScriptConstants()
2. Site specific settings from the site configuration
3. Constants from sys_template database records

Defining registers

Registers in TypoScript can be seen as stack array variables in programming languages. Each register can store a complex TypoScript block. Use LOAD_REGISTER to put a variable to the stack, use RESTORE_REGISTER to pull a variable from the stack and curly braces around a variable name to read the current value of the variable. You need a or a cObject. The registers cannot be read on other places than inside of these cObjects.

Example

10 = COA
10 {
    ### left menu table column
    10 = LOAD_REGISTER
    10 {
        ulClass = col-left
    }

    ### right menu table column
    20 = LOAD_REGISTER
    20 {
        ulClass = col-right
    }

    30 = HMENU
    30 {
        special = list
        special.value = 1
        1 = TMENU
        # ...
        3 = TMENU
        3 {
            stdWrap {
                preCObject = COA
                preCObject {
                    10 = RESTORE_REGISTER
                }
                dataWrap = <ul class="{register:ulClass}">|</ul>
            }
            wrap =
            SPC = 1
            SPC {
                allStdWrap {
                    replacement {
                        10 {
                            search = ---
                            replace =
                        }
                    }
                    dataWrap = </ul>|<ul class="{register:ulClass}">
                }
            }
        }
    }
}

This example shows a part of a TypoScript which builds a 2 column menu based on a spacer page. A class is added to the ul tag depending on the value of the register variable ulClass. The first pages will have the class col-left and the pages following the spacer page will get the class col-right.

{register:variablename} returns the "current" value of the variable variablename. A register stack can be like any TypoScript setup.

10 = COA
10 {
  10 = LOAD_REGISTER
  10 {
      ulClass = col-left
      aClass = a-special
      colors {
          chief = red
          servant = white
      }
  }
}

The "current" value is just an internal variable that can be used by functions to pass a single value on to another function later in the TypoScript processing. It is like "load accumulator" in the good old C64 days. Basically you can use a "register" as you like. The TSref will tell if functions are setting this value before calling some other object so that you know if it holds any special information.

Analyzing defined constants

The backend submodule Site Management > TypoScript > Active TypoScript provides a tree view to all defined TypoScript Constants on the currently active page.

Finding errors

There are no tools that will tell whether the given TypoScript code is 100% correct. The Included TypoScript will warn about syntax errors though:

In the frontend, the typo3/cms-adminpanel is another possibility to debug TypoScript: use its section called TypoScript. It shows selected rendered (configuration) values, SQL queries, error messages and more.

Debugging

TypoScript itself offers a number of debug functions:

• stdWrap comes with the properties , and which help checking which values are currently available and which configuration is being handled.
• TMENU comes with the property debugItemConf. If set to 1, it outputs the configuration arrays for each menu item. Useful to debug optionSplit things and such.

Setting the page TSconfig globally

Global page TSconfig should be stored within an extension, usually a sitepackage extension. The content of the file Configuration/page.tsconfig within an extension is automatically loaded during build time.

It is possible to load other TSconfig files with the import syntax within this file:

@import 'EXT:my_sitepackage/Configuration/TsConfig/Page/Basic.tsconfig'
@import 'EXT:my_sitepackage/Configuration/TsConfig/Page/Mod/Wizards/NewContentElement.tsconfig'

Many page TSconfig settings can be set globally. This is useful for installations that contain only one site and use only one sitepackage extension.

Extensions supplying custom default page TSconfig that should always be included, can also set the page TSconfig globally.

The PSR-14 event BeforeLoadedPageTsConfigEvent is available to add global static page TSconfig before anything else is loaded.

Page TSconfig on site level

Page TSconfig can be defined on a site level by placing a file called page.tsconfig in the storage directory of the site (config/sites/<identifier>/).

Extensions and site packages can provide page TSconfig in site sets by placing a file called page.tsconfig into the folder of that set.

This way sites and sets can ship page TSconfig without the need for database entries or by polluting global scope. Dependencies can be expressed via site sets, allowing for automatic ordering and deduplication.

See also site sets as page TSconfig provider.

name: my-vendor/my-set
label: My Set

base: 'http://example.com/'
rootPageId: 1
dependencies:
  - my-vendor/my-set

# This tsconfig will be loaded for pages in site "my-site"
# [...]

# This tsconfig will be loaded for pages in all sites that depend on set 'my-vendor/my-set'
# [...]

Static page TSconfig

<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

ExtensionManagementUtility::registerPageTSConfigFile(
    'extension_name',
    'Configuration/TsConfig/Page/myPageTSconfigFile.tsconfig',
    'My special config',
);

<?php

$GLOBALS['TCA']['pages']['columns']['tsconfig_includes']['config']['items'][] =
    [
        'LLL:EXT:my_sitepackage/Resources/Private/Language/locallang_db.xlf:pages.pageTSconfig.my_ext_be_layouts',
        'EXT:my_sitepackage/Configuration/TsConfig/Page/myPageTSconfigFile.tsconfig',
    ];

Set page TSconfig directly in the page properties

Go to the page properties of the page where you want to include the page TSconfig and open the tab Resources.

You can enter page TSconfig directly into the field Page TSconfig:

Page TSconfig inserted directly into the page properties is applied to the page itself and all its subpages.

Verify the final configuration

The full page TSconfig for any given page can be viewed using the module Page TSconfig with in the Site Management section.

Overriding and modifying values

Page TSconfig is loaded in the following order, the latter override the former:

1. Default page TSconfig that was set globally
2. Static page TSconfig that was included for a page tree.
3. Direct page TSconfig entered directly in the page properties.
4. User TSconfig overrides

Static and direct page TSconfig are loaded for the page they are set on and all their subpages.

The TypoScript syntax to modify values can also be used for the page TSconfig.

Example

Default page TSconfig

RTE.default.proc.allowTagsOutside = hr

Static page TSconfig included on the parent page

RTE.default.proc.allowTagsOutside := addToList(blockquote)

Finally you get the value "hr,blockquote".

Importing the user TSconfig into a backend user or group

1. Open the record of the user or group. Go to Options > TSconfig.

   

2. Enter the following TSconfig to import a configuration file from your sitepackage:

   TsConfig added in the backend record of a backend user or group

   @import 'EXT:my_sitepackage/Configuration/TsConfig/User/my_editor.tsconfig'

   Copied!

This will make all settings in the file available to the user. The file itself can be kept under version control together with your sitepackage.

TSconfig defined at user level overrides TSconfig defined at group level.

If a user is a member of several groups, the TSconfig from each group is loaded. The order in which the groups are added to the user in field General > Group is used.

The TSconfig from latter groups overrides the TSconfig from earlier groups if both define the same property.

Setting default user TSconfig

User TSconfig is designed to be individual for users or groups of users. However, good defaults can be defined and overridden by group or user-specific TSconfig.

Default user TSconfig should be stored within an extension, usually a sitepackage extension. The content of the file Configuration/user.tsconfig within an extension is automatically loaded during build time.

It is possible to load other user TSconfig files with the import syntax within this file:

@import 'EXT:my_sitepackage/Configuration/TsConfig/User/default.tsconfig'

The PSR-14 event BeforeLoadedUserTsConfigEvent is available to add global static user TSconfig before anything else is loaded.

Verify the final configuration

The full user TSconfig of the currently logged-in backend user can be viewed using the System > Configuration backend module and choosing the action $GLOBALS['BE_USER']->getTSConfig() (User TSconfig). However this module can only be accessed by admins.

The Configuration module is available with installed lowlevel system extension.

Override and modify values

Properties, which are set in the TSconfig field of a group, are valid for all users of that group.

Values set in one group can be overridden and modified in the same or another group. If a user is a member of multiple groups, the TSconfig settings are evaluated in the order in which the groups are included in the user account: When editing the backend user, the selected groups are evaluated from top to bottom.

Example:

• Add in user TSconfig

  EXT:site_package/Configuration/user.tsconfig

  page.RTE.default.showButtons = bold

  Copied!
• You get the value "bold".

• Add later in user TSconfig

  EXT:site_package/Configuration/user.tsconfig

  page.RTE.default.showButtons := addToList(italic)

  Copied!
• You get the value "bold,italic".

Finally, you can override or modify the settings from groups that your user is a member of in the user TSconfig field of that specific user.

Example:

Let's say the user is a member of a usergroup with this configuration:

TCAdefaults.tt_content {
    hidden = 1
    header = Hello!
}

Then we set the following values in the TSconfig field of the specific user.

page.TCAdefaults.tt_content.header = 234
options.clearCache.all = 1

This would override the default value of the header ("234") and add the clear cache option. The default value of the hidden field is not changed and simply inherited directly from the group.

Overriding page TSconfig in user TSconfig

All properties from page TSconfig can be overridden in user TSconfig by prepending the property name with page..

When a page TSconfig property is set in user TSconfig that way, regardless of whether it is in the TSconfig field of a group or a user, it overrides the value of the according page TSconfig property.

To illustrate this feature let's say new pages and copied pages are not hidden by default:

TCAdefaults.pages.hidden = 0
TCEMAIN.table.pages.disableHideAtCopy = 1

If we activate the following configuration in the user TSconfig of a certain backend user group, new and copied pages will be hidden for that group. The user TSconfig to be used is the same, but prefixed with page.

// Override the settings from the page TSconfig for the editors usergroup
page {
    TCAdefaults.pages.hidden = 1
    TCEMAIN.table.pages.disableHideAtCopy = 0
}

# Enable the "bold" button in Page TSconfig (!)
RTE.default.showButtons = bold

# Try to additionally add the "italic" button in User TSconfig (!)
page.RTE.default.showButtons := addToList(italic)

Condition variables available in TSconfig

[applicationContext == "Development"]
    // Your settings go here
[END]

[applicationContext matches "/^Production/"]
    // Your settings go here
[END]

# Check single page uid
[traverse(page, "uid") == 2]
    // Your settings go here
[END]
# Check list of page uids
[traverse(page, "uid") in [17,24]]
    // Your settings go here
[END]
# Check list of page uids NOT in
[traverse(page, "uid") not in [17,24]]
    // Your settings go here
[END]
# Check range of pages (example: page uid from 10 to 20)
[traverse(page, "uid") in 10..20]
    // Your settings go here
[END]

# Check the page backend layout
[traverse(page, "backend_layout") == 5]
    // Your settings go here
[END]
[traverse(page, "backend_layout") == "example_layout"]
    // Your settings go here
[END]

# Check the page title
[traverse(page, "title") == "foo"]
    // Your settings go here
[END]

# Check if page is on level 1 (root):
[tree.level == 1]
    // Your settings go here
[END]

# Use backend_layout records uids
[tree.pagelayout == 2]
    // Your settings go here
[END]

# Use TSconfig provider of backend layouts
[tree.pagelayout == "pagets__Home"]
    // Your settings go here
[END]

[tree.rootLine[0]["uid"] == 1]
    // Your settings go here
[END]

# Check if page with uid 2 is inside the root line
[2 in tree.rootLineIds]
    // Your settings go here
[END]

# Check if page with uid 2 is the parent of a page inside the root line
[2 in tree.rootLineParentIds]
    // Your settings go here
[END]

# Evaluates to true if current backend user is administrator
[backend.user.isAdmin]
    // Your settings go here
[END]

[backend.user.isLoggedIn]
    // Your settings go here
[END]

# Evaluates to true if user uid of current logged in backend user is equal to 5
[backend.user.userId == 5]
    // Your settings go here
[END]

[2 in backend.user.userGroupIds]
    // Your settings go here
[END]

[like(","~backend.user.userGroupList~",", "*,1,*")]
    // Your settings go here
[END]

[workspace.workspaceId == 0]
    // Your settings go here
[END]

[workspace.isLive]
    // Your settings go here
[END]

[workspace.isOffline]
    // Your settings go here
[END]

[typo3.version == "13.4.0"]
    // Your settings go here
[END]

[typo3.branch == "13.4"]
    // Your settings go here
[END]

[typo3.devIpMask == "203.0.113.6"]
    // Your settings go here
[END]

Condition functions available in TSconfig

# True if day of current month is 7
[date("j") == 7]
    // Your settings go here
[END]

# True if day of current week is 7
[date("w") == 7]
    // Your settings go here
[END]

# True if day of current year is 7
[date("z") == 7]
    // Your settings go here
[END]

# True if current hour is 7
[date("G") == 7]
    // Your settings go here
[END]

# Search a string with * within another string
[like("fooBarBaz", "*Bar*")]
    // Your settings go here
[END]

# Search string with single characters in between, using ?
[like("fooBarBaz", "f?oBa?Baz")]
    // Your settings go here
[END]

# Search string using regular expression
[like("fooBarBaz", "/f[o]{2,2}[aBrz]+/")]
    // Your settings go here
[END]

# Traverse query parameters of current request along tx_news_pi1[news]
[traverse(request.getQueryParams(), 'tx_news_pi1/news') > 0]
    // Your settings go here
[END]

# True if current version is 13.4.x
[compatVersion("13.4")]
    // Your settings go here
[END]
[compatVersion("13.4.0")]
    // Your settings go here
[END]
[compatVersion("13.4.1")]
    // Your settings go here
[END]

[getenv("VIRTUAL_HOST") == "www.example.org"]
    // Your settings go here
[END]

# True if feature toggle for strict TypoScript syntax is enabled:
[feature("TypoScript.strictSyntax") === false]
    // Your settings go here
[END]

# Site identifier
[site("identifier") == "my_website"]
    // Your settings go here
[END]

# Match site base host
[site("base").getHost() == "www.example.org"]
    // Your settings go here
[END]

# Match base path
[site("base").getPath() == "/"]
    // Your settings go here
[END]

# Match root page uid
[site("rootPageId") == 1]
    // Your settings go here
[END]

# Match a configuration property
[traverse(site("configuration"), "myCustomProperty") == true]
    // Your settings go here
[END]

Retrieving TSconfig settings

The PHP API to retrieve page and user TSconfig in a backend module can be used as follows:

<?php

declare(strict_types=1);

namespace UsingSettingTSconfig\_PhpApi;

use TYPO3\CMS\Backend\Utility\BackendUtility;
use TYPO3\CMS\Core\Authentication\BackendUserAuthentication;

final class MyBackendController
{
    public function someMethod(int $currentPageId): void
    {
        // Retrieve user TSconfig of currently logged in user
        $userTsConfig = $this->getBackendUser()->getTSConfig();

        // Retrieve page TSconfig of the given page id
        $pageTsConfig = BackendUtility::getPagesTSconfig($currentPageId);
    }

    private function getBackendUser(): BackendUserAuthentication
    {
        return $GLOBALS['BE_USER'];
    }
}

Both methods return the entire TSconfig as a PHP array. The former retrieves the user TSconfig while the latter retrieves the page TSconfig.

All imports, overrides, modifications, etc. are already resolved. This includes page TSconfig overrides by user TSconfig.

Similar to other TypoScript-related API methods, properties that contain sub-properties return their sub-properties using the property name with a trailing dot, while a single property is accessible by the property name itself. The example below gives more insight on this.

If accessing TSconfig arrays, the PHP null coalescing operator ?? is useful: TSconfig options may or not be set, accessing non-existent array keys in PHP would thus raise PHP notice level warnings.

Combining the array access with a fallback using ?? helps when accessing these optional array structures.

options.someToggle = 1
options.somePartWithSubToggles = foo
options.somePartWithSubToggles.aValue = bar

<?php

return [
    'options.' => [
        'someToggle' => '1',
        'somePartWithSubToggles' => 'foo',
        'somePartWithSubToggles.' => [
            'aValue' => 'bar',
        ],
    ],
];

<?php

declare(strict_types=1);

namespace UsingSettingTSconfig\_PhpApi;

final class _MyBackendLoggedInController
{
    public function isUserToggleEnabled(): bool
    {
        // Typical call to retrieve a sanitized value:
        return $isToggleEnabled = (bool)($this->getUserTsConfig()['options.']['someToggle'] ?? false);
    }

    public function getSomePartWithSubToggles(): array
    {
        // Retrieve a subset, note the dot at the end:
        return $this->getUserTsConfig()['options.']['somePartWithSubToggles.'] ?? [];
    }

    private function getUserTsConfig(): array
    {
        return $GLOBALS['BE_USER']->getTSConfig();
    }
}

Changing or adding page TSconfig

The PSR-14 event ModifyLoadedPageTsConfigEvent is available to modify or add page TSconfig entries.

Value assignment with "="

This most common operator assigns a single line value to an identifier path. Everything after the = character until the end of the line is considered to be the value. The value is trimmed, leading and trailing whitespaces are removed.

Values are parsed for constant references. With a value assignment like foo = someText {$someConstant} furtherText, the parser will look up the constant reference {$someConstant} and tries to substitute it with a defined constant value. If such a constant does not exist, it falls back to the string literal including the {$ and } characters.

A couple of examples:

# Identifier "myIdentifier" is set to the value "foo"
myIdentifier = foo

# Identifier path "myIdentifier.mySubIdentifier" is set to the value "foo"
myIdentifier.mySubIdentifier = foo

# "myIdentifier.mySubIdentifier" it set to the value "foo",
# but is immediately overwritten to value "bar"
myIdentifier.mySubIdentifier = foo
myIdentifier.mySubIdentifier = bar

# Same as above, value of "myIdentifier.mySubIdentifier" is "bar"
myIdentifier.mySubIdentifier = foo
myIdentifier {
   mySubIdentifier = bar
}

# Value assignments are not comment-aware, "#", "//" and "/*" after a
# "=" operator do not start a comment. The value of identifier
# "myIdentifier.mySubIdentifier" is "foo // not a comment"
myIdentifier.mySubIdentifier = foo // not a comment

# Value assignment using a constant:
# Ends up as "foo myConstantValue bar" if constant "myConstant" is set to "myConstantValue"
# Ends up as "foo {$myConstantValue} bar" if constant "myConstant" is not set
myIdentifier. mySubIdentifier = foo {$myConstantValue} bar

lib.nav.wrap =<ul id="nav">|</ul>

lib.nav.wrap = <ul id="nav">|</ul>

Multiline assignment with "(" and ")"

Opening and closing parenthesis are used to assign multi-line values. This allows defining values that span several lines and thus include line breaks.

The end parenthesis ) is important: If it is not found, the parser considers all following lines until the end of the TypoScript text snipped to be part of the value. This includes comments, [GLOBAL] conditions and @import file includes: They are not a syntax construct and are considered part of the value assignment.

However, the value is parsed for constants (text looking like {$myIdentifier.mySubIdentifier}: The parser will try to substitute them to their assigned constant value. The "TypoScript" and "Page TSconfig" backend modules may show a warning if a reference to a constant can't be resolved. If a constant reference can't be resolved, the value falls back to its string literal. Since multi-line values are sometimes used to output JavaScript, and JavaScript also uses a syntax construct like {$...}, this may lead to false positive warnings in those backend modules.

A couple of examples:

myIdentifier= TEXT
myIdentifier.value (
   This is a
   multiline assignment
)

myIdentifier= TEXT
myIdentifier.value (
   <p class="warning">
      This is HTML code.
   </p>
)

myIdentifier= TEXT
myIdentifier.value (
   This looks up the value for constant {$myConstant}
   and falls back to the string "{$myConstant}" if it can
   not be resolved.
)

Unset with ">"

This can be used to unset a previously defined identifier path value, and all of its sub identifiers:

myIdentifier.mySubIdentifier = TEXT
myIdentifier.mySubIdentifier = myValue
myIdentifier.mySubIdentifier.stdWrap = <p>|</p>

# "myIdentifier.mySubIdentifier" is completely removed, including value
# assignment and sub identifier "stdWrap"
myIdentifier.mySubIdentifier >

# Same as above: Everything after ">" operator is considered a comment
myIdentifier.mySubIdentifier > // Some comment

Copy with "<"

The < character is used to copy one identifier path to another. The whole current identifier state is copied: both value and sub identifiers. It overrides any old sub identifiers and values at that position.

The copy operator is useful to follow the DRY - Don't repeat yourself principle. It allows maintaining a configuration set at a central place, and copies are used at further places when needed again.

The result of the below TypoScript is two independent sets which are duplicates. They are not references to each other but actual copies:

myIdentifier = TEXT
myIdentifier.value = Hello world
myOtherIdentifier = TEXT
myOtherIdentifier.value = Hello world

# The above is identical to this:
myIdentifier = TEXT
myIdentifier.value = Hello world
myOtherIdentifier < myIdentifier

The copy operator is allowed within code blocks as well:

myIdentifier {
   10 = TEXT
   10.value = Hello world
   20 < myIdentifier.10
}

In the above example, the copied identifier path is referred to with its full path myIdentifier.10. When copying on the same level, it is allowed to use a relative path, indicated by a prepended dot. The following produces the same result as above:

myIdentifier {
   10 = TEXT
   10.value = Hello world
   20 < .10
}

Using the copy operator creates a copy of the source path at exactly this point in the parsing process. Changing the source afterwards does not change the target, and changing the target afterwards does not change the source:

# The above is identical to this:
myIdentifier = TEXT
myIdentifier.value = Hello world
myOtherIdentifier < myIdentifier

# Changing myIdentifier *after* it has been copied over to myOtherIdentifier,
# does *not* change myOtherIdentifier. The below line only changes the
# value of myIdentifier, not myOtherIdentifier:
myIdentifier.value = Hello world 2

# Changing myOtherIdentifier *after* it has been copied from to myIdentifier,
# does *not* change myIdentifier. The below line only changes the
# value of myOtherIdentifier, not myIdentifier:
myOtherIdentifier.value = Hello world 3

References with "=<"

In the context of frontend TypoScript, it is possible to create references from one identifier path to another within the tt_content path. References mean that multiple positions can copy the same source identifier path without making an actual copy. This allows changes to the source identifier afterwards, which changes the targets as well. References can be convenient for this special case, but should be used with caution.

lib.myIdentifier = TEXT
lib.myIdentifier {
   value = Hello world
   stdWrap.wrap = <p>|</p>
}
tt_content.text =< lib.myIdentifier
tt_content.textpic =< lib.myIdentifier

# This changes lib.myIdentifier.stdWrap.wrap *and* tt_content.text.stdWrap.wrap
lib.myIdentifier.stdWrap.wrap = <h1>|</h1>
# This changes only tt_content.textpic.stdWrap.wrap
tt_content.textpic.stdWrap.wrap = <h2>|</h2>

Value modifications with ":="

This operator assigns a value to an identifier path by calling a predefined function which modifies the existing value in different ways. This is very useful when a value should be modified without completely redefining it again.

A modifier is referenced by its modifier name, plus arguments in parenthesis. These predefined functions are available:

prependString()

Add a string to the beginning of the existing value.

foo = cd
foo := prependString(ab)
# foo is "abcd"

Copied!

appendString()

Add a string to the end of the existing value.

foo = ab
foo := appendString(cd)
# foo is "abcd"

Copied!

removeString()

Remove a string from the existing value.

foo = foobarfoo
foo := removeString(foo)
# foo is "bar"

Copied!

replaceString()

Replace old with new value. Separate these using |.

foo = abcd
foo := replaceString(bc|123)
# foo is "a123d"

Copied!

addToList()

Add values to the end of a list of existing values. There is no check for duplicate values, and the list is not sorted in any way.

foo = 123,456
foo := addToList(789)
# foo is "123,456,789"

foo =
foo := addToList(123)
# foo is "123" (no leading comma added on empty existing value)

Copied!

removeFromList()

Remove a comma-separated list of values from an existing comma-separated list of values. Empty values are removed as well.

foo = foo,123,bar,456,foo,,789
foo:= removeFromList(foo,bar)
# foo is "123,456,789"

Copied!

uniqueList()

Remove duplicate entries from a comma-separated list of values.

foo = 123,456,abc,456,456
foo := uniqueList()
# foo is "123,456,abc"

Copied!

reverseList()

Reverses the order of entries in a comma-separated list of values.

foo = 123,456,abc,456
foo := reverseList()
# foo is "456,abc,456,123"

Copied!

sortList()

Sorts the entries in a comma-separated list of values. There are optional sorting parameters, multiple can be separated using ,:

ascending (default)

Sort the items in ascending order: First numbers from small to big, then letters in alphabetical order.

descending

Sort the items in descending order: First letters in descending order, then numbers from big to small.

numeric

Apply numeric sorting: Numbers from small to big, letters sorted after "0".

foo = 10,100,0,20,abc
foo := sortList()
# foo is "0,10,20,100,abc"

foo = 10,0,100,-20
foo := sortList(numeric)
# foo is "-20,0,10,100"

foo = 10,100,0,20,-20
foo := sortList(numeric,descending)
# foo is "100,20,10,0,-20"

Copied!

getEnv()

Access a $_ENV value. Resolves to empty value if not set.

# $_ENV['foo'] = 'fooValue'
foo := getEnv(foo);
# foo is "fooValue"

Copied!

myCustomFunction()

Changed in version 12.0

The PSR-14 event \TYPO3\CMS\Core\TypoScript\AST\Event\EvaluateModifierFunctionEvent is available to define custom TypoScript functions. The event replaces the hook $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_tsparser.php']['preParseFunc'] .

The section EvaluateModifierFunctionEvent provides an example and the API.

Null coalescing operator ?? for TypoScript constants

TypoScript constants expressions support a null coalescing operator (??) as a way for providing a migration path from a legacy constant name to a newer name, while providing full backwards compatibility for the legacy constant name, if still defined.

Example that evaluates to $config.oldThing if set, otherwise the newer setting $myext.thing would be used:

plugin.tx_myext.settings.example = {$config.oldThing ?? $myext.thing}

Basic example

[date("j") == 9]
   page.10.value = It is the 9th day of the month!
[ELSE]
   page.10.value = It is NOT the 9th day of the month!
[END]

Syntax and rules

The general syntax is like this:

# Some TypoScript, always parsed
[condition criteria]
   # Some TypoScript, only parsed if the condition criteria is met
[ELSE]
   # Some TypoScript, only parsed if the condition criteria is *not* met
   # [ELSE] is optional
[GLOBAL]
# ... some TypoScript, always parsed

These general rules apply:

• Conditions are encapsulated in [ and ]
• [ELSE] negates a previous condition criteria and can contain a new body until [END] or [GLOBAL]. [ELSE] is considered if the condition criteria did not evaluate to true.
• [END] and [GLOBAL] stop a given condition scope. This is similar to a closing curly brace } in programming languages like PHP.
• Multiple condition criteria can be combined using or or ||, as well as and or &&

• Single criteria can be negated using !

  Changed in version 12.0

  [END] and [GLOBAL] behave exactly the same. Both are kept for historical reasons (for now).

• Conditions can use constants. They are available in frontend TypoScript "setup" and in TSconfig from "site settings". A simple example if this constant myPageUid = 42 is set:

  [traverse(page, "uid") == {$myPageUid}]
      page.10.value = Page uid is 42
  [end]

  Copied!

• Conditions can not be nested within code blocks.

  Changed in version 12.0

  Conditions can be nested into each other, if they are located in different snippets (files or records), see example below. They can not be nested within the same code snippet.

• A second condition that is not [ELSE], [END] or [GLOBAL] stops a previous condition and starts a new one. This is the main reason conditions can not be nested within one text snippet.

• Changed in version 12.0

  @import can be nested inside conditions. This allows conditional includes and is a new feature of the TYPO3 v12 parser.

• Changed in version 12.0

  Conditions automatically stop at the end of a text snippet (file or record), even without [END] or [GLOBAL]. Another snippet on the same level is in "global" scope automatically. The backend TypoScript and TSconfig modules may mumble about a not properly closed condition, though.

• New in version 12.1

  Using the null-safe operator is possible when accessing properties on objects which might not be available in some context, for example TSFE in the backend:

  # Previously
  [getTSFE() && getTSFE().id == 123]
  
  # Now
  [getTSFE()?.id == 123]

  Copied!

Examples

• If a user is logged in, or if the client is local, text will be output in upper case:

  Extension examples, file Configuration/TypoScript/Syntax/Conditions3/setup.typoscript

  page = PAGE
  page.10 = TEXT
  page.10.value = HELLO WORLD!
  
  [frontend.user.isLoggedIn || ip('127.0.0.1')]
     page.20 = TEXT
     page.20 {
        value = A frontend user is logged in, or the browser IP is 127.0.0.1
        stdWrap.case = upper
     }
  [GLOBAL]

  Copied!

• In case if is empty and only a else body is needed for a single condition criteria, these two are identical:

  Extension examples, file Configuration/TypoScript/Syntax/Conditions4/setup.typoscript

  page = PAGE
  page.10 = TEXT
  page.10.value = You are logged in
  
  # This is hard to read
  [frontend.user.isLoggedIn]
  [ELSE]
     page.10.value = You are *not* logged in
  [END]
  
  # This is faster to read
  [!frontend.user.isLoggedIn]
     page.10.value = You are *not* logged in
  [END]

  Copied!

• Conditions can not be nested within curly braces. The example below is invalid syntax and the backend modules mumble with "missing braces":

  Extension examples, file Configuration/TypoScript/Syntax/Conditions5/setup.typoscript

  # Invalid: Conditions must not be used within code blocks
  someIdentifier {
     someProperty = foo
     [frontend.user.isloggedIn]
        someProperty = bar
     [GLOBAL]
  }

  Copied!

@import

This keyword allows including files inspired by a syntax similar to SASS. It is restricted, but still allows wildcards on file level. Single files must end with .typoscript if included in frontend Typoscript. In backend TSconfig, single files should end with .tsconfig, but may end with .typoscript as well (for now).

The include logic is a bit more restrictive with TYPO3 v12, previous versions have been slightly more relaxed in this regard. See this changelog for more details.

The following rules apply:

• Multiple files are imported in alphabetical order. If a special loading order is desired it is common to prefix the filenames with numbers that increase for files that shall be loaded later.
• Recursion is allowed: Imported files can have @import statements.

• Changed in version 12.0

  It is allowed to put @import within a condition. This example imports the additional file only if a frontend user is logged in:

  [frontend.user.isLoggedIn]
      @import './userIsLoggedIn.typoscript'
  [END]

  Copied!
• Directory imports are not recursive, meaning that a directory import does not automatically travel down its subdirectories.
• Quoting the filename is necessary with the new syntax. Either double quotes (") or single quotes (') can be used.
• Wildcards * are only allowed on file level, not on directory level. Only a single wildcard character is allowed.
• Includes relative to the current file location are allowed using ./ as prefix.
• Includes must start with EXT: if not relative. Loading files outside of extensions is not possible.
• Directory traversal using ../ is not allowed.

Some examples:

# Import a single file
@import 'EXT:my_extension/Configuration/TypoScript/randomfile.typoscript'

# Import multiple files in a single directory, sorted by file name
@import 'EXT:my_extension/Configuration/TypoScript/*.typoscript'

# It's possible to omit the file ending. For frontend TypoScript, ".typoscript" is
# appended automatically, backend TSconfig allows both ".typoscript" and ".tsconfig"
@import 'EXT:my_extension/Configuration/TypoScript/'

# Import files starting with "foo", ending with ".typoscript" (frontend)
@import 'EXT:my_extension/Configuration/TypoScript/foo*'

# Import files ending with ".setup.typoscript"
@import 'EXT:my_extension/Configuration/TypoScript/*.setup.typoscript'

# Import "bar.typoscript" relative to current file
@import './bar.typoscript'

# Import all ".setup.typoscript" files in sub directory relative to current file
@import './subDirectory/*.setup.typoscript'

Alternatives to using file imports

The following features can make file inclusion unnecessary:

• Automatic global inclusion of user TSconfig of extensions
• Automatic global inclusion of page TSconfig of extensions
• Automatic page TSconfig on site level
• TypoScript provider for sites and sets automatically loads TypoScript per site when the site set is included in the site configuration.

boolean

date-conf

function name

integer

path

resource

string

PHP information

The content objects (data type: cObject) are primarily controlled by the PHP- script typo3/sysext/frontend/Classes/ContentObject/ContentObjectRenderer.php. The PHP-class is named ContentObjectRenderer and often this is also the variable-name of the objects ($cObj).

The $cObj in PHP has an array, $this->data, which holds records of various kind. See data type "getText".

This record is normally "loaded" with the record from a table depending on the situation. Say if you are creating a menu it's often loaded with the page-record of the actual menu item or if it's about content-rendering it will be the content-record.

Reusing content objects

When dealing with "cObjects", you're allowed to use a special syntax in order to reuse cObjects without actually creating a copy. This has the advantage of minimizing the size of the cached template. But on the other hand it does not give you the flexibility of overriding values.

This example will show you how it works:

#
# Temporary objects are defined:
#
lib.stdheader = COA
lib.stdheader {
  stdWrap.wrapAlign.field = header_position
  stdWrap.typolink.parameter.field = header_link
  stdWrap.fieldRequired = header

  1 = TEXT
  1.stdWrap.current = 1

  stdWrap.space = {$content.headerSpace}
}


#
# CType: header
#
tt_content.header = COA
tt_content.header {
  10 < lib.stdheader
  10.stdWrap.space >

  20 = TEXT
  20.stdWrap.field = subheader
}


#
# CType: bullet
#
tt_content.bullets = COA
tt_content.bullets {
  10 = < lib.stdheader
  20 < styles.content.bulletlist_gr
}

First lib.stdheader is defined. This is (and must be) a cObject! (In this case it is COA.)

Now lib.stdheader is copied to tt_content.header.10 with the "<" operator. This means that an actual copy of lib.stdheader is created at parsetime.

But this is not the case with tt_content.bullets.10. Here lib.stdheader is referenced and lib.stdheader will be used as the cObject at runtime.

The reason why lib.stdheader was copied in the first case is the fact that it's needed to unset ".stdWrap.space" inside the cObject (10.stdWrap.space >). This could not be done in the second case where only a pointer is created.

Example:

EXT:site_package/Configuration/TypoScript/setup.typoscript

page.10 = TEXT
page.10.value = kasper
page.10.stdWrap.case = upper

page.20 = < page.10
page.20.stdWrap.case = lower
page.20.value >
page.20.stdWrap.field = pages

Copied!

The result is this configuration:

Notice that .value was not cleared, because it's simply two arrays which are joined:

So hence the line page.20.value > in the above example is useless.

Properties

Example:

If in this example the field header turns out not to be set ("false"), an empty string is returned. Otherwise TYPO3 chooses between two different renderings of some content depending on whether the Properties field layout is "1" or not (Properties).

The result is in either case wrapped with |<br>.

stuff = CASE
stuff.if.isTrue.field = header
# This value determines, which of the following cObjects will be rendered.
stuff.key.field = layout

# cObject for the case that field layout is "1".
stuff.1 = TEXT
stuff.1 {
    # ....
}
# cObject for all other cases.
stuff.default = TEXT
stuff.default {
    # ....
}

stuff.stdWrap.wrap = |<br>

Properties

Examples:

lib.contentexample = COA
lib.contentexample {
  10 = TEXT
  10.value = <h1>Header</h1>

  20 = CONTENT
  20 {
    table = tt_content
    select.orderBy = sorting
    select.where = {#colPos}=0
  }

  30 = TEXT
  30.value = <footer>Footer text</footer>
}

The previous example will print a simple <h1> header, followed by the page content records and a <footer> element.

lib.currentDate = COA_INT
lib.currentDate {
  10 = TEXT
  10.stdWrap.data = date:U
  10.stdWrap.strftime = %H:%M:%S
}

This example will not be cached and so will display the current time on each page hit.

Properties