TypoScript Syntax

1.4.2. Parsing custom TypoScript

Lets imagine that you have created an application in TYPO3, for example a plugin. You have defined certain parameters editable directly in the form fields of the plugin content element. However you want advanced users to be able to set up more detailed parameters but instead of adding a host of such detailed options to the interface - which would just clutter it all up - you rather want advanced users to have a text area field into which they can enter configuration codes based on a little reference you make for them.

The reference could look like this:

 

Root level

Property	Datatype	Description	Default
colors	->COLORS	Defining colors for various elements.
adminInfo	->ADMINFO	Define administrator contact information for cc-emails
headerImage	file-reference	A reference to an image file relative to the websites path (PATH_site)

 

->COLORS

Property	Datatype	Description	Default
backgroundColor	HTML-color	The background color of blablabla...	white
fontColor	HTML-color	The font color of text in blablabla...	black
popUpColor	HTML-color	The shadow color of the pop up blablabla...	#333333

 

->ADMINFO

Property	Datatype	Description	Default
cc_email	string	The email address that blablabla...
cc_name	string	The name of blablabla...
cc_return_adr	string	The return address of blablabla...	[servers]
html_emails	boolean	If set, emails are sent in HTML	false

 

So these are the "objects" and "properties"  you have chosen to offer to your users of the plugin. This reference defines what information makes sense to put into the TypoScript field (semantics) because you will program your application to use this information as needed.

 

A case story

Now lets imagine that a user inputs this TypoScript configuration in whatever medium you have offered (eg. a textarea field):

 

  colors {

    backgroundColor = red

    fontColor = blue

  }

  adminInfo {

    cc_email = email@email.com

    cc_name = Copy Name

  }

  showAll = true

  [UserIpRange = 123.456.*.*]

    headerImage = fileadmin/img1.jpg

  [ELSE]

    headerImage = fileadmin/img2.jpg

  [GLOBAL]

    // Wonder if this works... :-)

  wakeMeUp = 7:00

 

In a syntax highlighted version it would look like this (below) which indicates that there are no syntax errors and everything is fine in that regard:

     0: colors {

     1:   backgroundColor = red

     2:   fontColor = blue

     3: }

     4: adminInfo {

     5:   cc_email = email@email.com

     6:   cc_name = Copy Name

     7: }

     8: showAll = true

     9:

    10: [UserIpRange = 123.456.*.*]

    11:

    12:   headerImage = fileadmin/img1.jpg

    13:

    14: [ELSE]

    15:

    16:   headerImage = fileadmin/img2.jpg

    17:

    18: [GLOBAL]

    19:

    20:   // Wonder if this works... :-)

    21: wakeMeUp = 7:00

(Syntax highlighting of TS (and XML and PHP) can be done with the extension "extdeveval").

 

In order to parse this TypoScript we can use the following code provided that the variable $tsString contains the above TypoScript as its value:

 

     3: require_once(PATH_t3lib.'class.t3lib_tsparser.php');

     4: 

     5: $TSparserObject = t3lib_div::makeInstance('t3lib_tsparser');

     6: $TSparserObject->parse($tsString);

     7: 

     8: echo '<pre>';

     9: print_r($TSparserObject->setup);

    10: echo '</pre>';

1. Line 3: The TypoScript parser class is included (most likely already done in both frontend and backend of TYPO3)

2. Line 5: Create an object of the parser class.

3. Line 6: Initiates parsing of the TypoScript content in the string $tsString.

4. Line 8-10: Outputs the parsed result which is located in $TSparserObject->setup

 

The result of this code is run will be this:

 

  Array

  (

      [colors.] => Array

          (

              [backgroundColor] => red

              [fontColor] => blue

          )

      [adminInfo.] => Array

          (

              [cc_email] => email@email.com

              [cc_name] => Copy Name

          )

      [showAll] => true

      [headerImage] => fileadmin/img2.jpg

      [wakeMeUp] => 7:00

  )

Now your application could use this information in a manner like this:

 

  echo '<table bgcolor="'.$TSparserObject->setup['colors.']['backgroundColor'].'">

      <tr>

          <td>

              <font color="'.$TSparserObject->setup['colors.']['fontColor'].'">HELLO WORLD!</font>

          </td>

      </tr>

  </table>';

As you can see some of the TypoScript properties (or object paths) which are found in the reference tables are implemented here. There is not much mystique about this and in fact this is how all TypoScript is used in its respective contexts; TypoScript is simply configuration values that makes our underlying PHP code act accordingly - parameters, function arguments, as you please; TypoScript is an API to instruct an underlying system.

This also means that now we can begin to meaningfully talk about invalid information in TypoScript - it is obvious that two properties are entered in TypoScript but does not make any sense; "showAll" and "wakeMeUp". Both properties are not defined in the reference tables and therefore they should neither be implemented in the PHP code of course. However no errors are issued by the parser since the syntax used to define those properties are still right. The only problem is that they are irrelevant; it is like defining a variable in PHP and then never use it! A waste of time - and probably confusing later.

As noted there exists no "semantics-checker" for any TypoScript implementation AFAIK at this writing. It might be interesting and very helpful some day if we had that as well so we could also be warned if we use non-existing properties (which could just be spelling errors).