Login / Status
developer.Resource
Home . Documentation . Document Library . Tutorials
Sponsors
hosted by punkt.deTYPO3 and Open Source Magazine

1.9. Templates

During this lengthy document you might have wondered time and again - how can I change that green background color? Or how can I put in my own logo. And the fonts - I want Times, not Arial and Verdana.

Before we look at these issues you must understand something fundamental about how most CMSs work: they separate content from presentation. This means the pages and content are stored in the database without any colors or fonts or background images attached to them. That information is instead located in the template and stylesheets which normally apply to the whole website when pages are shown. Thus a single change in the template will affect the overall appearance of the website for all pages. This is a great and very important feature of a CMS! Just ask people who made an html-file based website with 100+ pages and wanted to make a redesign...

Static and dynamic content

Consider the "FC Bigfeet" website:

Dynamic parts: On this website the menu (#1), the page headers (#2) and the "Last update" section (#4) are indirectly dynamic parts of the page. This means they change from page to page automatically. We cannot directly affect these items per page. They are dynamically programmed parts of the template.

However the content area (#3) is a directly dynamic part of the page since this is where the page specific content is inserted. We can affect this by adding, removing and rearranging page content elements! This area is not at all a part of the template (excepts its formatting in colors and fonts) since we directly control it by the content elements.

Static parts: Apart from the dynamic parts the template consists always of the same logo (#5), the same background image (#6) and the same background color (#7). These parts are also a part of the template (like the indirectly dynamic parts) but they never change by any action. Always the same on each page.

Template records?

So how does TYPO3 implement this principle? Well, you can read in-depth information about the recommended approach for professionally made website in the tutorial Modern Template Building. However this is written for people who are professionally working with web design in teams with developers, designers etc. So the level is a bit higher than this tutorial claims to be.

But the main point is - the template record. This is a control element that instructs TYPO3 how to handle a certain branch of the page tree. If this seems like an awkward approach to you at first then so be it - it's in fact highly consistent with what you have learned already and further it makes perfect sense when you later wants to make many sites in the same page tree including multiple templates etc.

If you look at the simple FC Bigfeet website in our case notice that the root page of the website contains such a template record:

Making changes to the template

Let’s try to change a few things in the template record, "NEW SITE, based on standard". Simply edit it:

For standard templates the "Constants" field is often the place to change values. Constants are later inserted in the Setup field and can be inserted many places. So one change to a constant may mean many changes different places in the final TypoScript configuration code of the template.

In our case, let’s add a red background color in the menu frame (see above).

After saving the template record, click "Clear all cache" in the "Admin Functions" menu:

Always do that if you edit template records directly (not needed when you use the Template module though).

The result is:

You can play with other values as well!

The constant editor

The better way to handle these changes is to use the Template module in the "Constant Editor" view:

You can access a lot of options here, there are visual explanations for most of them and you can select from various categories. You can also find the menu background colors listed here ("Basic" category):

Notice how this is really just a wizard that edits the constant from before called "menu.bgCol"!

Likewise you can easily change and upload images for use as logos or background images:

Here we change the current background image to be the logo instead (#1) and with the "Browse" button you can pick up a local image on your hard drive to use as a new logo - soon you will have a website for your company and not a football club!

Now, there is no reason for telling you more about these features since they are pretty obvious and the only way for you to get acquainted with them is to use them, play with them, see what happens. So do that!

Configuring the front end user folder?

Remember the notice about the required change in the template before the frontend user logins would work? This is the place to discuss that.

See, when the login form is rendered it needs to know in which page (sysFolder) to look for the users that are allowed to log in. This is done by setting a constant - "styles.content.loginform.pid" - to the uid value of the sysFolder "Users".

In this example, the uid of the storage sysFolder is "14":

So all we need to do is set the number "14" in this field:

This field is found among the 64 values listed under the CONTENT category of the Constant Editor. You can set the value manually in the "Constants" field as well of course.

The Setup field

The best way to edit a templates Setup or Constants field really is to use the "Info/Modify" view. Here you get direct access to the fields from the template record. This is done as a help for developers who will be using this a lot:

(Notice how  there is a link (#1) below the menu block which directly points you to editing of the full template record if you need it).

In the setup field you find a few lines:

These are clearly strange codes to you and they do require a manual and some background knowledge to get done right! So don't worry.

The first line (#1) inserts an alternative sitemap to the default (which is quite boring), then a stylesheet is configured for the page (#2). This is used by the "mininews" plugin which has all it's formatting done by CSS (contrary to other parts of this standard template which is from the time where <font>-tags were mainly used). Finally we find configuration for the newsletter plugin (#3). This was needed to make sure people didn't need to first receive an email with a link before they could subscribe. Then the danish language was configured (#4) and the Login User Tracking feature enabled (#5).

This was just a short description. Remember that these options does not speak for themselves. You will need more knowledge from various source (like TSref) before you understand them fully. For now you can just conclude that the Setup field is apparently the place to add such stuff! And this stuff is called TypoScript!

The Object Browser

As a final note to the Setup field (for now) I will introduce the Object Browser:

This tool shows visually the object tree of the TypoScript from the Setup field. If you noticed the TypoScript line for the danish language configuration ("page.config.language = dk") you can clearly see the logic of this tree view.

Notice that TypoScript is really not a scripting language with control structures but rather a declarational configuration language which creates an information hierarchy used internally to instruct the template engine what to do and in which order - much like the Registration Database in Windows. If TYPO3 has any scripting language it is PHP itself! Therefore TypoScript is not a new, proprietary technology that should have been XSLT instead or so - rather TypoScript is an unavoidable - and in that case brilliant - configuration language to bind external parts together (such as content, templates, PHP and XML or whatever). But well, you will have to learn it of course. But there really is no alternative and the degree to which you want to use TypoScript is partly up to you. But you will know more from other tutorials about this.

Back to work: If you "Enable Object Links" (bottom of page) you can even change the values from this great visual overview:

Click the property you want to edit:

Change the value and save:

It's that easy!

Now, how could you know what this option means? Well, you will still need a little more background knowledge but the TS wizard helps you with the syntax when you know what to look for:

For the "page.config" object there are properties which can be displayed with the TSreference Wizard:

In the window that pops up you can now search for the object that you need the property reference for. This is the part where you have to know what applies to your specific object page (in our case "page.config"):

And the next screen will conveniently show you the properties.

In fact this information is drawn directly from the online manuals and could also have been found on typo3.org. Just look at the CONFIG object in TSref.

TSref

The TypoScript reference (TSref) is a very well known document in the collection of documents that belongs to TYPO3. It contains the description of all the TypoScript objects you can use to create templates in TYPO3. It's the manual on what content you can put into the Setup field of template records.

Before you dive into TSref please notice that it only makes sense if you know what  you are looking for already! It's a reference listing all properties. So if you know which property to search for it's very useful - even indispensable!

TypoScript by Example

The better way to go if you want play around on your own is TypoScript by Example. This document contains a lot of examples arranged as mini-tutorials on TypoScript related topics.

Change template?

Well in our case the FC Bigfeet template is based on the standard template called "BUSINESS". This is where all the other configuration seen in the object browser comes from!

You can see this structure with the "Template Analyzer" view in the Template module:

All the "elements" in this upside-down tree represent pre-made TypoScript content for the template! So when you look at the Setup or Constant field of the main template record "NEW SITE, based on standard" (#1) and think where all the real stuff comes from - that is the answer. It has been pre-included from static templates by the parser.

If you want to see the content for each element, just click its title.

Static templates

The static template "styles.sitemap.gs" was included in order to get the nice tree-style sitemap on the web site. The static template file "Ext:da_newsletter_subscript..." was included to get the configuration right for the newsletter subscription (see the video previously). Finally the static template "template; BUSINESS" (standard template) is the key element to our websites look.

All this is editable within the template record. Go to the list module and edit it:

Clearly the "Include static" field contains the static templates as I told you (#1 and #2) and the "Include static (from extensions)" holds the reference to the static template file from the Newsletter extensions (#3). The checkboxes "Clear" and "Rootlevel" should normally just be set (#4) for main templates.

Generally static templates are not used so much in professional websites made with TYPO3. The reason is that such websites are normally custom work requiring custom TypoScript code. Static templates contain general TypoScript and that is very useful but also limited to some degree.

However in almost any template - even custom designs - a static template for rendering the page content elements is included. This is done since creating templates and rendering code for the total number of combinations of content element is a very large job and therefore it make a lot of sense to reuse code there!

Change template

Let’s try another standard template than the one called "BUSINESS". In the "Include static" field remove the BUSINESS template and add the CANDIDATE template instead:

Save the result, click "Clear All Cache" and check out the website:

As you can see the content elements are the same, the background color the same, the stylesheet used for the news teasers is the same - but the template is different! This is what templates do! They change the overall structure of the website! This is how easy it would be to make a re-design of a 10, 100 or 1000 page website in TYPO3 - a single change in a template affects all pages!

Now in this new template there seems to be a feature we didn't have before. That is the border column.  We can put content here.

Content in multiple columns

Page TSconfig

The first thing we have to do is to change the "Page TSconfig" option that keeps TYPO3 from displaying more than just the "Normal" content column in the Page module. Edit the page header of the root page "FC Bigfeet":

Add ",3" to the list as shown here:

This will instruct the Page module to display both the Normal (0) and Border (3) content column. If you want to know about possible options to set, click the "TS" button to the right. In the window that pops up, find "mod.SHARED":

This will show you the property "colPos_list" including a description of what it does. It even also allows you to click the property and it will be transferred back to the TSconfig field.

Save the page header and go the Page module - you will now see an additional content column shown:

Now, try to add a content element here. Just click the "New" icon:

Then select an ordinary "Text" element type and enter some content:

Notice the content of the field "Columns" from the secondary options of the "Type" field - it has the value "Border". This is precisely the setting that will make this content element appear in the Border column and not the Normal column! This field was preset before creation of this form.

Press "Save document and close" button. Back in the Page module you will see the new content nicely presented in the right column as expected:

But it should also be displayed on the website at the right position! So check the frontend as well:

And that was the case right away!

Understanding "Page TSconfig"

Now, the little change we did in the "TSconfig" field of the root page was quite interesting. This was a piece of configuration code which had some effect on how the backend works - in that particular branch of the page tree! "Page TSconfig" is thus a powerful concept that allows you to fine tune the behavior of modules, Rich Text Editor and other elements. The syntax of the codes you enter is TypoScript syntax - the same as used for the template records. But it has nothing to do with templates in the frontend - only the configuration internally of features. Like you just saw - enabling another column for content in the Page module!

If you want to know about the properties of TSconfig you can find the reference for it on typo3.org. This particular option was documented on this page (look  for the header "Shared options for modules (mod.SHARED)").

Verifying Page TSconfig

To view the page TSconfig settings for any point in the page tree use the Info module with the "Page TSconfig" view:

As you can see - same kind of tree structure shown as in the Object Browser.

Undo the template change

Before we continue let us reset the template to the BUSINESS type again. If you didn't make any changes to the template record in the mean time we can easily do this by just clicking the Undo button - that will restore the previous state of the record in the database. Select "Edit" for the template record:

After the screen has refreshed check the result. The previous setting of the static template box should be shown again:

(If this is not the case for you just make the change now manually).

You might also change the background color of the menu constant (menu.bgCol) back to #007000.

More info on the Undo/History feature in TYPO3 is available here.

Creating another website in the database?

TYPO3 has the ability to create not just one website but any number of websites in the same database! This is a powerful capability called "multi site". The principle is that a new website can start from any page in the page tree and the way to indicate the starting page (root page) of a new site to TYPO3 is by inserting a template record!

If you thought that template records are a strange approach to creating templates then you should now see why they are a very efficient solution to this problem - because the template record becomes the control element you insert on a page to start new sites. Thus as soon as you need more than just one website in the page tree you need a concept like this to make it happen!

Now, let’s try it in practice:

Creating a new branch

First you create a new page under the current one, then add a few sub pages to it. This is going to be the start of a fan club website:

The "Fan club" is your new root page for this site. Try to view it:

Not looking good:

Why? Well the answer is in the principle I told you about before - we have not yet created a template record on the root page so TYPO3 knows that this is the root page! The easiest way to come about this is to fire up the Template module, select the "Info/Modify" view and use the wizard there:

Find a standard template you want as a basis of your new website:

Confirm the creation of the new template and go to the List module to verify the existence of the new template record:

Now the interesting moment comes - did this solve the problem? Hit the frontend again:

And yes it did! Of course the pages are empty since no content exists yet. And the template must be configured with the "Constant Editor" with other colors etc. That is the next step now.

It is probably not a surprise to you that the page id sent to the browser was "34" - the id of the page from the site. But which one of the two websites in the database will be displayed now if we do not send any id? The answer is the first one - the "FC Bigfeet" site.

Well, if that is the case how do people every get to visit our new site? Read on...

Controlling multiple domains

When you want to manage multiple websites inside your TYPO3 database you simply make sure they have a separate domain each. For instance the "FC Bigfeet" websites could have the domain "www.fc-bigfeet.com" and the fan club website could be "fanclub.fc-bigfeet.com" and also "www.fanclub.fc-bigfeet.com". The challenge now is to make sure that people get to see the right thing when going to the right domain!

This is a three step process:

  • Make sure that the DNS of all domains point to your webserver (trivial, non-TYPO3 related issue)

  • Configure your web server to direct all requests for the three domains to the directory with the TYPO3-website (.../quickstart/) - now a visit to any of the three domains will end on the "FC Bigfeet" main site.

  • Finally create a domain record for each domain you want to end up on the "Fan Club" website.

This is done by adding a new element to the root page "Fan Club":

Then enter the main domain name:

Save the record.

Create another one. This time for the alternative domain "www.fanclub.fc-bigfeet.com". Since this is basically a domain we use for "safety" we want it to redirect to the "fanclub.fc-bigfeet.com" domain. This is done like this:

Save it and view the page in the list module:

Nicely the two records are found in the List module display of the "Fan club" page elements. If you configured everything correctly a hit to "http://fanclub.fc-bigfeet.com" will show the new website and the "http://www.fc-bigfeet.com" URL will show the old one (default). Of course it didn't work - unless you hurried to register these domains lately!

Behind the scenes this is what happens: TYPO3 detects the domain name. Then it tries to look for a domain record. If such a one is found (like "fanclub.fc-bigfeet.com") then TYPO3 locks itself to that page as root page! This means that any request for page ids must be within the branch where the domain record was found! If a page id from the "FC Bigfeet" is requested on the domain "fanclub.fc-bigfeet.com" then TYPO3 will just show the front page of the "Fan Club" website!

Starting up new websites

Using the New template wizard

The feature "Create template for a new site" of the "Info/Modify" view is very practical for starting up new websites.

If you just click it without selecting a standard template you will still get a new template record - but without any standard template and with a few lines of dummy TypoScript content to get started. This is the way the pros are normally starting up new custom made sites and then they work from there with their knowledge of the TypoScript etc. This is precisely the process suggested in the tutorial "Modern Template Building, Part 1".

Framework for new projects?

When you want to start your own new websites you normally do it with a clean database. If you want that - a totally clean database with no pages, no content and only one "admin" user - then download the "Dummy" package from typo3.org. This is designed as start-up framework for new projects.

Since you are still a newbee with TYPO3 - or if you are just very lazy - you might also start up new projects with the  "QuickStart" package - the one we are using here! The reason is that it already contains a bunch of users, a template, some content already in place etc. You would just have to remove the template, make a new one, rearrange pages and add new content while removing the parts you don't need. This is probably a good idea if you need to get started quickly.

Template disclaimer!

Since the "template" is the crucial point of your implementation possibilities with a CMS it's very important to stress that this tutorial does not to any degree display the depth of possibilities with templates in TYPO3. On purpose I have used a very boring standard template which has a touch of amateur look over it. That is fully on purpose so we don't get lost in these issues. Remember, the point of this tutorial was to teach you principles of TYPO3. Those principles also apply for professional use of the product. But the implementation of templates will be much different.

So please notice: This tutorial was based on a fully functional website with a template already in place! You have not (in details at least) learned how to implement your own custom design. That is what all of the remaining tutorials is about (almost)  - so the "FC Bigfeet" site is only meant as an hands-on introduction - customizing templates is the big science not covered here!

Facts about templates and possibilities

Just to nail it to your mind for sure, this are some facts about templates in TYPO3:

  • You can implement any design you like, the way you like.

  • You can have any number of menu levels.

  • You can have multiple sites, multiple templates.

  • You can have pages in any number of languages.

  • You can have multiple content areas (columns) on a page.

  • You can integrate all kinds of external data sources through PHP written plugins.

  • You can add any number of web applications to run on various pages in TYPO3.

  • You can extend everything with PHP (with full backwards compatibility!).

  • You can do anything - some things are just more straightforward (most typical things), other things are more tricky (less typical things).

If you need a look at the feature list of TYPO3 you can find it here on typo3.com.

Develop professional websites with TYPO3?

The tutorial "Modern Template Building, Part 1" is the document to read if you want to get into the template building as it is recommended for newbees on a professional level. That document is a sequel to this one so after finishing this tutorial, just go on to that one!