Core Documentation

If you think you perfectly understand TypoScript now (you might already...) then don't bother with this section. I even risk confusing you again. But anyways, here it is - more theoretical information on TypoScript including references to the relationship between XML and XSLT:

XML and TypoScript - all about syntax:

A chunk of "TypoScript code" is like an XML document - it only contains information in a structured way, nothing else.  But in order to store information in TypoScript or XML you need to follow the syntax - rules about how the information values can be  inserted in the structure. Like the grammar for a human language defines in which order words can be combined.

For XML such rules include that "all tags must be ended, eg. <b>...</b> or <br />", correct nesting, using lowercase for element and attribute names etc. If you follow these rules an XML document is called "well formed". For TypoScript similar rules exist like "The = operator assigns the rest of the text string as the value to the preceeding object path" or "A line starting with # or / is a comment and therefore ignored".

XSLT and "TypoScript Templates" - all about semantics (meaning, function):

This is syntactically valid XML:

<asdf>qwerty</asdf>

And this is syntactically valid TypoScript:

asdf = qwerty

And this is syntactically valid English:

footballs sing red

But none of these examples make sense without some reference which defines how elements, values and words can be combined in order to form meaning - they need a context. This is called semantics. For human languages we have it internally because we know footballs can't sing and you can't "sing red" - we know it's nonsense while the sentence is correctly formed. For an XML document you have it by the DTD or schema which defines if the element "<asdf>" exists on that level in the document (and if not, then it's nonsense) and for TypoScript you have it by the reference document for the context where the TypoScript syntax is used to define an information hierarchy - for instance the "TSref" for TypoScript Templates or the "TSconfig" document for "Page TSconfig" or "User TSconfig".

So an XML document makes sense only if you know the relationship of the information stored inside of the document and that is required if you want an XSLT stylesheet to transform one XML document to another document. In fact an XSLT stylesheet is like babelfish for XML - it translate one "language" of XML into another "language" of XML.

Similarly TypoScript is used as the syntax to build "TypoScript Templates" (containing semantics - meaning); the information only makes sense if it follows the rules defined in the "TSref" document.

BTW, the comparison of "TypoScript Templates" and "XSLT" is intensional since both can be described as declarational programming languages  - programming by configuring values which instructs a real procedural program  (eg. the TypoScript Frontend Engine which is written in PHP) how to output data. More is written on this issue on typo3.org.

For more on syntax and semantics, you can read this link that I found on the net.

This question cannot be answered completely since this document only describes the syntax of TypoScript and not any of the contexts where TypoScript syntax is applied for configuration; theoretically anyone could use the TypoScript parser class in TYPO3 to generate configuration for their own local extensions using their own local "semantics" (see another chapter in this document).

But at least we can mention the three main applications of the TypoScript syntax as used in TYPO3s core parts:

Page TSconfig

Each page record in TYPO3 has a field where you can enter "TSconfig". The main idea with Page TSconfig is that you can configure individual behavior for separate parts of the page tree. This is possible because the TypoScript code entered in the TSconfig fields is accumulated for all pages in the root line of the current position in the page tree starting from the root and going outwards. Thus TypoScript settings in TSconfig fields of outer pages can override those settings of pages closer to the root.

For instance you may have two separate websites  located in separate branches of the page tree. The one website might support content from only the "normal" column while the other website supports it for both the "normal" and "border" column. Since the Page module by default shows all four possible columns you may want to instruct the page module to show only the normal column and normal + border column respectively. But this will only be possible if you can somehow tell the system that from this page and outwards, use only "normal" column and from that page and outwards use only "normal" + "border" column. So in the root page of the two-column website you enter this line in the TSconfig field:

And likewise for the one-column website you enter this value in the TSconfig field of the root page:

Now the "Page" module will receive the value of the property "colPos_list" when showing the page content available for any subpage of the root page where the configuration was entered. Accordingly only the configured columns will be shown.

The objects and properties you can use here is generally defined in the document "TSConfig" in addition to local extension documents.

User TSconfig

Each frontend and backend user and group has a field for input of TSconfig. The main idea with User TSconfig is that you can configure individual behavior for groups and even users themselves. The possibilities are normally settings which are on a more detailed level than what you can already set as permission settings in the main forms for users/groups. For instance you could configure how many clipboard pads a user should see or whether a "Save document and add new" button should appear for all forms for this user - stuff which is clearly too detailed for a spot in the main form for permissions and settings.

Like with Page TSconfig the content of the TSconfig fields are accumulated in a certain order; the order of member groups and finally the users own fields settings. Thus a setting for a user will override the setting for one of his member groups.

To mention an example of what you can do with User TSconfig for a backend user, then this line will enable the "Save document and create new" button in editing forms:

The objects and properties you can use here is generally defined in the document "TSConfig" in addition to local extension documents.

TypoScript Templates

The most (in)famous and extensive use of TypoScript is in the frontend engine where TypoScript is used to configure how the frontend engine will put together the website output. This is probably also where TypoScript clashes most with traditional ideas of template building in web design and confuses people to think of TypoScript as a programming language - with the result that they find it even more confusing. (If TYPO3 has a scripting language it is not TypoScript  but PHP!)

