Conditions

TypoScript can contain if and if / else control structures. They are called conditions, their "body" is only considered if a condition criteria evaluates to true. Examples of condition criteria are:

  • Is a user logged in?
  • Is it Monday?
  • Is the page called in a certain language?

Conditions are a TypoScript syntax construct. They are thus available in both frontend TypoScript and backend TSconfig. However, condition criteria are based on prepared variables and functions, and those are different in frontend TypoScript and backend TSconfig. For example, the frontend variable does not exist in TSconfig, it is (obviously) impossible to have a backend TSconfig condition that checks for a logged in frontend user.

For a reference of allowed condition criteria, please refer to the according chapter in the frontend TypoScript Reference and the backend TSconfig Reference. These references come with examples for single condition criteria as well.

The TSconfig and TypoScript backend modules show lists of existing conditions and allow simulating criteria verdicts to analyze their impact on the resulting TypoScript tree.

Condition criteria are based on the Symfony expression language. The Core allows extending the Symfony expression language with own variables and functions, see symfony expression language API for more details.

Basic example

Extension examples, file Configuration/TypoScript/Syntax/Conditions1/setup.typoscript
[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]
Copied!

Syntax and rules

The general syntax is like this:

Extension examples, file Configuration/TypoScript/Conditions2/setup.typoscript
# 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
Copied!

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 and <INCLUDE_TYPOSCRIPT: ... 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!