Mastering TypoScript: TYPO3 Website, Template, and Extension Development:

This book is targeted at experienced TYPO3 users and is meant to help you primarily during your day-to-day work. However, before you start with TypoScript, we must clarify the selection of packages and extensions that need to be installed to use this book. It does not matter in principle which TYPO3 package you have installed—TypoScript can be learned with any package. The following instructions are based on an installed dummy package.

Setting up an Example Page Structure

You have bought this book to learn to use TypoScript in your own projects. Here TypoScript is explained using small independent examples, so that the book serves as a reference without you having to work through a large example or case study. However, some topics, such as the template auto-parser can only be explained with the help of a detailed example page structure. So in order to avoid having to define a new example each time in such cases, the following steps define a specific one. You can use the book quite well even if you don't use this example structure; however it makes things easier. The time spent on creating the example pages is less than 5 minutes.

First right-click TYPO3 and point to New. In the right frame New record click on Page (inside):

Give this page a title (e.g. Index); disable the Hide page checkbox in the upper area of the window and save the page.

Call the Index page and click on Functions in the left menu. Make sure that the Create multiple pages wizard is selected in the drop-down list as pages can be created quite easily using this wizard.

All you have to do is to enter the desired page titles.

The pages are created via the Create pages button. You can inspect the results immediately in the page tree.

You can now assign sub-pages to the newly created pages. To do this, point to About Us, select the Create multiple pages wizard again, and create a few sub-pages.

Repeat these steps for additional pages. The result should look like this in the page tree:

That's it. You can always build on this sample installation and keep coming back to it.

The name TypoScript is confusing. TypoScript is not a classical script, let alone a programming language in the usual sense. It cannot even be classified as a descriptive language similar to HTML. What then is TypoScript? To answer this question you must take a look at the basic principle of all Content Management Systems—content and layout must be separated from each other and can be manipulated through templates and stylesheets. Tags that are dynamically replaced by the CMS's content are preferred. The type of tag varies mostly between<Tag> and {Tag}, but the principle is always the same.

But TYPO3 doesn't stop here—because of the ability to create the complete output template with TypoScript, the developer has full control over the layout. The influence of this template on the final design in comparison to normal HTML templates is disproportionately higher.

Then what is TypoScript? The statement that it is not a programming language is not entirely true, since TypoScript, strictly speaking, can be regarded as a declarative programming language. TypoScript is a tool with which you specify what the output of the website and/or TYPO3 will look like. In contrast to a true programming language, you simply use TypoScript to describe the look of the result; the actual path to the solution is not programmed.

Unlike many other CMSs, TypoScript goes much beyond allowing you to integrate dynamic contents. Thanks to TypoScript, JavaScript-based menus, Flash, Graphics, etc. can be integrated with ease. You have maximum control over the design of the website and can control all options that would otherwise be addressed by HTML—simple text output, formatting, and much more. TypoScript also allows you to generate graphics at run time and the display of content can be changed according to the time of day or the user group.

What does this multiplicity of functions mean to you? To begin with it saves you time learning TypoScript. Even though TypoScript is only a declarative programming language, you first have to get familiar with the syntax. Luckily, TypoScript is not as complex as PHP or Java. Although the ambitious TYPO3 developer may find this to be a limitation in some areas, this reduces potential errors. If you have developed complex menus via JavaScript, you know about the problems that crop up until the menu finally works reliably. For example, take a look at a really simple drop-down menu as used on numerous websites.