This introduction to TypoScript tries to eliminate this confusion and therefore let us make two statements about how TYPO3 handles templates:

A TypoScript Template works a little like the Page TSconfig; it is a database record attaching its TypoScript content to a certain page and from that page and outwards the configuration contained in the TypoScript will affect the pages until a new template record is found which overrides content from earlier in the tree. Thus TypoScript Template records are effectively defining which page is the root page of a website:

TypoScript Templates contain a field for the TypoScript configuration code ("Setup" field) but a template record like the one on the picture above ("NEW typo3.org") can also contain references to other template records and files which contain predefined generally useful TypoScript code which is included and thus reusable/sharable across templates. The order of included TypoScript template records / files can be visually seen with the Template Analyzer extension (tstemplate_analyzer):

To get more background knowledge about how TypoScript templates work please read the document TypoScript Templates. To read about all standard objects and properties you can use in building TypoScript templates you should refer to TypoScript reference - TSref. For practical examples when you want to learn by doing, look at TypoScript by Example.

Since TypoScript has a line-based syntax which most of all resembles what is found in simple text based configuration files it is also authored in ordinary textarea input fields inside of TYPO3. An example is the "TSconfig" box of a regular page header:

This is typically how TypoScript is entered - directly in form fields. No syntax highlighting, no way of using TAB stops, no linenumber counting etc. Quite boring and rudimentary. Of course the lack of such features is not a political manifest but rather the lack of the ability to create such features with a simple textarea. Could anyone provide a nice Java-editor instead we would be happy. (In the meantime you can find TypoScript syntax highlighting for certain text editors. Ask on the mailing lists or search typo3.org).

However there are some helpful features:

Parsing TypoScript

This means that the TypoScript text content is transformed into a PHP array structure by following the rules of the TypoScript syntax. But still the meaning of the parsed content is not evaluated.

During parsing, syntax errors may occur when the input TypoScript text content does not follow the rules of the TypoScript syntax. The parser is however very forgiving in that case and it only registers an error internally while it will continue to parse the TypoScript code. Syntax errors can therefore  be seen only with a tool that analyzes the syntax - like the syntax highlighter does.

The class "t3lib_tsparser" is used to parse TypoScript content. Please see another chapter in this document for details.

Storing parsed TypoScript

When TypoScript has been parsed it is stored in a PHP array (which is often serialized and cached in the database afterward). If you take the TypoScript from the introduction examples and parses it you will get a result like below:

First, the TypoScript:

asdf = qwerty

asdf {

  zxcvbnm = uiop

  backgroundColor = blue

  backgroundColor.transparency = 95%

}

Then after parsing it with the function "parse()" in the t3lib_tsparser class the internal variable $this->setup in that class will contain a PHP array which looks like this (with the print_r() PHP function):

Array

(

    [asdf] => qwerty

    [asdf.] => Array

        (

            [zxcvbnm] => uiop

            [backgroundColor] => blue

            [backgroundColor.] => Array

                (

                    [transparency] => 95%

                )

        )

)

You can also print the array by an API function in TYPO3, namely t3lib_div::view_array() or just debug(). Then it looks like this:

As you see the value ("blue") of the property "backgroundColor" can be fetched by this PHP code:

$this->setup['asdf.']['backgroundColor']

So you can say that TypoScript offers a textbased interface for getting values into a multidimensional PHP array from a simple text field or file. This can be very useful if you need to take that kind of input from users without giving them direct access to PHP code - hence the reason why TypoScript came into existence.

"Executing" TypoScript

Since TypoScript itself contains only information (!) you cannot "execute" it. The closest you come to "executing" TypoScript is when you take the PHP array with the parsed TypoScript structure and passes it to a PHP function which then  performs whatever actions according to the values found in the array. This is the syntax/semantics debate again.

Syntax highlighting of TypoScript code is done by various analysis applications in TYPO3 like the Template Analyzer for TypoScript Templates or the User Admin module or Page TSconfig function in the Info module. These typically allows you to view the TypoScript in each context highlighted with syntax.

Here is an example from Page TSconfig:

In the extension "extdeveval" you will also find a tool, "Code highlighting", which can analyse TypoScript code adhoc:

There are various modes of display:

The analytic mode (displayed above) colors all parts of the syntax:

Another mode is the "Block mode", which simply indents the TypoScript code:

Finally you will be warned if syntax errors are found and ignored data will also be highlighted in green:

Debugging

Debugging TypoScript for syntax errors can be done with this tool and any other place where the syntax highlighter is used. But this will only tell you if something is syntactically wrong with the code - whether you combine objects and properties semantically correctly depends on the context and cannot be told by the TypoScript parser itself.

Currently no tools exist to do semantically checking for either TypoScript Templates, Page TSconfig or User TSconfig (writing summer 2003)

(This tool for syntax highlighting is available from TYPO3 version 3.6.0)

This page is the final word in this introduction chapter to the TypoScript syntax. It contains a few remarks and answers to questions you may still have. So here it goes:

