Remember,TypoScript is like a (large) multidimensional PHP array; valuesarranged in a hierarchy - a tree. The "branches" are indicated withperiods (".") - a syntax borrowed from for example JavaScript and whichconveys the idea of defining objects/properties. For more details onthese metaphors you should read the introductory chapters of thisdocument. 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]
Referingto "myObject" we might call it an "object with the value [value 1] andthe 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 realscripting language is; therefore it doesn‘t report any errors if youspecify non-existing objects or non-existing properties. Such anevaluation only makes sense when TypoScript is used in a context (like"TypoScript Templates" or "Page TSconfig"). However we can alwaysevaluate TypoScript for a correct syntax (which means whetherinformation 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):
TypoScriptis parsed in a very simple way; line by line. This means that each linenormally 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
assignsa value to an object path by calling a predefined function whichmodifies the existing value of the current object path in differentways.
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/closingcurly braces) means, that you can assign many object-properties in asimple 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/closingparenthesis) means, that you can assign a multiline value. By thismethod you can define values which span over several lines and thusincludes 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
isused to copy one object path to another. The whole object is copied -both value and properties - and it overrides any old objects and valuesat that position.
Example:
myObject = HTML
myObject.value = <BLINK> HTML - code </BLINK>
myOtherObject < myObject
Inthis case you have two independent sets of objects/properties whichexactly the same (duplicates). They are not references to each otherbut actually copies:
Another example (copy from within curly brace confinement):
pageObj {10 = HTML
10.value = <BLINK> HTML - code </BLINK>
20 < pageObj.10
}
Hereyou also make a copy of an object. The object is referred to from theroot. You can also use a notation where the object is referenced fromthe same level. In this case you just write the object but add a periodbefore 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):
WhenTypoScript is used in the context of TypoScript Templates you can findthat content objects can sometimes be referenced instead of copied.References mean that multiple positions in an object tree can use thesame object at another position without making an actual copy of theobject 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: }
Watchline 4: This looks like a feature of TypoScript but it is not!!! It isa feature implemented on the context level which means that it onlyworks because the TypoScript Template Engine has been programmed toperceive content object names starting with “<” as a reference tothe object path following the < sign.
In fact, if we look atthe parsed TypoScript in a node tree we can see that “< myObject” isnothing but the simple value of the object path “pageObj.10”:
Thisnote just served to point out this potential misconception you mightget when you begin working with TypoScript in relation to templatebuilding.
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 “[“
Conditionsbreak the parsing of the TypoScript in order to evaluate the content ofthe condition line. If the evaluation returns true parsing continues,otherwise the following TypoScript is ignored until the next conditionfound where a new evaluation will be performed. The next section inthis 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).
Thereis a possibility of using so called conditions in TypoScript.Conditions are simple control structures, that validates true or falsebased on some criteria (externally validated) and thereby determineswhether the following TypoScript code until the next condition foundshould 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?
Ofthese examples admittedly the first few is the most realistic, in factthey are readily available in the context of TypoScript Templates. Buta condition can theoretically evaluate any circumstance and returneither true/false which subsequently means the parsing of theTypoScript code that follows.
Where conditions can be used
Thedetection of conditions is a part of the TypoScript syntax but thevalidation of the condition content always relies on the context whereTypoScript is used. Therefore in plain syntax highlighting (no context)conditions are just highlighted and nothing more. In the context ofTypoScript Templates there is a whole section of TSrefwhich defines the syntax of the condition contents for TypoScriptTemplates. For “Page TSconfig” and “User TSconfig” conditions are notimplemented 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)
Soin this example the line “[GLOBAL]” is a condition (built-in, alwaysreturns true) and the line “[ condition 1 ][ condition 2]” is acondition. If “[ condition 1 ][ condition 2]” is true then theTypoScript 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 oftwo conditions being set, but from the TypoScript parsers point of viewthe whole line is the condition - it is in the context of TypoScriptTemplates that the condition line content is broken down into smallerunits (“[ condition 1 ]” and “[ condition 2]”) which are individuallyevaluated and OR‘ed together before they return the resulting true /false value. (That is all done with the class t3lib_matchCondition).
Hereis an example of some TypoScript (from the context of TypoScriptTemplates) where another text is outputted if you use the Netscapewebbrowser (instead of for example Internet Explorer) or use Windows NTas 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>
Youcan now use the Object Browser to actually see the difference in theparsed object tree depending on whether the condition evaluates to trueor false (which can be simulated with that module as you can see):
The special [ELSE], [END] and [GLOBAL] conditions
There‘sa special condition called [ELSE] which will return true if theprevious condition returned false. To end an [ELSE] condition you canuse either [END] or [GLOBAL]. For all three conditions you can also usethem 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>
Herewe have one output text if the browser is Netscape and another if not.Anyways the text is wrapped by <B>|</B> as we see, becausethis wrap is added after the [END]-condition.
Thefact that you can "enable" the condition in the TypoScript ObjectBrowser is a facility provided to simulate the outcome of anyconditions you insert in a TypoScript Template. Whether or not theconditions correctly validate is only verified by actually getting a(in this example) Netscape browser and hit the site.
Anotherexample could be if you wanted to do something special in case a bunchof conditions is NOT true. There‘s no negate-character, but you coulddo 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
Howeverfor the special condition, [GLOBAL] (which resets any previouscondition scope), it is a bit different since that will be detected atany line except within multiline value definitions.
someObject {1property = 234
[GLOBAL]
2property = 567
}
But you will still get some errors if you syntax highlight it:
Thereason for this is that the [GLOBAL] condition aborts the confinementstarted in the first line resulting in the first error (“... short of 1end brace(s)”). The second error appears because the end brace is nowin excess since the “brace level” was reset by [GLOBAL].
So, insummary; the special [global] (or [GLOBAL]) condition will at anytimebreak TypoScript parsing within braces and return to the global scope(unless entered in a multiline value). This is true for any TypoScriptimplementation whether other condition types are possible or not.Therefore you can use [GLOBAL] (put on a single line for itself) tomake sure that proceeding TypoScript is correctly parsed from the toplevel. This is normally done when TypoScript code from various recordsis 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.
Youcan also add include-instructions in TypoScript code. Availabilitydepends on the context, but it works with TypoScript templates, PageTSconfig 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” parameterpoints to the source of the included content. The string before thefirst “:” (in the example it is the word “FILE”) will determine whichsource 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”. |
|---|
聯(lián)系客服
