Modern Template Building, Part 1 (MTB/1)¶

Goal¶

The goal of the tutorial is to equipt you with the state-of-the-art techniques for creating TYPO3 powered websites. It will allow you a quick hands-on experience with the system and provide you with a overall understanding of the factors involved in website production with TYPO3.

If you think this tutorial is too long and want something shorter, please just find another CMS because nothing as powerful and complex a tool as TYPO3 can be described in less space. And even this tutorial is just outlining the over all picture.

Just because TYPO3 costs no money it will not take no time to learn for a developer! It takes a serious time investment and dedication - just like any commercial alternative on its level. So be forewarned. Flying aircrafts takes skills and therefore time to learn. Hopefully this tutorial will get you as quickly as possible onto the launch ramp.

Skill levels¶

The tutorial is divided into four sections:

The Basics - a newbee introduction to building websites with TYPO3, template records, TypoScript and Content Objects (cObjects). Any person who wants to develop with TYPO3 should be familiar with the concepts described here.

Part 1: Integration of an HTML template - this part aims specifically at intermediate HTML-webdesigners with a limited amount of technical knowledge.

Part 2: Creating a Template Selector - this part aims at intermediate web developer with good knowledge of PHP, SQL and programming concepts in general.

Part 3: Extending the Built-In Access Scheme - for advanced TYPO3 /PHP-developers.

Notice: Part 2 and Part 3 are found in `another document, in the extension " <http://typo3.org/doc.0.html?&tx_extrepmgm_pi1[extUid]=490 &cHash=27f9c79d25>`_ `doc_tut_templselect2 <http://typo3.org/doc.0.h tml?&tx_extrepmgm_pi1[extUid]=490&cHash=27f9c79d25>`_ `" <http://typo3 .org/doc.0.html?&tx_extrepmgm_pi1[extUid]=490&cHash=27f9c79d25>`_

You can jump onto any part you like directly. However if you follow the tutorial from the first to the last section you will find the sections to be sequential and that may give you the best step-by-step experience. However the step between the tutorials may require that you gain some experience first!

The extension¶

This tutorial has all its files contained in a TYPO3 extension. Extensions normally contain scripts and resources that extend the capabilities of TYPO3. However this tutorial extension does not interact with TYPO3s core if you install it - it merely serves as a vehicle for transporting the tutorial files to your server and for presenting the tutorial document online on typo3.org.

Therefore to follow this tutorial, first install the dummy-package (see The Basics section) and then import the extension "doc_tut_templselect" from TER (TYPO3 Extension Repository) with the EM (Extension Manager) and you will have all files at hand on your server when you need them.

This tutorial document can either be read online or you can download it as a SXW file from typo3.org for your convenience.

Price¶

You don't have to pay for reading this document. However it has taken the author, Kasper Skårhøj, a full week to prepare, write and complete. None of this work was paid. If you or your company find it useful and it makes you better fit for serving powerful websites to your customers, please consider a donation! You cannot feed me by shoulder padding alone. Otherwise this tutorial could be the last one...

Skill level¶

All developer newbees to TYPO3 regardless of experience in other fields.

Some parts will refer to technologies like SQL, HTML, CSS and PHP. The content is generally of a technical sort since it takes you through the installation of the dummy-package and explains the basics of the frontend template engine in TYPO3.

Enter database information:¶

Create a new table:¶

Import the dummy database, "database.sql":¶

Go to the backend:¶

