Typo3 templates tutorial: How to create a Typo3 template
March 26th, 2008We would show you how to create a custom template for your Typo3 powered website from scratch. This post is based on what some part of Typo3 community refers to as “traditional” template design as opposed to “modern templating” based on Typo3 extension called TemplaVoila. We would not be talking about how to customize predefined Typo3 templates because to us that is a waste of time and when you look at them it seems like its 1999 again.
We looked into TemplaVoila and our opinion is that if you are just starting to learn Typo3 you better stick to so called “traditional” templating. Also, we felt that our customers who would eventually maintain the Typo3 powered website themselves would find TemplaVoila far too complicated.
If you have just read our first Typo3 post and tried to view your website after you installed Typo3 you would get a “No template found!” error message because Typo3 requires a template to be defined to create any output.
(1) Ok, let’s get started! Follow these steps: Design the HTML template file I guess that you already created a custom HTML/CSS template to use with Typo3.If not then design the simple HTML/CSS template our fetch yourself one. You should have a mock menu with few items (left or top positioned, doesn’t matter), a page headline and put some lorem ipsum mock content. Keep it simple - a basic menu, heading and content is enough to illustrate basic Typo3 templating principles.
(2) Including placeholders for content into your templateIn the next step we would be defining the areas in your template whose contents or functionalities are to be dynamically replaced by your content inputted into Typo3 back‑end. To let TYPO3 know what parts of your template to replace you have to include special placeholders in the HTML template. Two types of placeholders are available for this: subparts and markers.
Subparts are used in pairs to enclose sections of the HTML template that are replaced by the output of your TypoScript configuration.
The name of the subpart is enclosed by ### and subpart name is case sensitive.
Example:
<!–###CONTENT### start –>
… This text would be replaced by Typo3 …
<!–###CONTENT### stop –>
Markers are enclosed by ###, they are used as single tags and distinction is made between upper and lower case.Example:
###BREADCRUMBS###
Main difference between the two is that you can enclose HTML comments inside subparts.
Because Typo3 front‑end creates HTML headers and <body> tags you should insert subparts to let Typo3 know where your <body> tags are. Your headers would be ignored, and you would use TypoScript to configure all stuff like <head> contents, DOCTYPE etc
<body>
<!–###DOCUMENT_BODY### start –>
… your HTML code goes here along with further subparts/markers…
<!–###DOCUMENT_BODY### stop –>
</body>
The HTML template should be prepared so that all resource paths refer to the directories in the file system in which they are stored, relative to the root directory. They should also be accessible from the File > Filelist module (e.g. fileadmin/images/…).
When you are done you can save the file with a tmpl extension and copy it to the server where your Typo3 installation resides.
Here’s a example of Typo3 HTML template:
<html> <head> <title>Welcome</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link href="css/styles.css" rel="stylesheet" type="text/css" /> </head> <body> <!--###DOCUMENT_BODY### start --> <div id="container"> <div id="maincontent"> <div id="left-column"> <img src="fileadmin/graphics/left-img.jpg" border="0" /> <!--###LEFTMENU### start --> <!--###LEFTMENU### stop --> </div> <div id="content"> <div id="you-are-here"> <!--###BREADCRUMBS### start --> <!--###BREADCRUMBS### stop --> </div> <div id="heading"> <!--###HEADING### start -->Heading<!--###HEADING### stop --> </div> <div id="content"> <!--###CONTENT### start --> Content <!--###CONTENT### stop --> </div> </div> </div> <div id="bottom-content-container"> <div id="bottom-content"> <!--###PRINT### start --> <!--###PRINT### stop --> <!--###EMAIL### start --> <!--###EMAIL### stop --> </div> </div> <div id="footer-container"> ###FOOTER### </div> </div><!--###DOCUMENT_BODY### start --> </body> </html>
Ok, so we know that Typo3 template file is HTML file containing special code that Typo3 would use to insert your content. Your template record controls how the Typo3 front-end engine outputs the contents from the database using the HTML template.
Typo3 templates are set up as records in the page tree. Its a good practice to keep all template records in sysFolders. So create a new sysFolder named Templates.
Create a page by envoking Typo3 context menu in a page tree (right click). Set its type as sysFolder.
Now right click the Template sysFolder in page tree and choose New > Template. Name the template “master” as this would be your root template. There are two types of templates: root templates and extension templates. The difference is that root templates are marked as Rootlevel in template record and all pages have Rootlevel template applied to their outputs, whereas extension templates can be found anywhere in the page tree and they are used to extend or modify the root template. Ignore everything else! Just save it, we would be modyfing it right away.
To view the template record go Web > Template > Info/Modify
I guess you would use “Info/Modify” view mostly (little dropdowm menu in the top right screen corner).
In Info/Modify module click “Click here to edit whole template record” link below the “Template information” table. You should get a screen like this:
The two most important fields of a template record are Setup and Constants. Setup contains the TypoScript setup - Typo3’s configurational language that defines all the configurations controlling the appearance and behavior of your website.
The Constants field provides global values - constants to the setup field. Using constants in the right way, you can, for example, change a color value used across several templates from a single location, instead of having to search through all the templates where you used that specific color.
Enter the following TypoScript code into your Setup field:
# You have to create an object and give it the property "PAGE"
# Then you have to define the typeNum
page = PAGE
page.typeNum = 0
# Now you create an object in the object (.10) and give it
# the property TEMPLATE
page.stylesheet = fileadmin/css/styles.css
page.bodyTag = <body>
page.10 = TEMPLATE
page.10 {
template = FILE
template.file = fileadmin/templates/ria.tmpl
# We used the subtitle Page property to display as heading subpart
field = subtitle
subparts.HEADING = TEXT
subparts.HEADING.field = subtitle
subparts.CONTENT < styles.content.get
marks.FOOTER = TEXT
marks.FOOTER.value = Copyright notice blah blah
workOnSubpart = DOCUMENT_BODY
}
(3) Creating Typo3 template record
Save the template record, and create a page in Web > Page module. Enter some contents in NORMAL column and it should appear insted of CONTENT subpart.
You are done! You have a workable page using your custom template!
Check out your result in the front‑end! Typo3 uses caching so if you don’t see your changes click on clear FE cache and reload the FE.
Use comments in TypoScript to get the grasp of what going on in this simple setup and customize it to your needs.
