TypoScript Syntax

1.2.2. TypoScript Syntax

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]

 

1. 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.

2. 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.

3. 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:

1. /* and */ MUST be the very first characters of a trimmed line in order to be detected.

2. 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:

1. 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:

1. 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).

2. There are four predefined functions:

   1. prependString: Adds a string to the beginning of the existing value.

   2. appendString: Adds a string to the end of the existing value.

   3. removeString: Removes a string from the existing value.

   4. replaceString: Replaces old with new value. Separate these using "|".

   5. 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.

   6. removeFromList: Removes a comma-separated list of values from a comma-separated list.

3. 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:

1. Everything on the second line that comes after "{" is ignored.

1. The "}"-sign must be the first non-space character on a line in order to finish the confinement. Everything after "}" is ignored.

2. NOTE: You cannot use conditions inside of braces (except the [GLOBAL] condition which will be detected and reset the brace-level to zero)

3. 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:

1. 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:

1. Conditions can break the parsing only when outside of any confinement (curly brace levels).