Remember, TypoScript is like a (large) multidimensional PHP array; values arranged in a hierarchy - a tree. The "branches" are indicated with periods (".") - a syntax borrowed from for example JavaScript and which conveys the idea of defining objects/properties. For more details on these metaphors you should read the introductory chapters of this document. Here we will only deal with the syntactically rules.
Example:
myObject = [value 1]
myObject.myProperty = [value 2]
myObject.myProperty.firstProperty = [value 3]
myObject.myProperty.secondProperty = [value 4]
Refering to "myObject" we might call it an "object with the value [value 1] and the property, 'myProperty' with the value [value 2]. Furthermore 'myPropery' has its own two properties, 'firstProperty' and 'secondProperty' with a value each ([value 3] and [value 4])."
We might even call 'myProperty' for a TypoScript object in this example! This is already explained in the introduction chapter.
Remember, TypoScript contains information and is not "executed" like a real scripting language is; therefore it doesn't report any errors if you specify non-existing objects or non-existing properties. Such an evaluation only makes sense when TypoScript is used in a context (like "TypoScript Templates" or "Page TSconfig"). However we can always evaluate TypoScript for a correct syntax (which means whether information is defined in a correct way, following the “grammatical” rules).
Anyways, the TypoScript above looks like this in a node-tree (the TypoScript Object Browser creates such):
TypoScript is parsed in a very simple way; line by line. This means that each line normally contains three parts based on this formula:
[Object Path] [Operator] [Value]
Example:
myObject.myProperty = [value 2]
Object path is like the variable name in a programming language (Above: myObject.myProperty ). The object path is the first block of non-whitespace characters on a line until a "=<>{( "-character (space included) is found. Use only A-Z, a-z, 0-9, "-", "_" and periods (.) for Object Paths.
Operator is one of the characters “=<>{(“ (Above: “=”). The significance of each is described below.There is one special operator “:=” that changes the value depending on a predefined function.
Value is whatever characters that proceeds the operator until the end of the line, but trimmed for whitespace (Above: [value 2]). Notice that values are not encapsulated in quotes! The value starts after the operator and ends with the linebreak.
Example
Here myObject is defined as a HTML content object and the property "value" is set (from the context of TypoScript Templates):
myObject = HTML
myObject.value = <BLINK> HTML - code </BLINK>
Comments: When a line starts with "/" or "#"
...then it's considered a comment which means the line is totally ignored.
Example:
// This is a comment
/ This is also a comment (only ONE slash is needed)
myObject = HTML
myObject.value = <BLINK> HTML - code </BLINK>
# This line is also a comment.
Comment blocks: When a line starts with "/*" or "*/"
... it defines the beginning or the end of a comment section respectively. Anything within a comment section is ignored.
Rules:
/* and */ MUST be the very first characters of a trimmed line in order to be detected.
Comments are not detected inside a multiline value parenthesis.
Example:
/* This is a comment
.. and this line is within that comment which...
ends here:
*/ ... this is not parsed either though - the whole line is still within the comment
myObject = HTML
myObject.value (
Here's a multiline value which
/*
ignores comments in side, so this is parsed!
*/
)
Value assignment: The "="-operator
assigns a value to an object path.
Rules:
Everything after the "="-sign and to the end of the line is considered to be the value. In other words: You don't need to quote anything! Please be aware that the value will be trimmed which means stripped for whitespace in both ends.
Value modifications: The ":="-operator
assigns a value to an object path by calling a predefined function which modifies the existing value of the current object path in different ways.
This is very useful for extending lists of page IDs etc. when a value should be extended without redefining it completely again.
Rules:
The portion after the “:=”-operator and to the end of the line is split in two parts: A function and a value. The function is specified right next to the operator (trimmed) and holding the value in brackets (not trimmed).
There are four predefined functions:
prependString: Adds a string to the beginning of the existing value.
appendString: Adds a string to the end of the existing value.
removeString: Removes a string from the existing value.
replaceString: Replaces old with new value. Separate these using “|”.
addToList: Adds a comma-separated list of values to the end of a string value. There is no check for duplicate values, and the list is not sorted in any way.
removeFromList: Removes a comma-separated list of values from a comma-separated list.
There is a hook inside class.t3lib_tsparser.php which can be used to define more functions like this.
Example:
myObject = TEXT
myObject.value = 1,2,3
myObject.value := addToList(4,5)
myObject.value := removeFromList(2,1)
...results in the same like this:
myObject = TEXT
myObject.value = 3,4,5
Confinements: The { } signs
(opening/closing curly braces) means, that you can assign many object-properties in a simple way at once. It's called a confinement or nesting of properties.
Example:
myObject = HTML
myObject.value = <BLINK> HTML - code </BLINK>
...is the same as:
myObject = HTML
myObject {value = <BLINK> HTML - code </BLINK>
}
Rules:
Everything on the second line that comes after "{" is ignored.
The "}"-sign must be the first non-space character on a line in order to finish the confinement. Everything after "}" is ignored.
NOTE: You cannot use conditions inside of braces (except the [GLOBAL] condition which will be detected and reset the brace-level to zero)
NOTE: Excessive endbraces are ignored, but issues a warning in the TypoScript parser.
Multiline values: The ( ) signs
(opening/closing parenthesis) means, that you can assign a multiline value. By this method you can define values which span over several lines and thus includes linebreaks.
Example:
myObject = HTML
myObject.value (
<BLINK>
HTML - code
</BLINK>
)
Rules:
NOTE: The end-parenthesis is extremely important as if it is not found, the parser does not return to parsing TypoScript. This includes the [GLOBAL] condition which will not save you! So don't miss it!
Object copying: The "<" sign
is used to copy one object path to another. The whole object is copied - both value and properties - and it overrides any old objects and values at that position.
Example:
myObject = HTML
myObject.value = <BLINK> HTML - code </BLINK>
myOtherObject < myObject
In this case you have two independent sets of objects/properties which exactly the same (duplicates). They are not references to each other but actually copies:
Another example (copy from within curly brace confinement):
pageObj {10 = HTML
10.value = <BLINK> HTML - code </BLINK>
20 < pageObj.10
}
Here you also make a copy of an object. The object is referred to from the root. You can also use a notation where the object is referenced from the same level. In this case you just write the object but add a period before it in order to denote that they are on the same level.
This is equal to the above example:
pageObj {10 = HTML
10.value = <BLINK> HTML - code </BLINK>
20 <.10
}
Note about references to objects (in TypoScript Templates):
When TypoScript is used in the context of TypoScript Templates you can find that content objects can sometimes be referenced instead of copied. References mean that multiple positions in an object tree can use the same object at another position without making an actual copy of the object but by simply pointing to the objects full object path.
An example based on the above code:
0: myObject = HTML
1: myObject.value = <BLINK> HTML - code </BLINK>
2:
3: pageObj {4: 10 = < myObject
5: }
Watch line 4: This looks like a feature of TypoScript but it is not!!! It is a feature implemented on the context level which means that it only works because the TypoScript Template Engine has been programmed to perceive content object names starting with “<” as a reference to the object path following the < sign.
In fact, if we look at the parsed TypoScript in a node tree we can see that “< myObject” is nothing but the simple value of the object path “pageObj.10”:
This note just served to point out this potential misconception you might get when you begin working with TypoScript in relation to template building.
Object unsetting: The ">" sign:
This is used to unset an object and all its properties.
Example:
myObject = HTML
myObject.value = <BLINK> HTML - code </BLINK>
myObject >
In this last line “myObject” is totally wiped out (removed)
Conditions: Lines starting with “[“
Conditions break the parsing of the TypoScript in order to evaluate the content of the condition line. If the evaluation returns true parsing continues, otherwise the following TypoScript is ignored until the next condition found where a new evaluation will be performed. The next section in this document describes conditions in more detail.
Example:
[browser=netscape]
page.10.value = Netscape
[else]
page.10.value = Not a netscape browser!
[end]
Rules:
Conditions can break the parsing only when outside of any confinement (curly brace levels).
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:
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.
You can also add include-instructions in TypoScript code. Availability depends on the context, but it works with TypoScript templates, Page TSconfig and User TSconfig.
An include-instruction looks like this:
<INCLUDE_TYPOSCRIPT: source="FILE: fileadmin/html/mainmenu_typoscript.txt">
It must have its own line in the TypoScript template, otherwise it's not recognized.
It is processed BEFORE any parsing of TypoScript (contrary to conditions) and therefore does not care about the nesting of confinements within the TypoScript code.
The “source” parameter points to the source of the included content. The string before the first “:” (in the example it is the word “FILE”) will determine which source the content is coming from. This is the options:
FILE | A reference to a file relative to PATH_site. Must be less than 100 KB. Cannot contain “..” (double periods, back path). If you prefix the relative path with such as “EXT:myext/directory/file.txt” then the file included will be sought for in the extension directory of extension “myext”, subdirectory “directory/file.txt”. |
|---|
