TypoScript Syntax and In-depth Study 1.1

1.1. Introduction

Actually this document should have been much much shorter - after all the TypoScript syntax can be defined in a few lines. However TypoScript has a history of confusing people and therefore this introductory chapter has been dedicated to clearly define what TypoScript is so you can be sure to have the right perception.

My recommendation is that you at least read the next section “What is TypoScript?” and then you can proceed to the chapter “Syntax” and read that. If you are at any time confused about the concept of TypoScript please make sure to come back and read the introduction to the end!

If you are confused already, please don‘t skip anything. Better safe than sorry.

What is TypoScript?

Since people are generally confused about what TypoScript (TS) is, where it can be used and has a tendency to think of it as something complex this document has been written to clearly explain these issues.

First lets start with some basic truths:

1. TypoScript is a syntax for defining information in a hierarchical structure using simple ASCII text content.

This means that:

1. TypoScript itself does not "do" anything - it just contains information.

2. TypoScript is only transformed into function when it is passed to a program which is designed to act according to the information in a TypoScript information structure.

So strictly speaking TypoScript has no function in itself, only when used in a certain context. Since the context is almost always to configure something you can often understand TypoScript as parameters (or function arguments) passed to a function which acts accordingly (eg. "background_color = red"). And on the contrary you will probably never see TypoScript used to store information like a database of addresses - you would use XML or SQL for that.

PHP arrays

In scope of its use you can also understand TypoScript as a non-strict way to enter information into a multidimensional array. In fact when TypoScript is parsed that means it is transformed into a PHP array! So when would you define static information in PHP arrays? You would do that in configuration files - but probably not build your address database!

This can be summarized as follows:

1. When TypoScript is parsed it means that the information is transformed into a PHP array from where TYPO3 applications can access it.

2. So the same information could in fact be defined in TypoScript or directly in PHP; but the syntax would be different for the two of course.

3. TypoScript offers convenient features which is the reason why we don‘t just define the information directly with PHP syntax into arrays. These features include a relaxed handling of syntax errors, definition of values with less language symbols needed and the ability of using an object/property metaphor etc.

For more details see the bottom of the next page.

TypoScript syntax, object paths, objects and properties

See, that is what this document is about - the syntax of TypoScript; the rules you must obey in order to store information in this structure. Obviously I‘ll not explain the full syntax here but just give an example to convey the idea.

Remember it is about storing information, so think about TypoScript as assigning values to variables: The "variables" are called "object paths" because TypoScript easily lends itself to the metaphor of "objects" and "properties". This has some  advantages as we shall see but at the same time TypoScript is designed to allow a very simple and straight forward assignment of values; simply by using the equal-sign as an operator:

asdf = qwerty

Now the object path "asdf" contains the value "qwerty".

Another example:

asdf.zxcvbnm = uiop

asdf.backgroundColor = blue

Now the object path "asdf.zxcvbnm" contains the value "uiop" and "asdf.backgroundColor" contains the value "blue". According to the syntax of TypoScript this could also have been written more comfortably as:

asdf {

  zxcvbnm = uiop

  backgroundColor = blue

}

What happend here is that we broke down the full object path, "asdf.zxcvbnm" into its components "asdf" and "zxcvbnm" which are separated by a period, ".", and then we used the curly brace operators, { and } , to bind them together again. To describe this relationship of the components of an object path we normally call "asdf " the object and " zxcvbnm " the property of that object.

So although the terms objects and properties normally hint at some context (semantics) we may also use them purely to describe the various parts of an object path without considering the context and meaning. Consider this:

asdf {

  zxcvbnm = uiop

  backgroundColor = blue

  backgroundColor.transparency = 95%

}

Here we can say that "zxcvbnm" and "backgroundColor" are properties of (the object) "asdf". Further, "transparency" is a property of (the object / the property) "backgroundColor" (or "asdf.backgroundColor").

Note about perceived semantics:

You may now think that "backgroundColor = blue" makes more sense than "zxcvbnm = uiop" but in reality it doesn‘t!  The only reason that "backgroundColor = blue" seems to make sense is that in the English language we understand the words "background color" and "blue" and automatically implies some meaning. But to a machine like a computer the word "backgroundColor" makes just as little sense as "zxcvbnm" unless it has been programmed to understand either one and take its value as the background color for something. In fact "uiop" could be an alias for blue color values and "zxcvbnm" could be programmed as the property setting the background color of something, eg. a HTML page.

This just serves to point one thing out: Although most programming languages and TypoScript use function, method, keyword and property names which humans can often deduct some meaning from then ultimately the programming reference, DTD or XML-Schema defines the meaning.

Note about the internal structure when parsed into a PHP array:

As stated in the previous chapter TypoScript can be understood as a lightweight way to enter information into a multidimensional PHP array. Lets take the TypoScript from above as an example:

        asdf {

          zxcvbnm = uiop

          backgroundColor = blue

          backgroundColor.transparency = 95%

        }

When parsed, this information will be stored in a PHP array which could be defined as follows:

$TS[‘asdf.‘][‘zxcvbnm‘] = ‘uiop‘;

$TS[‘asdf.‘][‘backgroundColor‘] = ‘blue‘;

$TS[‘asdf.‘][‘backgroundColor.‘][‘transparency‘] = ‘95%‘;

Or alternatively you could define the information in the PHP array like this:

$TS = array(

    ‘asdf.‘ => array(

        ‘zxcvbnm‘ => ‘uiop‘,

        ‘backgroundColor‘ => ‘blue‘,

        ‘backgroundColor.‘ => array (

            ‘transparency‘ => ‘95%‘

        )

    )

)

Personally I‘m still convinced that TypoScript  is the best syntax for the job! Less symbols involved and non-technical users can safely write it (although non-techs are not meant to use TS!) without fearing PHP parsing errors which will harshly abort the execution of page generation (or whatever).