Myth: "TypoScript is a scripting language"

This is misleading to say since you will think that TypoScript is like PHP or JavaScript while it is not. From the previous pages you have learned that TypoScript strictly speaking is just a syntax. However when the TypoScript syntax is applied to create TypoScript Templates then it begins to look like programming and the parallel to XSLT might also hint at that.

In any case TypoScript is NOT a comparable to a scripting language like PHP or JavaScript. In fact, if TYPO3 offers any scripting language it is PHP itself! TypoScript is only an API which is often used to configure underlying PHP code.

Finally; The name "TypoScript" is misleading as well. We are sorry about that, too late to change now.

Myth: "TypoScript has the same syntax as JavaScript"

TypoScript was designed to be simple to use and understand. Therefore the syntax looks like JavaScript objects to some degree. But again; it's very dangerous to say this since it all stops with the syntax - TypoScript is still not a procedural programming language!

Myth: "TypoScript is a proprietary standard"

Since TypoScript is not a scripting language it does not make sense to claim this in comparison to PHP, JavaScript, Java or whatever scripting language.

However compared to XML or PHP arrays (which also contain information) you can say that TypoScript is a proprietary syntax since a PHP array or XML file could be used to contain the same information as TypoScript does. But this is not a drawback: For storage and exchange of content TYPO3 uses SQL (or XML if you need to), for storage of configuration values XML is not suitable anyways - TypoScript is much better at that job (see below).

To claim that TypoScript is a proprietary standard as an argument against TYPO3 is really unfair since the claim makes it sound like TypoScript is a whole new programming language or likewise. Yes, the TypoScript syntax is proprietary but extremely useful and when you get the hang of it it is very easy to use. In all other cases TYPO3 uses official standards like PHP, SQL, XML, XHTML etc. for all external data storage and manipulation.

The most complex use of TypoScript is probably with the TypoScript Template Records. It is understandable that TypoScript has earned a reputation of being complex when you consider how much of the Frontend Engine you can configure through TypoScript Template records. But basically TypoScript is just an API to the PHP functions underneath. And if you think there are a lot of options there it would be no better if you were to use the PHP functions directly! Then there would be maybe even more API documentation to explain the API and you wouldn't have the streamlined abstraction provided by TypoScript Templates. This just served to say: The amount of features and the time it would take to learn about them would not be eliminated if TypoScript were not made!

Myth: "TypoScript is very complex"

TypoScript is simple in nature. But certainly it can quickly become complex and get "out of hand" when the amount of code lines grows! This can partly be solved by:

Why not XML instead?

A few times TypoScript has been compared with XML since both "languages" are frameworks for storing information. Apart from XML being a W3C standard (and TypoScript still not... :-) the main difference is that XML is great for large amounts of information with a high degree of "precision" while TypoScript is great for small amounts of "adhoc" information - like configuration values normally are.

Actually a data structure defined in TypoScript could also have been modeled in XML. Currently you cannot use XML as an alternative to TypoScript (writing of June 2003) but this may happen at some point. Lets present this fictitious example of how a TypoScript structure could also have been implemented in "TSML" (our fictitious name for the non-existing TypoScript-Mark Up Language):

styles.content.bulletlist = TEXT

styles.content.bulletlist {

  current = 1

  trim = 1

  if.isTrue.current = 1

        # Copying the object "styles.content.parseFunc" to this position

  parseFunc < styles.content.parseFunc

  split {

    token.char = 10

    cObjNum = 1

    1.current < .cObjNum

    1.wrap = <li>

  }

    # Setting wrapping value:

  fontTag = <ol type="1"> | </ol>

  textStyle.altWrap = {$styles.content.bulletlist.altWrap}

}

That was 17 lines of TypoScript code and converting this information into an XML structure could look like this:

<TSML syntax="3">

    <styles>

        <content>

            <bulletlist>

                TEXT

                <current>1</current>

                <trim>1</trim>

                <if>

                    <isTrue>

                        <current>1</current>

                    </isTrue>

                </if>

                  <!-- Copying the object "styles.content.parseFunc" to this position -->

                <parseFunc copy="styles.content.parseFunc"/>

                <split>

                    <token>

                        <char>10</char>

                    </token>

                    <cObjNum>1</cObjNum>

                    <num:1>

                        <current>1</current>

                        <wrap>&lt;li&gt;</wrap>

                    </num:1>

                </split>

                  <!-- Setting wrapping value: -->

                <fontTag>&lt;ol type=&quot;1&quot;&gt; | &lt;/ol&gt;</fontTag>

                <textStyle>

                    <altWrap>{$styles.content.bulletlist.altWrap}</altWrap>

                </textStyle>

            </bulletlist>

        </content>

    </styles>

</TSML>

That was 33 lines of XML - the double amount of lines! And in bytes probably also much bigger. This example clearly demonstrates why not XML! XML will just get in the way, it is not handy for what TypoScript normally does. But hopefully you can at least use this example in your understand of what TypoScript is compared to XML.

The reasonable application for using XML as an alternative to TypoScript is if an XML editor existed which in some way makes the entering of XML data into a structure like this possible and easy.