Remember, TypoScript is like the Windows Registry. It is values arranged in a hierarchy. The "branches" are indicated with periods - like objects in JavaScript. But remember, just because JavaScript was an inspiration, TypoScript is not anyway near the same.
Objects: Sometimes we refer to something being an "object". If we're talking about a "menu-object" or "contentObject" it's related to a specific function, but generally a TypoScript "object" is a value with properties.
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!
OK?
Remember, TypoScript is not "executed" like JavaScript and therefore doesn't report any errors if you specify non-existing objects or non-existing properties. Whether or not something happends depends on whether or not you have specified the correct properties to the correct objects. And which "correct objects" there is - that's what this reference is all about. The combinations.
Anyway the TypoScript above looks like this in a node-tree:
The TypoScript syntax applies to both the "Setup" and "Constants" field of the template records.
In the "Setup"-field the TypoScript is "executed" - that is the TypoScript hierarchy is traversed and your definition of objects and values will result in some output - but the TypoScript in the "Constants" field just results in a hierarchy of values where each value may represent an inserted constant in the "Setup" field which is substituted before the template configuration is cached.
About this mechanism (constants), see later in this document.
TypoScript is parsed in a VERY simple way: All lines are devided and parsed (In PHP: exploded into an array).
The first block of characters on a line - that is every character until a "=<>{} "-character (space included) is met - is seen as the object reference. Use only A-Z, a-z, 0-9, "-", "_" and periods (.). This is stricly checked in TypoScript ver2 (comes with Typo3.2+).
Ex: Here myObject is defined as a HTML-content-object and the property "value" is set:
myObject = HTML
myObject.value = <BLINK> HTML - code </BLINK>
...then it's considered a comment.
Ex:
// 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.
... it defines the beginning and the end of a comment section respectively. Anything within a comment section is ignored. Notice these codes, /* 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.
Ex:
/* 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!
*/
)
assigns a value to a property. 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 - stripped for whitespace in both ends.
(opening/closing braces) means, that you can assign many object-properties a simple way at once. It's called a confinement.
Ex:
myObject = HTML
myObject.value = <BLINK> HTML - code </BLINK>
...is the same as:
myObject = HTML
myObject {value = <BLINK> HTML - code </BLINK>
}
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.
NOTE: Excessive endbraces are ignored, but issues a warning
(opening/closing parenthesis) means, that you can assign a multiline value.
Ex:
myObject = HTML
myObject.value (
<BLINK>
HTML - code
</BLINK>
)
NOTE: The end-parenthesis is extremely important as if it is not found, the parser does not return to parsing TypoScript. So don't miss it!
is used to copy one object to another. The whole object is copied - both value and properties - and it overrides any old objects and values at that position.
Ex.
myObject = HTML
myObject.value = <BLINK> HTML - code </BLINK>
myOtherObject < myObject
In this case you have two independent objects exactly the same. They are not references to each other but actually copies.
pageObj {10 = HTML
10.value = <BLINK> HTML - code </BLINK>
20 < pageObj.10
}
Here you also make a copy of an object. The object is refered 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 adds a period before it in order to denote 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: From ver2 of TypoScript the original object is totally wiped out at copying.
There are a possibility of using conditions in TypoScript. Conditions is a simple kind of control structure, that validates true or false based on some criteria. The outcome of the validation determines whether or not, the following TypoScript code should be parsed or not.
Note: Conditions can be used outside of braces only! That means this is not valid:
someObject {1property = 234
[browser=netscape]
2property = 567
}
Note: Condition does not necessarily apply to all uses of TypoScript. For instance the TypoScript style configuration for backend users does not use conditions. However most other does including the most prevalent use; frontend templates (which is what this document is about...)
Note: The special [global] (or [GLOBAL]) condition will at anytime break TypoScript parsing within braces and return to the global scope. This is true for any TypoScript implementation whether other condition types are possible or not. Therefore use [GLOBAL] (put on a single line for itself) to make sure that preceeding TypoScript is correctly parsed from the top level.
A condition has it's own line and looks like this:
(Some TypoScript)
[ condition 1 ][ condition 2]
(Some TypoScript only parsed if cond. 1 or cond. 2 are met)
[GLOBAL]
(Some TypoScript)
Now, if condition 1 or 2 is met, then the TypoScript in the middle would be parsed until [GLOBAL] (or [END]) resets the conditions and parses the TypoScript for everybody.
Here is an example of some TypoScript where another text is output if you use Netscape instead of Internet Explorer or use Windows NT:
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>
Note: Conditions can be used in the global space ONLY!
There's a special condition called [else] which will return true if the previous condition returned false. In this context the condition [end] is better understood as being an alias to [global] which returns us to the global scape.
Here's an example of using the [else]-condition:
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 "test" the outcome of any conditions, you insert in the script. 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]
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 it's 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 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 lest than 100 KB. Cannot contain “..”. 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”. |
|---|
If there's a bug in your TypoScript then you'll know only by the fact that the desired result didn't appear. Any wrong configuration is simply ignored. This can lead to problems because the error is not discovered and therefore it's hard to find.
Your help in the misery is basically the TypoScript Object Browser (see screenshots from above). But you can also set ".debug..." properties for a few objects like stdWrap (.debug, .debugFunc, .debugData) and the menuobjects, GMENU, TMENU, IMGMENU.