For these steps to complete nicely you will have to make localconf.php writable (you will be told if it isn't!) and have the database username and password at hand.

Creating a Template Record¶

So what we will do now is to create a template record on the page "Root page". The most easy way is to use the "Template" module:

The next screen will show you this view from the "Template" module. You will use this for editing the template record later:

For now, look at the "Root page" with the "List" module instead:

As you can see there is a "Template" record located on the page "Root page".

This template record will contain the basic instructions to the frontend engine about how the website beginning from this point should be rendered, which features it has, how it is configured, etc. A template record is always needed to start any new website in TYPO3 (using the default frontend engine). However you can personally balance how much of your website design the template record will control directly; you can program a whole website directly inside a template record. You could also instruct the template record to immediately call a PHP function you have created which will render and return all the page content (based on XML, XSLT or other databases - whatever you fancy). You can also choose a middleway mixing the best of both worlds. This is what we do in this tutorial.

Looking at the content you will see these fields of specific interest:

The "Template title" is just the title of your template record - not displayed anywhere.

The "Website title" will be a prefix of the page title as found between the <title> tags of any page.

The "Setup" field is where you enter the instructions that make the frontend engine react in a certain way. These instructions are contained in a hierarchical information structure defined by the TypoScript syntax. Since the instructions from the "Setup" field is defined by the TypoScript syntax you will often find template records referred to as "TypoScript templates".

The "Clear constants" and "Clear setup" flags means that no TypoScript configuration code is inherited from template records earlier in the tree (closer to the root), if any. These flags should always be set for template records serving as main templates ("Rootlevel").

The "Rootlevel" flag simply means: "This template records marks the start of a new website".

Now, back to the viewing of the page "Licensing":

Now, something different popped up. This is what happend:

• Request page with uid "5" (#1)
• Select the first template record on this page (pid=5); Nothing found!
• Since no template record on page with uid "5" was found, check the previous page in the root line.... (#2)
• Select the first template record on this page, "Root page", (pid=1); A template record was found!
• Since a template record was found on page with uid "1", check if the "Rootlevel" flag was set...
• Yes, the "Rootlevel" flag was set. Fine, this is the start of a website. So...
  • Parse the TypoScript configuration of the Setup field.
  • Begin executing the instructions from the Setup field.

The PAGE object (#1)¶

First we define a new "Toplevel Object" (TLO) called "page". Object type is "PAGE" (you can also define a FRAMESET, see TSref). Instead of "page" you could use other strings except a list of reserved TLO's, see TSref about Toplevel Objects .As a property for the "page" object we define the obligatory property, "typeNum", and set its value to 0 (zero).

What all this means is that the Toplevel Object "page" will now be the default handler of any request sent to a page within the branch of the page tree where our template record marks the beginning of a website.

Now we want to instruct the "page" object what to do. Basically we need to look up the possible properties for PAGE objects in the TSref . Some properties are meta properties like the "config" or "includeLibs" property. Others are there to define what HTML output this PAGE object will generate.

The most significant set of properties for PAGE objects is the numerical array of content objects (cObjects) . Each of these content objects can render a string of HTML-content which altogether makes up the content between the body- tags of the page.

The Content Object (#2)¶

In the example above there is a very simple content object - TEXT - defined for the index "10" of the numerical array of content objects in the PAGE object, "page". This cObject has the property "value" set to "HELLO WORLD!". The effect is that this string is returned from the cObject and becomes the content between the page bodytags:

You can see the set of properties for the TEXT cObject here .

TypoScript - no programming language¶

Before we move on; please notice that TypoScript is not a procedural programming language. You might easily be lead to think this and if you have experience with other programming languages and how they work this is a dangerous cocktail since you will be quite confused. In reality, TypoScript merely configures the system to act in a certain way.

In order to explain what TypoScript really is and point you to the difference between this and how it is used in TYPO3, you can look in this document explaining the basics .

Two cObjects?¶

What happens if you enter another content object:

# Default PAGE object:
page = PAGE
page.typeNum = 0

# Content object one:
page.10 = TEXT
page.10.value = HELLO WORLD!

# Content object two:
page.20 = TEXT
page.20.value = HELLO UNIVERSE!

(BTW, lines starting with "#" or "/" are comments.)

Output:

<body bgcolor="#FFFFFF">
HELLO WORLD!HELLO UNIVERSE!
</body>

So - as expected more content objects will just be concatenated!

Changing order?¶

What if the order of definition is changed?

# Default PAGE object:
page = PAGE
page.typeNum = 0

# Content object two:
page.20 = TEXT
page.20.value = HELLO UNIVERSE!

# Content object one:
page.10 = TEXT
page.10.value = HELLO WORLD!

Output:

<body bgcolor="#FFFFFF">
HELLO WORLD!HELLO UNIVERSE!
</body>

The same - the order of rendering is according to the index in the array.

Dynamic content?¶

What if we want the TEXT cObject to insert the page title?

Then you will have to look up in the TSref to see if the TEXT cObject has any properties that allows you to instruct it to do so. It seems that it has. Apart from the "value" property on the same level the TEXT object also has "stdWrap" properties (click here) which can be used to fetch and process data dynamically.

Since the rendering of the cObject TEXT is done in the main scope of the PAGE Object the current record will be the current page record. So referring to a fieldname with the stdWrap property "field" will fetch content from the current page's record. Here the field named "title" will carry the page name (this of course requires knowledge about what fields are available in the pages table!):

# Default PAGE object:
page = PAGE
page.typeNum = 0

# Content object outputting current page title:
page.10 = TEXT
page.10.field = title

Output:

<body bgcolor="#FFFFFF">
Licensing
</body>

Since the current page was the "Licensing" page, that was the title in the output!

stdWrap properties¶

Now that we are playing with the "stdWrap" properties we can wrap the value, process it in different ways etc:

# Default PAGE object:
page = PAGE
page.typeNum = 0

# Content object outputting current page title:
page.10 = TEXT
page.10 {
  field = title
  crop = 8 | ...
  case = upper
  wrap = This is the truncated page title: <b> | </b>
}

( Notice how I changed the formatting in TypoScript so the properties was encapsulated in curly braces. This syntax of TypoScript makes it easier to assign many properties on the same level but the end result is no different from prefixing all the properties with the full object path "page.10".)

Output:

<body bgcolor="#FFFFFF">
This is the truncated page title: <b>LICENSIN...</b>
</body>

Notice how the wrapping string was wrapped around the page title which was further set in uppercase and truncated to max. 8 chars with "..." appended!

We could have achieved the same output by another cObject called "HTML" - the only difference is that all the stdWrap properties are properties to the "value" property of the HTML cObject - not properties of the cObject itself:

# Default PAGE object:
page = PAGE
page.typeNum = 0

# Content object outputting current page title:
page.10 = HTML
page.10.value {
  field = title
  crop = 8 | ...
  case = upper
  wrap = This is the truncated page title: <b> | </b>
}

It's a question of personal preference and style whether you use TEXT or HTML cObjects.

Content from PHP scripts¶

You can easily insert content from PHP scripts if you like to. This is a very recommended practice if you need conditional output just a little above the most basic level since the cObjects and their properties doesn't offer "procedural programming" at all - remember they are just pre-programmed objects reacting on a set of properties, nothing more.

So the USER cObject is what you need.

First, lets create a PHP-file in fileadmin/userfunctions.php :

<?php

class user_functions {

        /**
         * Multiplies the current page ID with $conf["factor"]
         */
        function multiplyTest($content,$conf)   {
                $currentPageUid = $GLOBALS['TSFE']->id;
                $factor = intval($conf['factor']);

                return $currentPageUid * $factor;
        }
}
?>

Then lets configure a cObject of the type USER to call this function with a single parameter, "factor":

# Default PAGE object:
page = PAGE
page.typeNum = 0
page.includeLibs.some_random_id_string = fileadmin/userfunctions.php
page.config.admPanel = 1

# Content object outputting current page title:
page.10 = HTML
page.10.value = The page ID, {field:uid}, multiplied with 15 is:
page.10.value.insertData = 1
page.10.value.wrap = <b> |</b> <br />

page.20 = USER
page.20.userFunc = user_functions->multiplyTest
page.20.factor = 15

And the output should be:

As you can see we defined a few "meta-properties" not directly related to content output:

page.includeLibs.some_random_id_string = fileadmin/userfunctions.php
page.config.admPanel = 1

"includeLibs" is a property that allows you to configure a list of PHP-files (classes and function libraries!) to be included before starting the rendering of the page. "config" allows for a whole lot of configuration options about general behaviour of this PAGE object. In this case the Admin Panel was added in the bottom of the page.

You really should take a few minutes to look at this example. Notice how the property "factor" of the USER object was available in the PHP- function. Notice how the PHP-function retrieves the page ID. Notice how the "admin panel" was included. You can learn a lot from playing a little with this example. Let your fantasy loose for a while since this can give you a good feeling of control.

The Object Browser¶

The Object Browser in the Template module is an indispensable tool for verifying the hierarchical information structure of your template records:

As you can see the TypoScript values are parsed into this nicely organized tree. This lets you verify if every property you have set is at the correct place and even allows you to edit a single value if you make sure "Enable object links" is checked:

Going back to "Info/Modify" you can see that the template Setup field has been modified:

The Object Browser is not intelligent enough to go and change the line with "page.20.factor = 15" - it just inserts a new line in the end which will override any previously set value. You can clean it up manually. The whole point is that the Object Browser provides a fool- proof way of setting these values since the correct object path will always be used.

Try a condition?¶

We could in fact use this situation to demonstrate "conditions" . A very basic condition is to check for the browser:

# Default PAGE object:
page = PAGE
page.typeNum = 0
page.includeLibs.some_random_id_string = fileadmin/userfunctions.php
page.config.admPanel = 1

# Content object outputting current page title:
page.10 = HTML
page.10.value = The page ID, {field:uid}, multiplied with 15 is:
page.10.value.insertData = 1
page.10.value.wrap = <b> |</b> <br />

page.20 = USER
page.20.userFunc = user_functions->multiplyTest
page.20.factor = 15

[browser = msie]

page.20.factor = 30
page.10.value = The page ID, {field:uid}, multiplied with 30 is:

[global]

In Microsoft Internet Explorer this will look like:

In all other browsers it looks like:

The significance of "&type="¶

In this example below there is not only one PAGE object defined. Also the TLO "another_page" is defined as a PAGE object but the "typeNum" property is set to "1". This means that the "page" PAGE object is the handler of default page requests while the "another_page" PAGE object becomes the handler of page requests where the "&type=1" parameter is set in addition to the id-parameter:

page = PAGE
page.typeNum = 0
page.10 = TEXT
page.10.value = HELLO WORLD!

another_page = PAGE
another_page.typeNum = 1
another_page.10 = TEXT
another_page.10.value = HELLO UNIVERSE

The output will be:

And the object tree:

Copying objects¶

Quickly it becomes very practical to divide the TypoScript configuration code of your templates into related units and then assemble them all in the end of the template by copying them into the right positions. This might even include separation of the units into a hierarchy of included template records or static templates thus allowing for reuse of TypoScript. You will learn about that later.

The main feature of TypoScript that allows this is the syntax for copying one branch of the object tree to another. Consider this example:

# Make temporary version of the first cObject:
temp.world = TEXT
temp.world.value = HELLO WORLD!


# Make temporary version of the second cObject:
temp.universe = TEXT
temp.universe.value = HELLO UNIVERSE!


# Default PAGE object:
page = PAGE
page.typeNum = 0

page.10 < temp.world
page.20 < temp.universe

The result is - of course - this:

<body bgcolor="#FFFFFF">
HELLO WORLD!HELLO UNIVERSE!
</body>

If you look in the object browser you can see, that the objects from "temp. ..." has been copied to the paths "page.10" and "page.20". However we might expect seeing the "temp." TLO in the tree, but we don't. The reason is that the TLOs named "temp." and "styles." are unset again after parsing the TypoScript since they are reserved as temporary object spaces available only during parsing - not after parsing.

If we wanted our objects to stay in the tree we could do that by using another TLO:

# Make temporary version of the first cObject:
MY_TLO.world = TEXT
MY_TLO.world.value = HELLO WORLD!


# Make temporary version of the second cObject:
MY_TLO.universe = TEXT
MY_TLO.universe.value = HELLO UNIVERSE!


# Default PAGE object:
page = PAGE
page.typeNum = 0

page.10 < MY_TLO.world
page.20 < MY_TLO.universe

... and the TLO "MY_TLO" is still there:

References - not copies¶

This also means that we can create a reference to the objects at MY_TLO.* since references to cObjects requires them to exist in the structure during after parsing is done (opposite to the "temp" and "styles" TLOs). Thus the script can be rewritten to this:

# Make temporary version of the first cObject:
MY_TLO.world = TEXT
MY_TLO.world.value = HELLO WORLD!


# Make temporary version of the second cObject:
MY_TLO.universe = TEXT
MY_TLO.universe.value = HELLO UNIVERSE!


# Default PAGE object:
page = PAGE
page.typeNum = 0

page.10 =< MY_TLO.world
page.20 =< MY_TLO.universe

It seems like a little change but the impact is huge since objects are NOT copied, merely referered to:

There are some practical consequences and drawbacks to this method. However the upside to references is that a cObject defined at one path in the object tree can be used multiple times by references from within the structure without spending memory on duplicates - which also becomes hard to manage if you want to override properties of all duplicates in the tree. An example of this problem is found in the end of Part 2 in this tutorial.

Notice: References like this are not a part of the TypoScript syntax as such. It's a feature provided internally by the cObjects and thus references can be used only when refering to cObjects, not any other kind of objects or properties (unless noted).

Clearing the cache¶

Finally you must be aware that when you make changes to a template record through the Template module the "Cache-all" is cleared. This must be done because when TYPO3 parses a TypoScript template the resulting structure is saved in the cache so it can be quickly fetched again for the next page delivery. However this means that changes made to template records directly through the List module for instance will not clear the cache - and then you must do it manually with the link under the menu in the left frame.

Generally, before you announce any strange behavior as a bug, please make sure that it wasn't caching of either templates or extension files that bugged you!

Skill level¶

Intermediate webdesigner from HTML/CSS background, not necessarily a web programmer.

In order to complete this section of the tutorial you should have a good knowledge of HTML and CSS. Further you must have a working TYPO3 database with the page tree created in an earlier chapter of this tutorial. Finally you might need an understanding of programming concepts in order to understand everything fully. But don't worry - you are clearly told everything you need to do - just pay attention and take time to understand the examples.

Installing the extension¶

Go to the Extension Manager, import extension from online repository:

Find the extension "automaketemplate", click the import icon:

This should be the result on success:

Go back, select "Available Extensions to Install" and install the extension:

After pressing the "Make updates" button, go back to the Template module and check the Object Browser:

The extension should have added a USER cObject at the object path "plugin.tx_automaketemplate_pi1" as you see above. This cObject can now be used by us instead of the FILE cObject to read Raphaels template file and have it automatically marked up and relative paths corrected!

Configuring the Template Auto-parser¶

As with any extension for which we want to know anything we should consult the manual for the extension on typo3.org. Click this link and you will see the table with properties for the cObject .

To make it very clear to you what the Template Auto-parser does I'll simply insert the output from the plugin as the only content on the page and further I will configure the PAGE object "page" to not output the usual header and footer content.

This is the Setup field content of the template record:

# Configuring the Auto-Parser:
plugin.tx_automaketemplate_pi1 {
    # Read the template file:
  content = FILE
  content.file = fileadmin/template/main/template_1.html

    # Here we define which elements in the HTML that
    # should be wrapped in subpart-comments:
  elements {
    BODY.all = 1
    BODY.all.subpartMarker = DOCUMENT_BODY

    HEAD.all = 1
    HEAD.all.subpartMarker = DOCUMENT_HEADER
    HEAD.rmTagSections = title

    TD.all = 1
  }

    # Prefix all relative paths with this value:
  relPathPrefix = fileadmin/template/main/
}


# Default PAGE object:
page = PAGE
page.typeNum = 0
page.config.disableAllHeaderCode=1

page.10 =< plugin.tx_automaketemplate_pi1

Save template and hit the frontend. You should see exactly what the fileadmin/template/main/template_1.html would look like by itself:

And so...? - you think. But this is rather cool and when you look inside the source code of this page you will see why:

Now, as you can see two main things has happend:

• A lot of blocks in the template file has automatically been wrapped in subparts! (1+2)
• All relative links/references has been prefixed with the path "fileadmin/template/main/" (3)

This is because the Template Auto-parser was configured to handle "elements" like this:

...
  elements {
    BODY.all = 1
    BODY.all.subpartMarker = DOCUMENT_BODY

    HEAD.all = 1
    HEAD.all.subpartMarker = DOCUMENT_HEADER
    HEAD.rmTagSections = title

    TD.all = 1
  }
...

("Elements" are all tags having a start and end tag separately from each other, fx. the <td> tag. Tags with no end tag, fx. <img>, must be defined by the "single" property of the Template Auto-parser)

So the configuration of the elements says that

• a) the element <body> should be wrapped with the subpart marker "###DOCUMENT_BODY###"
• b) the element <head> should be wrapped with the subpart marker "###DOCUMENT_HEADER###". Further any <title> sections should be removed. (We don't want the <title> tag from Raphaels template replicated in our TYPO3 pages...)
• c) All <td> elements found should be wrapped - but since no .subpartMarker value was defined only <td>-tags with a "id" or "class" attribute will be wrapped and then in a subpart marker corresponding to the id/class value. Thus the tag <td id="menu_1"> will have the content inside of it wrapped in the subpart markers "<!--###menu_1###-->...<!--###menu_1###-->".

Now, how can we use this?

Well, the answer is that the Auto-parser allows Raphael to create templates based on modern CSS styling techniques with a conscious use of id and class attributes in the HTML-elements, and at the same time those attributes will serve as the "markers" that TYPO3 uses to replace portions of the template with the dynamic content! Easy for Raphael (the designer), less hazzle for Benoit (the developer) and good for Picouto's finances since less time is used on conversions and manual markup of templates with subpart markers!

Result¶

The result looks like this:

Notice that the menu and content areas have been substituted with content from the TEXT cObjects which were just there as a test!

The HTML-source looks like this:

The <head> section without the <title> tag is inserted

The <body> section inserted, content substitutions performed

The ###header_1### and ###footer### subparts were not substituted since they were not defined at all in the "temp.mainTemplate" TEMPLATE cObject! So this is no error.

The ###menu_1### and ###content### subparts were correctly substituted as we expected since the "temp.mainTemplate" TEMPLATE cObject was in fact configured to do so.

Summary¶

So from Raphaels template TYPO3 automatically extracts the <head> and <body> content, corrects relative paths to images, links, forms and stylesheets, makes substitutions for dynamic content, and inserts each part in the <head> and <body> section of the output page from TYPO3.

The basic framework is now up and running - we just need to add some dynamic content to the menu and content areas! This is most effectively done by TypoScript cObjects for rendering menus and content elements.

Menu objects and item states¶

First of all the cObject we will use to generate menus is the HMENU object. This object calls "menu objects" of the type TMENU or GMENU or GMENU_LAYERS etc. for each menu level we want (which one you use depends on the kind of menu you would like to render - textual, graphic, cascading layers etc.).

For each "menu-object" (that was fx. a TMENU or GMENU) you define general properties for the level it represents and in addition item- specific properties (eg. width and height of a GMENU graphical item). The item-specific properties are always defined for a specific state of the item. The normal state (NO) must always be defined, but in addition to this we could fx. define an active state of the item (ACT) - that means "how should the menu item look, if we are on a page equal to or below that page".

Well, the point of this tutorial is not to teach the details of the HMENU cObject and all derived issues. You should refer to the TypoScript by Example for that.

Now, take a look at the HTML source of Raphaels template:

As you can see he has used a <div> tag for each menu item regardless of level or state. The whole difference lies in the value of the class attribute! This is clever design since the markup becomes so simple that Benoit saves even more time on the implementation! :-) And the full, visual control lies outside of TYPO3 - in the CSS stylesheet.

Also notice how Raphael has provided a design for "active" menu items.

The implementation of this menu is extremely easy. It just goes like this:

First, define a temporary object somewhere in the top of the template record (before the definition of "temp.mainTemplate"):

# Menu 1 cObject
temp.menu_1 = HMENU
  # First level menu-object, textual
temp.menu_1.1 = TMENU
temp.menu_1.1 {
    # Normal state properties
  NO.allWrap = <div class="menu1-level1-no"> | </div>
    # Enable active state and set properties:
  ACT = 1
  ACT.allWrap = <div class="menu1-level1-act"> | </div>
}
  # Second level menu-object, textual
temp.menu_1.2 = TMENU
temp.menu_1.2 {
    # Normal state properties
  NO.allWrap = <div class="menu1-level2-no"> | </div>
    # Enable active state and set properties:
  ACT = 1
  ACT.allWrap = <div class="menu1-level2-act"> | </div>
}

Notice how the red lines contain the extracted HTML-markup that Mr. Benoit clipped from Mr. Raphaels template. Now it's hardcoded in the template record.

The only thing you need to do now is to copy this object to be the cObject of the "menu_1" subpart of the "temp.mainTemplate" cObject:

...
# Main TEMPLATE cObject for the BODY
temp.mainTemplate = TEMPLATE
temp.mainTemplate {
    # Feeding the content from the Auto-parser to the TEMPLATE cObject:
  template =< plugin.tx_automaketemplate_pi1
    # Select only the content between the <body>-tags
  workOnSubpart = DOCUMENT_BODY

    # Substitute the ###menu_1### subpart with dynamic menu:
  subparts.menu_1 < temp.menu_1

    # Substitute the ###content### subpart with some example content:
  subparts.content = TEXT
  subparts.content.value = HELLO WORLD - CONTENT
...

(The red lines represent the change!)

... and the result speaks for it self:

Clearly the page structure (below) is reflected in the menu above!

And exactly how easy will it be to change the menu design? Well, try and edit the stylesheet in "fileadmin/template/main/res/stylesheet.css":

See! This whole approch allows you to put the major factors controlling the visual design - HTML template and stylesheet - outside of TYPO3 for direct and incredibly convenient access for the Mr. Raphael, the HTML/CSS-designer. And Mr. Benoit was required to perform only a minor job of TypoScript programming inside the template record - he simply configured the frontend engine to use Raphaels design work in the way that fits their preferred development style best!

Please refer to TypoScript by Example if you want to play more with the HMENU object and related stuff <http://typo3.org/doc.0.html?&tx_ex trepmgm_pi1[extUid]=269&tx_extrepmgm_pi1[tocEl]=780&cHash=c746a46653> _ .

A content element¶

In the List module, click the page icon of the page "License C", then select "New" and then in the right frame, click the content wizard link:

Select "Text with image to the right" and then the "Normal" column:

After entering the content in the element and saving it you should see something like this:

So we now have a content element in place on the page "License C":

Including a static template¶

To display the content element we need to include a static template which will provide all the many hundred lines of TypoScript code which will perform the rendering for us. This is done by editing the whole template record.

However the first thing you have to do is to install the extension, "css_styled_content":

Just click the Install button and press the accept-button on the next page.

(NOTICE: At the time of this writing (january 2004) the "CSS styled content" plugin is NOT complete! It is on the top-3 of Kaspers todo list and is scheduled for development immediately after the snowboard tour.)

Back to the template: In the Template module, click this link:

Then you should see the "CSS Styled Content" static file available in the box "Include Static (from extensions)":

Click it, save the template and look in the Template Analyzer:

The Template Analyzer shows the hierarchy of template records and static templates which may be attached to the current "main template record". By selecting the static template for inclusion it will simply be included before the rendering of the TypoScript code inside the template record "NEW SITE". This means that any object defined inside the "EXT:css_styled_content/....." static template can be copied and used in the NEW SITE template record. This is what we will do now since the included static template contains an object, "styles.content.get" which is a content object that selects all content elements from the "Normal" column of the current page:

So in the template record, change this part of the definition of the "temp.mainTemplate" object:

...
# Main TEMPLATE cObject for the BODY
temp.mainTemplate = TEMPLATE
temp.mainTemplate {
    # Feeding the content from the Auto-parser to the TEMPLATE cObject:
  template =< plugin.tx_automaketemplate_pi1
    # Select only the content between the <body>-tags
  workOnSubpart = DOCUMENT_BODY

    # Substitute the ###menu_1### subpart with dynamic menu:
  subparts.menu_1 < temp.menu_1

    # Substitute the ###content### subpart with some example content:
  subparts.content < styles.content.get
...

If you refresh the frontend for the page "License C" you should now see this:

In the HTML source code we see this:

Apparently the header of the content element was rendered in <h1> tags. If you select other "Layout" types for the header you will get the rendering in fx. <h2> instead (for Layout 2).

Each line of bodytext is wrapped in <p> tags with the class set to "bodytext". Thus you can specifically address the style of page content from content elements in your stylesheet! Notice how Raphael cleverly already designed the dummy content in the template files to use <p class="bodytext"> tags!

Every content element inserted will have a <a>-tag with the name value set to the uid of the content element. This is anchor points which can be used in the URL to go directly to a certain position on a page.

This is from the HMENU objects rendering of the 2-level menu. Just notice how the link is automatically pointing to the right page and even an additional onFocus handler is set.

The Object Tree?¶

Now, by copying this supposed content element, "styles.content.get", what is it really we are inserting in the object tree? Lets look with the Object Browser:

We find two interesting things:

The object path "styles.content.get" obviously contained a cObject of the type CONTENT. By looking at the attributes it seems reasonable to conclude that it selects records from the table "tt_content" ordering them by the field, "sorting". For more information look up the CONTENT cObject here .

Secondly a whole new TLO (Toplevel Object) was defined - "tt_content". By default the CONTENT cObject selecting records from "tt_content" (#1) will use this TLO (also defined to be a cObject) for rendering each record found!As we can see the "tt_content" TLO is defined as a USER cObject invoking a PHP function from the "css_styled_content" extension - seems correct to me since that is the extension we installed to be in charge of this! For details about that you should consult the documentation for the "css_styled_content" extension .

For the really curious we might even look inside the class "tx_cssstyledcontent_pi1" and check out the logic in there. Here is a snippet from the function main():

   function main($content,$conf)   {
                $this->conf = $conf;

                // This value is the Content Element Type - determines WHAT kind of element to render...
                $CTypeValue = (string)$this->cObj->data["CType"];
                $content="";
                switch($CTypeValue)     {
                        case "header":
                                $content = $this->getHeader().$this->render_subheader();
                        break;
                        case "bullets":
                                $content = $this->getHeader().$this->render_bullets();
                        break;
                        case "table":
                                $content = $this->getHeader().$this->render_table();
                        break;
                        case "text":
                                $content = $this->getHeader().$this->render_text();
                        break;
                        case "image":
                                $content = $this->getHeader().$this->render_image();
                        break;
                        case "textpic":
                                $content = $this->render_textpic();
                        break;
...

Better template structure¶

The only thing left is to organize the template record a little better. Even though the amount of TypoScript used is kept to an absolute minimum we can easily see that such a template record becomes large and unhandy very quickly. The solution is to create a series of template records for inclusion:

First you might create a whole new page on the root level of the page tree. Select the type "sysFolder" (means "storage space for any database element you want") and name it Template Storage.

Then create three template records there as seen here:

Don't set any of the "Clear" flags! Just copy the appropriate "temp.xxxx" object definitions from the "NEW SITE" template into these. The order is also insignificant in this list.

The next step is to include these three templates in the "NEW SITE" main template. So edit the "NEW SITE" template:

The order is important: the first listed template is included first and since the template record "ext: Main TEMPLATE cObject" makes copies of fx. the "temp.menu_1" object it must be included as the last one.

Save the template record and view the new structure with the Template Analyzer:

As you can see, first the static template is included, then the three "base templates" from our storage folder and finally the main template record. For each one you can click the title and look at the content below.

Make clear which parts are dynamic, which are static¶

Mr. Raphael needs first and foremost to understand - probably together with the whole web team - which parts of the page are static parts and which are dynamic. Static parts are everything that TYPO3 does NOT touch. The dynamic parts are however supposed to be substituted with content coming from the data sources inside TYPO3.

When dynamic areas are identified, Raphael needs to make sure two things:

• The part must be encapsulated in a single HTML-element. This could be a <div>-element, a <td>-element, a <span> element .
• The encapsulating element must have either an id or class attribute which the Template Auto-parser plugin is configured to find and wrap in subpart markers. Fx. <td id="content"> for the table cell which must contain the content.

It's totally OK to let dummy content remain in the template file - after all it is just substituted with the dynamic counterparts.

Simplify the markup, use CSS stylesheets¶

We are in year 2004 now and it really is the time to say good bye to the <font>-tag, bgcolor-attributes and put it all into an external stylesheet. For a CMS implementation this technique serves the goal to keep using as many external technologies as possible and only utilize a necessary amount of CMS-specific technology (like TypoScript template records).

In this section of the tutorial the best example has been the 2-level menu:

<!-- Menu table cell: -->
     <td id="menu_1">
             <div class="menu1-level1-no"><a href="#">Menu item 1</a></div>
             <div class="menu1-level1-no"><a href="#">Menu item 2</a></div>
             <div class="menu1-level1-act"><a href="#">Menu item 3 (act)</a></div>
             <div class="menu1-level2-no"><a href="#">Level 2 item</a></div>
             <div class="menu1-level2-no"><a href="#">Level 2 item</a></div>
             <div class="menu1-level2-act"><a href="#">Level 2 item (act)</a></div>
             <div class="menu1-level1-no"><a href="#">Menu item 2</a></div>
     </td>

Lets just look at a single element here (the red one above). This could also have been implemented something like this:

<!-- Menu table cell: -->
     <td id="menu_1">
                     <!-- Menu item level 1, begin -->
             <table border="0" cellpadding="0" cellspacing="0" width="95%"><tr>
               <td bgcolor="#eeeeee"><font face="verdana" size="2">
                       <a href="#" class="menu1-items">Menu item 1</a>
               </font></td>
       </tr>
       <tr>
               <td><img src="gray_dotted_line.gif" width="180" height="1" alt=""/></td>
       </tr>
       </table>
                     <!-- Menu item level 1, end -->
             ...
     </td>

Now, remember that our TMENUITEM object inside the template record was defined to wrap the elements with this simple <div>-section:

temp.menu_1.1 {
    # Normal state properties
  NO.allWrap = <div class="menu1-level1-no"> | </div>
...

... and yes, you guessed it; with the above implementation we would need to wrap the elements something like this:

temp.menu_1.1 {
    # Normal state properties
  NO.allWrap (
                        <table border="0" cellpadding="0" cellspacing="0" width="95%"><tr>
                          <td bgcolor="#eeeeee"><font face="verdana" size="2">
                                   |
                          </font></td>
                  </tr>
                  <tr>
                          <td><img src="gray_dotted_line.gif" width="180" height="1" alt=""/></td>
                  </tr>
                  </table>
)
...

And this wouldn't even be enough: You would also have to add the class name of the A-tag by another property of the NO state object and the "gray_dotted_line.gif" file would need to be prefixed with the correct file path - something like "fileadmin/template/main/".

Don't use class attributes for dynamic links¶

Many designers might think that the best way to mark up their menu elements and other links would be to use a class attribute for the <A>-tag. Example:

<!-- Menu table cell: -->
     <td id="menu_1">
             <div><a href="#" class="menu1-level1-no">Menu item 1</a></div>
             ...
     </td>

However this is not the case since the <A> tag is precisely what is automatically generated by TYPO3! So to make this work for our TMENUITEM we would need additional TypoScript properties:

temp.menu_1.1 {
    # Normal state properties
  NO.allWrap = <div> |</div>
  NO.ATagParams = class="menu1-level1-no"
...

Adds more complex TypoScript properties and gives less flexibiliy in the stylesheet. For instance if you want to control the appearance of the link from CSS in this case you can use

A.menu1-level1-no { color: navy; }
     A.menu1-level1-no:hover { color: red; }

... but you cannot control the wrapping <div>-element since that is not tagged with the any class or id! If you just stuck to the original way where the <a>-element had no class attribute, but the <div>-element had, then you could control both the <div>-layer and all links inside of it:

DIV.menu1-level1-no  { padding: 2px 2px 2px 2px; }
     DIV.menu1-level1-no  A { color: navy; }
     DIV.menu1-level1-no  A:hover { color: red; }

Stay clear of row/colspans!¶

This is most likely the number one killer for dynamic content - using colspan in the making of a dynamic object! That just leaves it out of question. For instance consider this alternative implementation of the menu:

 <tr>

              <!-- Menu table cell: -->
              <td class="menu1-level1-no"><a href="#">Menu item 1</a></td>

              <!-- Page Content Area table cell: -->
              <td id="content" rowspan="7">
                      . . .
              </td>
      </tr>
      <tr>
        <td class="menu1-level1-no"><a href="#">Menu item 2</a></td>
</tr>
<tr>
        <td class="menu1-level1-act"><a href="#">Menu item 3 (act)</a></td>
</tr>
<tr>
        <td class="menu1-level2-no"><a href="#">Level 2 item</a></td>
</tr>
<tr>
        <td class="menu1-level2-no"><a href="#">Level 2 item</a></td>
</tr>
<tr>
        <td class="menu1-level2-act"><a href="#">Level 2 item (act)</a></td>
</tr>
<tr>
        <td class="menu1-level1-no"><a href="#">Menu item 2</a></td>
</tr>

This is almost impossible to implement! The first menu item is in a table row with the content cell, the other 6 menu items has separate table rows. Further the table cell with the content needs a colspan="7" attribute so that it spans all the rows for the menu!

This is clearly a very bad design from the technical viewpoint since:

the mark-up for the menu is scattered over different locations in the HTML-code

there is a dependency between the colspan-attribute and the number of menu items (which is dynamic!)

So designers should stay clear of such designs. Instead designers like Mr. Raphael should learn to create markup for dynamic elements like menu in a manner so they are easily repeatable . These are good examples:

The one from our current template:

<!-- Menu table cell: -->
     <td id="menu_1">
             <div class="menu1-level1-no"><a href="#">Menu item 1</a></div>
       <div class="menu1-level1-no"><a href="#">Menu item 2</a></div>
       <div class="menu1-level1-act"><a href="#">Menu item 3 (act)</a></div>
             ...
     </td>

Alternative implementation with a table:

<!-- Menu table cell: -->
     <td id="menu_1">
             <table border="0" cellspacing="0" cellpadding="0">
                     <tr><td class="menu1-level1-no"><a href="#">Menu item 1</a></td></tr>
               <tr><td class="menu1-level1-no"><a href="#">Menu item 2</a></td></tr>
               <tr><td class="menu1-level1-act"><a href="#">Menu item 3 (act)</a></td></tr>
                       ...
             </table>
     </td>

The examples could be even more complex like the one from earlier which wrapped the element in a table each ! The point is not the amount of HTML per item - the point is the repetitive nature of the markup !

Mr. Raphael should understand these issues so that Mr. Benoit doesn't have to spend hours implementing a flawed HTML-structure - and eventually Mr. Picouto might even be so happy with the speedy development resulting from Raphael and Benoits symbiotic coorperation that he buys them a lunch!