TYPO3 Templates
Create and modify templates with TypoScript and TemplaVoila
Build dynamic and powerful TYPO3 templates using TypoScript, TemplaVoila, and other core technologies.
Customize dynamic menus, logos, and headers using tricks you won’t find in the official documentation.
Build content elements and template extensions to overhaul and improve TYPO3’s default back-end editing experience.
Follow along with the step-by-step instructions to build a site from scratch using all the lessons in the book in a practical example.
Introducing flexible content elements
I just said flexible content elements are like mini-templates, but they are actually a little more sophisticated than that. TYPO3 templates, traditionally, are just used to design the pages of your website. Well, flexible content elements are there as a way to create our own specialized types of content elements. Flexible content elements give us most of the power that we've had in the main TemplaVoila templates; the workflow and structure is almost exactly the same. We still have a data structure and a mapped object for each template, and we can still create backend layouts and preview images to help our editors. So, we already have all the raw skills we need to start creating them, but we just need a few examples of where we would want them.
Creating a flexible content element really is just like creating a new content type for our sites utilizing the power of TemplaVoila. Once created, they can be embedded into any templates or even other FCEs. We can use references to link them across separate pages. We can copy them around between TYPO3 installations easily. We can even update the main template object or data structure of an FCE and watch our changes reach to every instance of that content element in our page tree. The best examples of this are going to be some of the ones we're about to build: a contact section, a div to wrap around other content elements, a multi-column element, and a custom product layout.
Creating our first flexible content element
The first FCE we're going to create is going to be simple enough to show us the basic workflow, but it's also a pretty handy trick so that we can add our contact information onto multiple pages using consistent formatting across our site. We're going to create a new flexible content element for our contact information using microformats (http://microformats.org/) so that Google and some browsers can read our address, phone number, and email address easier. Normally, this would require a lot of extra work to place it on multiple pages, but we can create an FCE that our editors can add to any page just like a normal content element.
Building the content element
Of course, the first thing that we should do is create an HTML file that we can use for our mapping. FCEs are normally mapped to a part of a complete HTML template, while page templates are mapped to the whole file. For our example, we will create one universal HTML file to hold all of our flexible content element HTML snippets called template_fce_snippets.html in the fileadmin/templates/ directory.
At this point, we can create our HTML that the FCE will be based on. Like we said before, we are going to use microformats so that our contact information can be read by software more easily. To use microformats, we are just going to add some specific class names to the span and div tags around our information. If you would like to see more information about microformats, I recommend going to http://microformats.org/. For now, we can add this code into our template_fce_snippets.html file:
<!DOCTYPE HTML>
<html>
<head>
<meta charset="utf-8" />
</head>
<body>
<div id="contact_info_section">
<h3 id="contact_info_title">Contact Us</h3>
<div class="vcard">
<div class="fn org">Example.com</div>
<div class="adr">
<div class="street-address">1214 Rebekah Ave.
</div>
<span class="locality">Dallas</span>,
<span class="region">TX</span>
<span class="postal-code">75154</span>
<span class="country-name">USA</span>
</div>
<div class="tel">(212) 555-1212</div>
<a class="email"
href="mailto:jeremy@example.com">jeremy@example.com</a>
</div>
</div>
</body>
</html>
We are ready to start creating the TemplaVoila structures now, so we can go to the TemplaVoila Control Center in the backend of our installation now. We can create a new data structure by going to the Template Files tab in the control center. To create a new template object and data structure simultaneously based on our new HTML file, we need to click on the Create... link for our template file, fileadmin/templates/template_fce_snippets.html.
Now we need to choose the root data element. Go ahead and choose the main div tag (circled in the following screenshot). We need to make sure we set the mapping mode to OUTER (Include tag). Due to an oddity in TemplaVoila, outer mapping is the only way to make sure that we actually keep the contact_info_section class after mapping. It may be counter-intuitive, but TemplaVoila treats root elements exactly the opposite of all other elements in its implementation of outer and inner mapping modes. Click on Set to start creating our data structure.
Now that we have set the root, we can add our own fields to the FCE data structure. All of our contact information can be static, so we will just create a field for the header. Like the page templates, we will create a new field by filling the in name, field_header, at the bottom of the page as shown in following screenshot, and click on Add.
Now we can fill in the form for our new field. We will set the Title to Header, and we can set the Sample Data as [Header goes here]. As we are using this as a header, we can choose Header field as our Element Preset. After we have filled out the form as shown in the following screenshot, we can click on Add to save our settings.
Map the header field to the h3 tag in our HTML template and click on Set to save the mapping.
We've finished creating our small content element, so we can click on the Save as button in our builder screen and save our progress. We are creating a new data structure, so we will need to fill out the CREATE Data Structure/ Template Object portion of the TemplaVoila save screen. We will give our new element an easy title, Contact Information. We also need to make sure we choose Content Element from the Template Type drop down because we are creating an FCE instead of a page template this time.
Our screen should look something like shown in the following screenshot before we click on the CREATE DS / TO button:
Testing our new content element
We can add our element to any page the same way we've been adding text or graphic elements in the past through the Page view.
Go to the main page in the backend of TYPO3 and click on the new element button (circled in the following screenshot).
Added to the choices of standard or extension-based elements, we can see our own flexible content element, Contact Information [Template], listed. Go ahead and choose it to add it to the page.
The next screen we see is the content editing screen where we can fill in the header for our new element:
Finally, we can save our new content element and see the output on the frontend (highlighted in the following screenshot):
Creating a flexible HTML wrapper
As a website grows, we sometimes run into times where we would like to assign a special style to a content element or group of content elements, but there is no easy way to do this in TYPO3 without creating a new page template. All we really want to do is wrap a div tag around the group of elements we are styling with a CSS class to give them any style we need from our own stylesheets. For example, we might want to highlight a group of content elements with a color background or border.
We will create a flexible content element to output a div tag with a blank class attribute that can contain normal page content elements. The FCE will have a field for the class, so our editors can fill in whatever class they need to use later.
We're also keeping control over the options that editors have. They are still restricted to using CSS classes, as opposed to arbitrary style attributes, so we have not given them too much freedom.
Building the content element
First, we can create our HTML to which the FCE will be mapped. All we need is a div tag with a blank class attribute, so we can just add our snippet to the bottom of /fileadmin/templates/template_fce_snippets.html. We will also add some HTML comments around our new snippet so that we can always identify it in the HTML file:
<!-- BEGIN HTML Wrapper -->
<div class=""></div>
<!-- END HTML Wrapper -->
Now, we go back to the TemplaVoila module in the backend. From the Template Files tab in the TemplaVoila Control Center, click on Create... next to the file fileadmin/templates/template_fce_snippets.html label.
Go ahead and choose our new div tag between the HTML comments (circled in the following screenshot) and click on Set to start creating our data structure.
Again, choose OUTER (Include tag) as our mapping mode.
The first field we need to create is the wrapper field for the content element. We have already set the div tag as the root element, but we still need to create a separate field to handle content elements or we won't be able to add content into our new FCE in the Page view. Like before, we can create a field by filling in the new field text area with a new name, field_wrapper, and clicking on the Add button. Now we can create the field with the following values just like we did when we added fields to our main templates. Like our page templates, we are going to use the Page-Content Elements preset because it allows us to place other content elements inside our new field:
Field: field_wrapper
Element
Title: Wrapper
Sample Data: [Content goes here]
Element Preset: Page-Content Elements
Once we have created and saved our new field, we can map it to the div tag by clicking on the Map button. We can use inner mapping this time because we want to keep the tag and this is not the ROOT field.
The next field we need to create is the class field so that we can edit the class from the page module. Instead of an element, we are creating an attribute. To create the new field, fill in the name, field_class, at the bottom of our page and click on Add. Choose Attribute from the drop down on the left side and fill out the field values:
Title: Class
Sample Data: [Class field]
Element Preset: Plain input field
After we have created the new class attribute and saved it, we can map it to the class attribute in our div tag. If we click on the Map button for the class field, we see that we can only choose the div tag to map to; this is okay. If the div tag is grayed out or disabled, we probably need to check that the root element was set with OUTER mapping. After we click on the div tag, we are presented with a slightly different mapping screen than we have seen before. Up until now, we have been mapping tags instead of attributes, so our choice has been INNER or OUTER mode. When mapping attributes, this drop down will show any blank attributes that exist within the HTML template for that tag. If we wanted to set a relation attribute, for example, the HTML just needs to have rel="" present in the tag with or without a value. For now, we can choose ATTRIBUTE "class" (= ) from the drop down and click on the Set button to continue.
We've created all of the fields we need for this small content element, so we can click on the Save as button to save our progress. We will give our new element an easy title, HTML Wrapper. We also need to make sure we choose Content Element from the Template Type drop down again.
Testing our new content element
We now have a data structure and template object created as a flexible content element and mapped, so we are ready to test. We can test with almost any class from our stylesheet, but we'll make it easy by adding a new class style to the bottom of our style.css file with a color background, rounded corners, and a slight shadow to highlight content:
.alert {
background-color: #BBCCDD;
padding: 10px;
-webkit-border-radius: 10px;
-moz-border-radius: 10px;
border-radius: 10px;
box-shadow: 2px 2px 5px #888;
-webkit-box-shadow: 2px 2px 5px #888;
-moz-box-shadow: 2px 2px 5px #888;
}
As an example, we can highlight a couple of bullet lists on the Bulletlist page that the TemplaVoila wizard created.
Go to the Bulletlist page in the backend of TYPO3 and choose to add a new element like we did for the Contact Information FCE.
This time, choose HTML Wrapper [Template] for our new element.
The next screen we see is the editing screen, and we can see that the titles we gave our data structure fields are showing up along with the different form elements we just declared. We can add elements to the wrapper here, but it's easier in the page module. Instead, we'll just set the Class field to alert to match our stylesheet, and save our new element.
Finally, in the page module, we can drag elements into our new content element, and our new div tag with a class we have set in the settings will wrap around them. We can drag two of our bullet lists into the FCE:
If we look at our edited page on the frontend, we can see the new CSS styling applied immediately:
Creating a multi-column layout element
As helpful as a wrapping div tag can be, we should start getting a little bigger with our goals. One thing that we run into all the time in the real world of site development is the need to have multi-column elements. With the rise of grid-based design and content-heavy sites, it's getting more popular to start adding two columns into the main content area under a single column article or something similar. Unfortunately, there are a lot of variations on this idea of mixing and nesting multi-column layouts, and it's not always possible or smart to create a template for every possible variation in a limited amount of time. You can easily waste all your time creating templates with a two-column element over a three-column element over a two-column element over a single-column element. I know that sounded confusing, and that's the problem. Instead, we can create a handful of useful multi-column flexible content elements that our editors can use anywhere they need to and in any order they need to. They can even nest them inside of each other if we do this right.
Right now, we're going to make a quick FCE with two columns that take up roughly half of the current content area. We're just going to start by adding some basic styling to our main stylesheet, fileadmin/templates/style.css:
.multi_column_element {
display: inline-block;
width: 100%;
}
#nested_column_1 {
float: left;
clear: left;
}
#nested_column_2 {
float: right;
clear: right;
}
.half {
width: 49%;
}
As you can see above, we are using inline-block as the display setting for the entire element. If we don't set that, then the elements below it can creep up when we start using floats. For more information on CSS values like inline-block, I recommend the tutorials from w3schools.com (http://www.w3schools.com/css/).
In addition, our style floats the first column, nested_column_1, to the left and clears anything to its left. The second column, nested_column_2, floats to the right and clears anything to the right of it. If we assign the class half to both columns, then they will both take up a little under 50% of the total width with a little whitespace in the middle.
After we've modified the CSS, we need to update our HTML file. Once again, we'll add our new HTML code with identifying comments into our HTML template, /fileadmin/templates/template_fce_snippets.html. Go ahead and add some basic code to the main FCE HTML file to create two divs for columns:
<!-- BEGIN 1/2 + 1/2 Element --><div class="multi_column_element">
<div class="nested_column half" id="nested_column_1">Column 1</div>
<div class="nested_column half" id="nested_column_2">Column 2</div>
</div>
<!-- END 1/2 + 1/2 Element -->
Now we're going to follow most of the same steps from the previous examples starting with the creation of a new data structure:
From the Template Files tab in the TemplaVoila Control Center, click on Create... next to the file fileadmin/templates/template_fce_snippets.html label.
Choose the main div tag that wraps around the entire HTML template as the root field. Again, we need to make sure we set the mapping mode to OUTER (Include tag).
Create a new field for the first column named field_column_1. As the float is set completely in CSS, we will not refer to the columns as left or right columns here. This means we could swap the columns in CSS or assign different identifiers in the HTML without breaking our data structure. Go ahead and create our new field with these values:
Field: field_column_1
Element
Title: Column 1
Sample Data: [Column #1 goes here]
Element Preset: Page-Content Elements
Save the first field and map field_column_1 to the div tag with the ID nested_column_1. Make sure that you select inner mapping so that the classes and identifiers are left in the div tag.
Create a new field for the second column with almost the same values as the first column:
Field: field_column_2
Element
Title: Column 2
Sample Data: [Column #2 goes here]
Element Preset: Page-Content Elements
Save the second column field and map it to the div tag with the ID nested_column_2 in the HTML.
Click on the Save as button to save our new data structure and template object. Set the title as something memorable, Two-Column Element, before choosing Content Element as the Template Type and clicking CREATE DS / TO.
As easy as that, we've just created another FCE. We can test this one on the main page of our test site by creating a new content element with our new FCE, Two-Column Element, and dragging our current blocks into either side:
With two even columns, our front page should look something like this:
Read more
United States
Great Britain
India
Germany
France
Canada
Russia
Spain
Brazil
Australia
Singapore
Canary Islands
Hungary
Ukraine
Luxembourg
Estonia
Lithuania
South Korea
Turkey
Switzerland
Colombia
Taiwan
Chile
Norway
Ecuador
Indonesia
New Zealand
Cyprus
Denmark
Finland
Poland
Malta
Czechia
Austria
Sweden
Italy
Egypt
Belgium
Portugal
Slovenia
Ireland
Romania
Greece
Argentina
Netherlands
Bulgaria
Latvia
South Africa
Malaysia
Japan
Slovakia
Philippines
Mexico
Thailand
