TypoScript Syntax
1.2.3. Conditions
There is a possibility of using so called conditions in TypoScript. Conditions are simple control structures, that validates true or false based on some criteria (externally validated) and thereby determines whether the following TypoScript code until the next condition found should be parsed or not.
Examples of a condition could be:
-
Is the browser "Netscape"?
-
Is a usergroup set for the current session?
-
Is it monday?
-
Is the GET parameter "&language=uk" set?
-
Is it my mothers birthday?
-
Do I feel lucky today?
Of these examples admittedly the first few is the most realistic, in fact they are readily available in the context of TypoScript Templates. But a condition can theoretically evaluate any circumstance and return either true/false which subsequently means the parsing of the TypoScript code that follows.
Where conditions can be used
The detection of conditions is a part of the TypoScript syntax but the validation of the condition content always relies on the context where TypoScript is used. Therefore in plain syntax highlighting (no context) conditions are just highlighted and nothing more. In the context of TypoScript Templates there is a whole section of TSref which defines the syntax of the condition contents for TypoScript Templates. For "Page TSconfig" and "User TSconfig" conditions are not implemented at all.
The syntax of conditions
A condition always has it's own line and the line is detected by " [ " (square bracket) being the first character on that line:
(Some TypoScript)
[ condition 1 ][ condition 2]
(Some TypoScript only parsed if cond. 1 or cond. 2 are met)
[GLOBAL]
(Some TypoScript)
So in this example the line "[GLOBAL]" is a condition (built-in, always returns true) and the line "[ condition 1 ][ condition 2]" is a condition. If "[ condition 1 ][ condition 2]" is true then the TypoScript in the middle would be parsed until [GLOBAL] (or [END]) resets the conditions and parses the TypoScript for any case again.
Notice: The condition line "[ condition 1 ][ condition 2]" conveys the idea of two conditions being set, but from the TypoScript parsers point of view the whole line is the condition - it is in the context of TypoScript Templates that the condition line content is broken down into smaller units ("[ condition 1 ]" and "[ condition 2]") which are individually evaluated and OR'ed together before they return the resulting true / false value. (That is all done with the class t3lib_matchCondition).
Here is an example of some TypoScript (from the context of TypoScript Templates) where another text is outputted if you use the Netscape webbrowser (instead of for example Internet Explorer) or use Windows NT as operating system:
pageObj.10 = HTML
pageObj.10.value = Hello World
pageObj.10.value.case = upper
[browser = netscape][system = WinNT]
pageObj.20 = HTML
pageObj.20 {
value = Hello Netscape or Windows NT users!!
value.case = upper
}
[GLOBAL]
pageObj.30 = HTML
pageObj.30.value = <HR>
You can now use the Object Browser to actually see the difference in the parsed object tree depending on whether the condition evaluates to true or false (which can be simulated with that module as you can see):
The special [ELSE], [END] and [GLOBAL] conditions
There's a special condition called [ELSE] which will return true if the previous condition returned false. To end an [ELSE] condition you can use either [END] or [GLOBAL]. For all three conditions you can also use them in lower case.
Here's an example of using the [ELSE]-condition (also in the context of TypoScript Templates):
page.typeNum=0
page = PAGE
page.10 = TEXT
[browser=netscape]
page.10.value = Netscape
[else]
page.10.value = Not a netscape browser!
[end]
page.10.wrap = <B>|</B>
Here we have one output text if the browser is Netscape and another if not. Anyways the text is wrapped by <B>|</B> as we see, because this wrap is added after the [END]-condition.
The fact that you can "enable" the condition in the TypoScript Object Browser is a facility provided to simulate the outcome of any conditions you insert in a TypoScript Template. Whether or not the conditions correctly validate is only verified by actually getting a (in this example) Netscape browser and hit the site.
Another example could be if you wanted to do something special in case a bunch of conditions is NOT true. There's no negate-character, but you could do this:
[browser=netscape][usergroup=3]
# Enter nothing here!
[else]
page.10.value = This text displays only if the conditions above are not true!
[end]
Where to insert conditions in TypoScript?
Conditions can be used outside of confinements (curly braces) only!
So, this is valid:
someObject {
1property = 234
}
[browser=netscape]
someObject {
2property = 567
}
But this is not valid:
someObject {
1property = 234
[browser=netscape]
2property = 567
}
When parsed with syntax highlighting you will see this error:
This means that the line was perceived as a regular definition of "[object path] [operator] [value]" and not as a condition.
The [GLOBAL] condition
However for the special condition, [GLOBAL] (which resets any previous condition scope), it is a bit different since that will be detected at any line except within multiline value definitions.
someObject {
1property = 234
[GLOBAL]
2property = 567
}
But you will still get some errors if you syntax highlight it:
The reason for this is that the [GLOBAL] condition aborts the confinement started in the first line resulting in the first error ("... short of 1 end brace(s)"). The second error appears because the end brace is now in excess since the "brace level" was reset by [GLOBAL].
So, in summary; the special [global] (or [GLOBAL]) condition will at anytime break TypoScript parsing within braces and return to the global scope (unless entered in a multiline value). This is true for any TypoScript implementation whether other condition types are possible or not. Therefore you can use [GLOBAL] (put on a single line for itself) to make sure that proceeding TypoScript is correctly parsed from the top level. This is normally done when TypoScript code from various records is combined.
Summary
-
Conditions are detected by "[" as the first line character (whitespace ignored).
-
Conditions are evaluated in relation to the context where TypoScript is used; They are widely used in TypoScript Templates but not at all used with "Page TSconfig" or "User TSconfig".
-
Special conditions [ELSE], [END] and [GLOBAL] exists.
-
Conditions can be used outside of confinements (curly braces) only. However the [GLOBAL] condition will always break a confinement if entered inside of one.