<script type="text/javascript"> <!--
function MM_jumpMenu(targ,selObj,restore)
{ //v3.0 eval(targ+".location='"+selObj.options[selObj. selectedIndex].value+"'"); if (restore) selObj.selectedIndex=0; } //--> </script>
<form name="demo" method="post" action=""> <select name="themes" onChange="MM_jumpMenu('parent',this,0)"> <option selected>Please choose!</option> <option value="page_one.html">Page 1</option> <option value="page_two.html">Page 2</option> <option value="page_three.html">Page 3</option> <option value="page_four.html">Page 4</option> </select> </form>

This example illustrates some of the aspects and problems of JavaScript menus. If you want to create this type of menu, you have to understand JavaScript. Furthermore, you must have experience as to what browser the syntax works with and how to compensate for functions that create errors in others. Don't forget that this is a really simple example. When we approach dynamic websites, the effort and the likelihood of errors increase. If, for example, you want to provide semi-transparent navigation using graphics and layers, you have to have a thorough knowledge of HTML, DHTML, and JavaScript. The size of such scripts quickly bloats up to several hundred lines. It therefore takes some time before everything is running properly. The debugging adds to the difficulties. How does TypoScript circumvent these? What are its strengths? Take a look at the following menu:

page.10.marks.MENU.1 = GMENU page.10.marks.MENU.1.expAll = 1 page.10.marks.MENU.1.NO
{ backColor = #000000 XY = 100, 20 10 = TEXT 10.text.field = title 10.fontColor = #ffffff 10.offset = 4,14 10.fontFile = fileadmin/verdana.ttf 10.fontSize = 11 wrap = | <br /> } page.10.marks.MENU.2 = GMENU page.10.marks.MENU.2.NO
{ backColor = #c0c0c0 XY = 100, 20 10 = TEXT 10.text.field = title 10.fontColor = #ffffff 10.offset = 4,14 10.fontFile = fileadmin/verdana.ttf 10.fontSize = 10 wrap = | <br /> }

This is how menus are created in TypoScript. The example shown is representative of the size of scripts that create menus. Even graphical menus can be created with scripts of this length and the syntax is much simpler than that of JavaScript.

Obviously menus are not the only area where TypoScript helps developers. Have you ever used PHP to create run time graphics? The experienced PHP developer doesn't usually have a problem with this, but the creation of a corresponding script requires a lot of development and testing time. With TypoScript this is no problem even for those with no PHP experience.

Obviously TypoScript is not a normal programming or scripting language, and yet is very powerful. So how do we ultimately classify TypoScript? TypoScript can be used to configure TYPO3; it can thus be described as a configuration language for which no programming knowledge is necessary. In contrast to true programming or scripting languages, TypoScript lacks elements (such as loops) that are typical of such languages. In fact, TypoScript consists of configuration instructions that are incredibly simple in structure and are reminiscent of CSS in their simplicity (with respect to their syntax and not the effect).

How TypoScript is structured can be seen with the help of the TypoScript Object Browser tool. For this, go to Web | Template and select the TypoScript Object Browser menu from the drop-down list.

Here you can see the TypoScript objects in a clear tree structure. You will learn more about the TypoScript Object Browser and the objects on the following pages.

Using so-called TSConfig instructions you can personalize the back-end for individual users or user groups. For instance, certain modules can be masked out in a user's working environment. For a different user one can, in turn, deactivate single options in a checkbox list. The entire back end can be controlled this way and be customized to the needs of the respective editors.

We have already pointed out that TypoScript is programmed in PHP. However, you do not have to know PHP syntax to be able to work with TypoScript; but knowledge of PHP is definitely an advantage. You can, for example, easily import information from the PHP class files using appropriate objects and values. The following example will show how this works.

Anyone who wants to know more about the structure and the development (from a programming point of view) of TypoScript should take a look at the tslib directory. It contains the PHP classes that control TypoScript.

For a better understanding open the file typo3/sysext/cms/tslib/class.tslib_content.php. You will find numerous PHP functions in it. We will concentrate on the CTABLE() function.

function CTABLE ($conf)
{ $controlTable = t3lib_div::makeInstance('tslib_controlTable'); if ($conf['tableParams'])
{ $controlTable->tableParams = $conf['tableParams']; } // loads the pagecontent $controlTable->contentW = $conf['cWidth']; // loads the menues if any if (is_array($conf['c.']))
{ $controlTable->content = $this->cObjGet($conf['c.'],'c.');
$controlTable->contentTDparams =isset($conf['c.'] ['TDParams']) ? $conf['c.']['TDParams'] : 'valign="top"'; } if (is_array($conf['lm.']))
{ $controlTable->lm = $this->cObjGet($conf['lm.'],'lm.'); $controlTable->lmTDparams = isset($conf['lm.'] ['TDParams']) ? $conf['lm.']['TDParams'] : 'valign="top"'; } if (is_array($conf['tm.']))
{ $controlTable->tm = $this->cObjGet($conf['tm.'],'tm.'); $controlTable->tmTDparams = isset($conf['tm.'] ['TDParams']) ? $conf['tm.']['TDParams'] : 'valign="top"'; } if (is_array($conf['rm.']))
{ $controlTable->rm = $this->cObjGet($conf['rm.'],'rm.'); $controlTable->rmTDparams = isset($conf['rm.']
['TDParams']) ? $conf['rm.']['TDParams'] : 'valign="top"'; } if (is_array($conf['bm.']))
{ $controlTable->bm = $this->cObjGet($conf['bm.'],'bm.'); $controlTable->bmTDparams = isset($conf['bm.'] ['TDParams']) ? $conf['bm.']['TDParams'] : 'valign="top"'; }
return $controlTable->start($conf['offset'], $conf['cMargins']); }

Thanks to this function, elements can easily be positioned with the help of a table. What does this mean for TypoScript? To understand this take a look at the following syntax, which uses the Content Object (cObject) CTABLE:

page = PAGE page.10.marks.TABLE = CTABLE page.10.marks.TABLE { tableParams = width="800" border="0" cellpadding="3" cellspacing="0" offset = 0,0,0,0,0 cMargins = 15,15,15,15 rm.TDParams = width="100" valign="bottom" tm.TDParams = width="300" valign="bottom" lm.TDParams = width="300" valign="bottom" bm.TDParams = width="100" valign="bottom" c.TDParams = width=80% c.10 < styles.content.get tm.10 = HMENU tm.10.1 = TMENU tm.10.1 { NO.allWrap = | target = page }
}

Using page.10.marks.TABLE, a new TypoScript object of the CTABLE type is defined. Using TypoScript, the remaining lines define the look and the content of the table. You are surely familiar with the HTML layout attributes; TypoScript's own attributes such as HMENU etc. will be shown later. Note that you will need templates and placeholders to get this example to work. More information on these can be found in Chapter 4 and Chapter 5. The output of this example is shown below:

If you want to work more closely with the PHP functions, take one function after another and experiment with it. You will gradually understand how the meshing between TypoScript and PHP works. At the same time you also have an opportunity to learn about the weaknesses of TypoScript. Each TypoScript object can only deliver what the programmer has designed into the respective function (except when you develop your own functions).

The core of TypoScript is the typo3/sysext/cms/tslib/index_ts.php file. It charts the information about the template datasets of the website tree. How this works is shown by the following TypoScript:

page = PAGE page.typoeNum = 0 mybicycle.color = blue mybicycle.size = 26

This syntax creates the TypoScript object mybicycle. You assign the properties color and size to the mybicycle object. These two properties in turn are assigned the following values: color becomes blue and size gets the value 26. In the TypoScript Object Browser you will see objects, properties, and values represented as follows:

PHP can also be used directly in TYPO3; we will cover more about this later.

You will get a detailed introduction to TypoScript templates in the next chapter. At this point we want you to simply make an initial contact. If one wants to describe a template, the word 'mould' immediately comes to mind. A template is simply nothing more than a master that is used over and over. Templates determine how the content that is entered by the editor and stored in the database will be displayed on the website. To put it bluntly, you can enter as much as you want into the database—TYPO3 will not be able to display it in the front end without templates. You can check this out with an easy experiment. As an experienced TYPO3 user you have no doubt encountered the error message Error: No pages are found on the rootlevel. This message tells you that no page has been created yet for the current project. The following message, however, is rarer:

When this error message appears all the time in the front end you have to create a template before any content can be displayed. In Chapter 5 you will learn how this works, what template inheritance is, and what peculiarities you need to be aware of when creating templates.

TYPO3 offers ready-made templates to make your work easier for most areas of application. You don't have to develop a new template each time you want to create a link, for example. However, the focus in this book is on the development of your own templates. This will help you create an appropriate solution for each and every application.

Without spending too much time on templates at this time, we want to make the following observations:

You now have an idea of how powerful templates are and what possibilities they offer. In a nutshell, the quality of a TYPO3 website depends on the quality of its templates.

In this chapter we provided an introduction to TYPO3 and the prerequisites for installing it. We set up an example page structure that we will use in the examples throughout this book.

We then introduced TypoScript, a configuration language for which no programming knowledge is necessary. In contrast to true programming or scripting languages, TypoScript lacks elements (such as loops) that are typical of such languages. In fact, TypoScript consists of configuration instructions that are incredibly simple in structure.

We wound up with an introduction to TypoScript templates.