Translations
Info
All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh

TemplaVoila/FTB1

From TYPO3Wiki
Jump to: navigation, search

<< Back to Administrators page

[edit]

This document is split up into two wiki pages, this one and Flexible Content Elements.

Extension Key: doc_tut_ftb1

Copyright 2004, Kasper Skårhøj & Robert Lemke, <kasper@typo3.com / rl@robertlemke.de>

This document is published under the Open Content License available from http://www.opencontent.org/openpub/

The content of this document is related to TYPO3 - a GNU/GPL CMS/Framework available from www.typo3.org

Contents

Introduction

What does it do?

This extension is a from-scratch tutorial about how to build a CMS-powered website with TYPO3 based on a HTML-template and the extension TemplaVoila (ext key: "templavoila").

It is based on the same basic material as the reknown "Modern Template Building, Part 1" but demonstrates the templating concepts taken to a new level compared to the Modern Template Building tutorial.

The document is recommended for developers on beginner level. However, before doing this tutorial you should have gone through "Getting Started" and "Modern Template Building, Part 1" in order to equip yourself with basic TYPO3 knowledge.

The website you will be guided to build will look like this:


tx_oodocs_83619c3cb3.png

Goal

The goal of the tutorial is to present to you a newly developed concept of templating revolving around the extension "templavoila" mixed with what is known as "FlexForms" and "Data Structures". Further it turns the traditional way of working with content elements around from being "columns"-centered to being totally hierarchically nested inside each other.

Whether this tutorial provides a best-practice implementation or not is not sure yet - that will depend on the general success and adoption of these techniques. But it is backed by high motivation from sponsors and personally we believe it holds great potentials.

The extension "TemplaVoila"

The extension "TemplaVoila" was developed by Kasper Skårhøj and Robert Lemke for a project in a large, french company, Dassault Systemes. TemplaVoila was the result of the innovation that followed some problem solving for the project. In particular the problems that TemplaVoila addresses are how to create more flexible page structures than currently known in TYPO3s concept of "columns". Further, it integrates traditional templating on the content element level but with a far more flexible point-n-click style than seen before. Finally the development of TemplaVoila also lead to some enhancements of the TYPO3 Core, in particular a concept called FlexForms which allows TYPO3s backend to build hierarchical forms and store their content into XML structures.

Dedication

<kasper> This time want to dedicate this document to my friends at Dassault Systemes in France. I want to thank you from my hearts deep for your generouscity, both personally and professionally, and I have loved to work with and for you all the time, both in Denmark and Paris. It has truely blessed my life on all levels and for TYPO3 your adoption has been a major reward and testimony to the quality it holds.</kasper>

The extension

This tutorial has all its files contained in a TYPO3 extension (doc_tut_ftb1). 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 of the tutorial "Modern Template Building, Part 1")
  • then import the extension "doc_tut_ftb1" 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. If you are lucky some merciful soul might have uploaded a PDF version for you as well... === WARNING - beta software Although TemplaVoila is used in production it is far from finished. The same goes for FlexForms - a core feature of TYPO3 3.6.0

You must be aware that what you are reading about in this document is all subject to change and we expect to revise this tutorial heavily upon the final release of the TemplaVoila extension. Please bear this in mind while you play with this!

Also notice that TYPO3 in version 3.6.0 is a requirement for this tutorial!


Spelling and such.

Under the "Dedication" section:

- "This time want to dedicate" - there's a double space there. Perhaps "This time I want to dedicate" or "At this time I'd like to dedicate" - generouscity = generosity Correct and delete this comment...  :)

Introduction

This chapter will demonstrate an implementation parallel to "Modern Template Building, Part 1" but with TemplaVoila instead of the "Auto-parse Template" extension. This will show you how powerful TemplaVoila is!

As an introduction to the principles we are following please read the chapter [extUid=442&tx_extrepmgm_pi1%5btocEl%5d=1273&cHash=e678dd49eb "Implementation of a CMS" in "Modern Template Building, Part 1"] first.

Installed the dummy-package and page-tree?

At first you have to make sure that you did install a blank TYPO3 database - basically the "dummy"-package is what you need. Further you should create a page tree structure as outlined in the [extUid=442&tx_extrepmgm_pi1%5btocEl%5d=1267&cHash=885ac047ea "The Basics"] chapter of "Modern Template Building, Part 1" (MTB/1). You don't need to follow the rest of "The Basics" section in MTB/1 - just create the page structure.

What you should see in the backend is a page tree like this:


tx_oodocs_940cbc4b41.png

The HTML template

The web team has just got a new customer - Main Dish & Son - and Raphael, the artist on the team, has produced the website template as a regular HTML file:


tx_oodocs_7272d89a03.png

This HTML file "template_page.html" is put into the directory "fileadmin/template/main/" relative to the TYPO3 installation (the dummy-package).

To follow this tutorial you should now copy the folder "template/" from this tutorial extension into the folder "fileadmin/". If you didn't import the tutorial extension "doc_tut_ftb1" from TER you should do that now!

tx_oodocs_7a48b043ee.png

Well, back to Raphaels work; the template HTML file is really just a regular HTML page. But when TYPO3 imports this file as a template the point is to make certain parts dynamic. This includes the menu to the left and also the section with dummy content to the middle/right.

Lets look at the source code of this file. In TYPO3 that is easy - just go the the File > Filelist module, click the title of the main/ folder and click the image in the list:


tx_oodocs_1d714a8093.png

This will open the file in a webbrowser.

Looking into the source code of the HTML template reveals a simple XHTML compliant document referring to a stylesheet and using a single table to position various elements on the page:


tx_oodocs_bbbef4b89d.png

Here follows some commentary on this HTML template and the challenges we are facing:

  1. This section from the header of the document must go into our webpage since it refers to the stylesheet used.
    Challenge: We must make sure to extract this part of the document into the header section generated by the frontend engine!
  2. The menu on the left is made by a
    -section per menu item. Each of these
    -elements has a class assigned to it. By this class name the design of the element is controlled in the CSS stylesheet.
    This is a very clever way to create a menu since each element consists of a minimum amount of HTML-code (good for TypoScript implementation), they are easily repeatable (necessary when the menu will be dynamic).
    Challenge: We must substitute the dummy-menu here with a dynamically generated one!
  3. This is dummy content that Raphael put into the template file just to get the visual impression right. Notice how it is formatted with <h1> and <p> tags (using the class "bodytext") - this is clever since the dynamic content inserted by TYPO3 later on will use those tags / classes for formatting as well! (Raphael must have cheated with some TYPO3 experience on beforehand, eh?)
    Challenge: We must substitute the dummy-content with dynamically generated page content.

Now the tutorial files are safely in place. Next step - installing the needed extensions.

Install "TemplaVoila" and "CSS Styled Content"

The next step is to install TemplaVoila which will be our template- and content rendering engine. Further we need "CSS Styled Content" which will render the regular content elements as for other normal TYPO3 websites.

If you didn't do it yet, import "TemplaVoila" from TER (TYPO3 Extension Repository) through the EM. When that is done, install the two extensions:


tx_oodocs_c3477f6286.png

For TemplaVoila you should make sure to enable the Page Template Selector in the update screen:


tx_oodocs_c3f6f8d10c.png

Press "Update" and all database tables and fields will automatically be created for you!

After you installed TemplaVoila, please reload the whole backend since the extension contains backend modules.

"css_styled_content"

Now, install CSS Styled Content extension:


tx_oodocs_6f1dbe1cfa.png

User annotations:

Date: 20-05-2004 15:37 by stephenwallis

css_styled_content now at version 0.0.10

Now that there is a newer version of css_styled_content do we need to upgrade? Or will it cause problems to get the new version?Date: 17-03-2004 19:17 by justinz

Error installing tempvoila

After i reload i get thie error "Fatal error: Call to undefined function: addllreffortcadescr() in /home/justin/public_html/quickstart/typo3conf/temp_CACHED_ps5720_ext_tables.php on line 1599"Date: 25-04-2004 17:03 by houmark

I also get an error....

The whole backend did go down, because of the missing function: addllreffortcadescr I located the the install file and comented out the line, reloaded the backend, went to TemplateVoila from the menu and then the following error came:

PHP Fatal error: Call to undefined function: includellfile() in /home/typo3testsite/typo3conf/ext/templavoila/mod2/index.php on line 42 I am to uninstall this module for now, as it seems to unstable. What a shame, as the method seems really clever...Date: 16-02-2004 12:37 by stephenwallis

Reload backed

I presume by "please reload the whole backend" you mean I should log out of the backend and log back in again. Maybe you could make this clearer in your documentation by having the following:


Code Listing:...please reload the whole backend (by logging out and back in again)...Date: 18-02-2004 18:22 by christianlangYou "reload the whole backend" by pressing the reload button of your webbrowser (instead of reloading only one frame).

The Storage Folder

Now you are about to create an important element for the website - the "Storage Folder". Normally you store elements related to a page on the page itself, eg. Content Elements or maybe even frontend users. However you will often find that for a website you need some general purpose page to place records which are related to the whole site and not just single pages - this is what we call a Storage Folder; A "SysFolder" page defined to be a general purpose storage page for elements related to a website in a branch of the page tree.

Steps involved in creating a SysFolder are these:

  • Create a page in the page tree of the type "SysFolder". You might want to place this page as the last page on the first level of the website branch.
  • Create a relation for "General Storage Folder" from the page header of the website root page to the new sysFolder page.

tx_oodocs_ac2dcf3576.png

Above screenshot shows the created storage folder. But to make it the storage folder of the website starting from "Root page" we need to edit the page header of "Root page":

tx_oodocs_a93a3dcc46.png

That's it.

Create the TypoScript Template Record

Next, we create a root template record on the "Root page" page. For details you can refer to "MTB/1" where this process is outlined in details. The point is that you end up with a "Template" record with this contents:


tx_oodocs_d6a699e835.png

tx_oodocs_c98a1dd511.png

The information you see in the "Setup" field is called "Template TypoScript" - it is configuration code that TYPO3s frontend engine (extension "cms") interprets in order to render the website pages. In the above case the text "HELLO WORLD" is outputted.

If you know about TypoScript in a historical perspective you know that a) the Setup field might end up being hundreds and hundreds of lines long, b) after a while slightly confusing to manage and c) requiring a lot of TypoScript knowledge, basically all of TSref.

If you know how we did in the MTB/1 tutorial you saw that the amount of TypoScript was not that frightening. In fact we just configured the extension "automaketemplate" to read an external HTML file and insert dynamic content at certain locations. That configuration was only like hundred lines or so (except menus). Far less than the "nightmares" of past times.

If you read on in this document you will see how we do not even add a single line - we just change the last two:


tx_oodocs_a7b086c971.png

So, all you initially need in order to use TemplaVoila in terms of TypoScript is a code listing like this:

# Default PAGE object:
page = PAGE
page.typeNum = 0
page.10 = USER
page.10.userFunc = tx_templavoila_pi1->main_page

(Admittedly, a little more will be added later since we also have to define the menu....)

Make sure to save this code listing. If you view the website now you should see a blank page with nothing in the body.

Now, the next step is to create a TemplaVoila Template Object for the page template.

Creating the Template Object for the page template

Go to the File > Filelist module, click the "template/main/" folder and then click the icon of the file "template_page.html":

tx_oodocs_3ca98e3a44.png

This will bring you to the mapping interface of TemplaVoila:


tx_oodocs_60832462a0.png

In this interface we will create a Data Structure (DS) for the page template and at the same time map that DS to the HTML elements of this template file and finally store the mapping information in a Template Object (TO) created along with the DS.

Data Structures (DS) and Template Objects (TO)

You can read more technical information about Data Structures in the document "TYPO3 Core API" and the documentation of "TemplaVoila". However, to give a quick distinction between DS and TO:

  • A Data Structure (DS) says which "fields" we can map to a HTML template.
  • A Template Object (TO) says which HTML elements the fields from the DS maps to.

By this definition we can see that a TO always refers to a DS which tells the TO which fields can be mapped and by which rules and hierarchies. It also means that you can have many TOs referring to the same DS - thus more templates for the same data!

Creating the Data Structure of "Main Dish & son"

In our tutorial the Data Structure needed for the page template is:

  • Definition of the overall element containing the page - that is obviously the <body> tag!
  • Menu: Define container element for the menu to the left
  • Content: Define container element for the content cell.

Such a DS could be manually created by hand if you know the syntax of the DS XML, <T3DataStructure>. However, the whole point of what we are doing just now is that TemplaVoila offers a visual point'n'click tool for automatic kickstarting such a Data Structure! It works like this:


Add an element representing the menu:

tx_oodocs_a84e311294.png

(The name "field_menu" is prefixed "field_" which is a best-practice convention. You can use other field names if you like.)

This gives you a form by which you can enter details for the new element:


tx_oodocs_b3d205ca3e.png

You can enter information like we have done above. Here are a few hints about options not so obvious. For details you should refer to the TemplaVoila documentation.

  • Mapping Type: Here you select the behavior of the element in terms of mapping to HTML. Select "Element"
  • Editing Type: This selects a preset for the field content. In our case we want to insert content from a TypoScript Object Path - which we will define to be the HMENU cObject later!
  • Mapping rules: Since the menu should probably be contained inside an HTML element like <div> or <td> etc. we define the rule "*:inner" which means that we can map the menu to be inside whatever element in the template.

After pressing "Add" you will see this:


tx_oodocs_ca9d45344c.png

You can repeat this process for the page content:


tx_oodocs_d17aae8dc4.png

In this case we selected the Editing Type preset to be "Content Elements" - this will give us the ability to insert content elements in this field later.

After pressing "Add" we now have a data structure reflecting what we wrote earlier - basically a menu and content cell:


tx_oodocs_12feb7daea.png

Mapping the DS to the HTML content

After having created the DS (which you could also have done on the fly when mapping if you liked that better) you have to map the elements in it to HTML elements in the template file.

Click "Map" for the "ROOT" element, then click the "<body>" tag icon in the "Mapping Window":

tx_oodocs_46eb837a36.png

This brings you a little form for the "ROOT" element where you can select mapping type:


tx_oodocs_16e9d7ecf5.png

For all "block-elements" (my name for HTML elements which has a beginning and an end, eg. <td>...</td> or
...
, contrary to eg. <img ....>) you can select INNER or OUTER mapping. This means whether we capture the content of the tag inside the tag (excluding the tag) or outside the tag (including the tag). Since we only want the contents of the <body> tag excluding the <body> tag we select "INNER".

tx_oodocs_354c831964.png

The result is this:


tx_oodocs_9915194f66.png

The DS listing now shows that the "ROOT" element has successfully been mapped to the <body> tag of the template! And since the "ROOT" element in the DS is parent element to the menu and content area elements we can now perform mapping of those DS elements as well.

Click the "Map" button for the "field_menu" element in the DS. Then click the "<td>" tag icon representing the <td> tag inside of which our dummy menu of the template was found:


tx_oodocs_68bf146d0d.png

Notice that we do not have other options that "INNER" this time:


tx_oodocs_0b3d3ebdcb.png

This is as expected because we made a rule that any element selected can only be mapped by the "INNER" mode - thus keeping the tag in the template and substituting only the contents with dynamic content.

So again, create an "INNER" mapping for the element:


tx_oodocs_c1c3e468ff.png

Now, do the final mapping of the "Page content" DS element:


tx_oodocs_7e3090caaf.png

Like with the other elements, just map it to "INNER" again.

You should see this result:


tx_oodocs_5c0dde1c77.png

You can always verify a mapping by clicking the "HTML-path" link. This will shown only the mapped portion of the template marked-up:


tx_oodocs_19be533d0e.png

Previewing the mapping

Since we entered a little sample data for our entries in the Data Structure we will be able to perform a simple preview of how a substitution in the template will look. Simply press the "Preview" button:


tx_oodocs_31da9f2ec1.png

This will render this "Mapping Window" for you:



Saving the DS and TO

Until now all you have done has been stored in the session data for your backend user profile. To complete the job you have just done you must click the "Save" button...

tx_oodocs_31351b58cf.png

... and then

  • Enter a title of the DS / TO (can be changed later)
  • Enter a type, in this case "Page template" (tells TYPO3 that this Data Structure is for a whole page). You should set this correctly now!
  • Select a Storage Folder to store it in - and you should only have one at this point in time.
    If you do not see a storage folder in the selector box you have a problem - you didn't configure the Storage Folder correctly according to the steps outlined earlier in this document!)

tx_oodocs_3c629f7e88.png

If everything went well you should see this acknowledgment:


tx_oodocs_9f9a427975.png

And in the "Storage Folder" page you will find the DS and TO records just created!

tx_oodocs_4a42d9081c.png

User annotations:

Date: 05-09-2004 10:42 by ries

To show the DS and TO records just created....

You should press 'LIST' and then the 'Storage Folder' to see what's actually IN the Storage Folder.Date: 06-06-2004 18:25 by palahala

Click "Map" and then "Cancel" after clicking "TemplaVoila"

In my 0.2.0 (on TYPO3 3.6.1) the "This will bring you to the mapping interface of TemplaVoila" will not present the screen as shown. To get a sneak preview that kind of resembles the above image (I just wanted to be sure my installation was allright) one needs to click the button "Map" as well. Note that the cursor will not change when moving over the little icons in that mapping preview (such as BODY or TD) but one can surely click such icon anyway. Next, choose Cancel to continue this very example... Enjoy, PalahalaDate: 22-02-2004 02:34 by wdelias

Incorrect spelling in "Create Data Structure / Template Object" Form label

Change "Titel of DS/TO" to "Title of DS/TO"

Applying the TO as page template

Let's summarize what we have done till now:

  • Template Files: Placed pre-made HTML files from a designer in "fileadmin/template/main/"
  • Extensions: Installed TemplaVoila and CSS Styled Content
  • Storage Folder: Configured a storage folder for the website.
  • TypoScript Template record: We created a simple TypoScript Template record in the root of the website - only containing a USER cObject triggering TemplaVoila.
  • Create DS/TO: Creating a Data Structure (DS) and Template Object (TO) for the main page template

All we need now is to select the newly created TO as the page template to be used. This is very easy. Just edit the page header of "Root page":

tx_oodocs_705996635e.png

This selects the DS for the page template - this is needed as a first step in order to tell TYPO3 which "features" the page will have (in this case two things; a menu and page content). Now, save the page header.

After that you will have to select the "Template Design" (the TO record):

tx_oodocs_e9ce2c5951.png

Then save - maybe even click "Save Document and View":

tx_oodocs_73c64e8dc3.png

... and as a reward you will see this:


tx_oodocs_d1f95a16e1.png

Yes, the template is used! But, reward? At least we are not at the end yet! What we miss is:

  • Setting up css_styled_content for content rendering
  • Adding page content
  • Creating the dynamic menu
  • Setting the stylesheet and body tag

User annotations:

Date: 10-05-2004 18:55 by nadine1978

Same problem, no drop down box.

I have the same problem as mentioned, unfortunatly I do not know how to fix it. Where can I enable the setting? NadineDate: 22-07-2004 00:57 by ganast

Step by step...

Go to "Ext Manager" > Drop down to "Loaded Extensions" > Choose "TemplaVoila" [text, not icon] > check "Enable Page Template Selector" > Click "Update" Re-Edit the page header and it should now have the menus.Date: 09-03-2004 10:04 by thalassja

No drop downs

Everything worked perfect. But at this point there are no drop downs to select the template structure, when I edit the page header of the root page. I installed everything as told in the tutorial. Could anybody help me?

Found it!!! I forgot the selector box to enable the page template selector. grrrrDate: 09-07-2004 12:49 by jitka

Same problem

There is no display too. I have checked the field Enable Page Template Selector [enable.pageTemplateSelector] and still nothing doesn't appear !!! Maybe there is some small mistake, I will describe, how I install. The first install was done without this checking, so then I found this field, checked and make update - nothing has done. So I uninstall the TemplaViola, reload, logout, login (I want be sure that I will start from begin with install templaviola). After installing it again, with checking, it was again wrong. And the TO/DO objects from the previous testings were still in the SysFolder!!!

Setting up css_styled_content for content rendering

Before content elements can be rendered we need a static TypoScript template to do that for us. This is known from all other implementations of TYPO3 so there is nothing new here; just edit the Template Record and add the "CSS Styled Content" static template file:


tx_oodocs_e26e6fb32f.png

Save and close.

Adding page content

One of the new things that comes with TemplaVoila is a totally new concept for integrating page content. Normally we use the concept of organizing content elements in columns on a page. Thus the content elements gets shown because they belong to a page and to a column.

In TemplaVoila content elements should still belong to the page they are shown on but the relation goes from the page (or higher level content element) to the content element inserted! This is the inverse direction of what you are used to, since normally content elements refer to their parent page and column! We'll add a little more details to this later. For now, just lean back and enjoy the new Page module:


WARNING: At this point the page module is under construction. Therefore screenshots are far from finished!

To create content a page page, just click the new icon:


tx_oodocs_af7e99e23c.png

This inserts a new content element. Edit that:


tx_oodocs_cadc48c4bf.png

Here we added some of the dummy text from the template file:


tx_oodocs_9ec11bb55d.png

Close, and you will see this:


tx_oodocs_260e1429d5.png

This is the way to add content to the page with TemplaVoila. You can insert more elements, you can copy/cut/paste them around, even make references to elements on other pages and you can also nest elements - this is shown later.

You can click the "View" icon to see the site now:


tx_oodocs_f0cbc977f3.png

Still not that pretty - we clearly miss the stylesheet. Well...

Behind-the-scenes of TemplaVoila's new Content Element management

This is for the interested developers; how does TemplaVoila manage the relations from pages to content elements?

Well, first of on a user level all that should be taken care solely by the new "Web > Page" module you have just used. But behind the scenes you can look into the page header and see that a new field has been added which allows you to add content elements to the page:


tx_oodocs_3aa613e88e.png

You can in fact modify the structure shown visually by the Web > Page module by adding relations to content elements manually with this form! But... that is not what you want to try and explain the average user!

FlexForm and the Data Structure behind

Another note on this is that the contents of this form is not going into a dedicated table cell - it is going into an XML structure in a database field of the page record (tx_templavoila_flex) which can potentially contain many more fields defined by the Page Template Data structure you have just created. This is one of the really thrilling and brilliant features of Data Structures. The concept is called "FlexForms" and this field is just one of those. Very beautiful stuff.

Basically the Data Structure we created along with the Template Object defines this. If you go to the "Storage Folder" page with the List module, click the DS records icon, in the context menu select "TemplaVoila" you will have a chance to see the XML of the DS:


tx_oodocs_eb950815e9.png

If you study this XML code you will find that for the field name "field_content" there is a section defining some "TCEforms" values - in fact this is what rendered the field with relations to the Content Elements:

<T3DataStructure>
   <ROOT>
           <tx_templavoila>
....
                   </field_menu>
                   <field_content>
....
                           <TCEforms>
                                   <config>
                                          <type>group</type>
                                          <internal_type>db</internal_type>
                                          <allowed>tt_content</allowed>
                                          <size>5</size>
                                          <maxitems>200</maxitems>
                                          <minitems>0</minitems>
                                          <show_thumbs>1</show_thumbs>
                                  </config>
                                  <label>Page content</label>
                          </TCEforms>
                  </field_content>
          </el>
  </ROOT>
</T3DataStructure>


Peaking into the value of the "tx_templavoila_flex" field of the page record also reveals an XML structure - <T3FlexForm>. It looks like this:

<?xml version="1.0" encoding="iso-8859-1" standalone="yes" ?>
<T3FlexForms>
   <meta>
          <currentSheetId>sDEF</currentSheetId>
  </meta>
  <data>
          <sDEF>
                  <lDEF>
                          <field_content>
                                  <vDEF>1</vDEF>
                          </field_content>
                  </lDEF>
          </sDEF>
  </data>
</T3FlexForms>

Notice the value between the <vDEF> tags - that is the uid of the content element "Buy PaperShredder(tm) Gizmo with 30-days money-... "

Rendering the content elements

One thing is to create the relations to the content elements. Another thing is how they are rendered. Apparently the good old static TypoScript templates like "CSS Styled Content" are still used - but how?

The answer is also in the Data Structure created. Look at these lines:

                   <field_content>
                          <tx_templavoila>
                                  <title>Page content</title>
                                  <description>Map this to the container element for page content</description>
                                  <sample_data>
                                          <n0>[Here goes my page content. Here goes my page content. Here goes my page content. Here goes my page content. Here goes my page content. Here goes my page content. Here goes my page content.] </n0>
                                  </sample_data>
                                  <eType>ce</eType>
                                  <TypoScript>
                                       10= RECORDS
                                       10.source.current=1
                                       10.tables = tt_content
                                  </TypoScript>
                          </tx_templavoila>
....

Those lines contains TypoScript code which looks quite as we have seen it before: It's a RECORD cObject, rendering elements from the "tt_content" table, taking the uids from the "current value" - which seems to be loaded with the content of <vDEF> tag in the scope where this TypoScript is used for processing (which is inside the "tx_templavoila_pi1" plugin as you might be able to figure out from previous code listing).

Want to know more:

FlexForms, Data Structures and all that is documented fully in the TYPO3 Core APIs document, section <T3DataStructure>.

User annotations:

Date: 28-09-2004 23:14 by ppuj

version 3.7.0 - change for menu

SORRY!! this was for the next page so clear that one and creat one on next pageDate: 29-06-2004 23:40 by charlie

Error: No user logged in

When I tried to add content, I got the error message: No user logged in/Browser accepts no cookies. I've used Typo 3.6.1, Template Voila 0.2.0 with Konqueror 3.1.4, now I use mozilla and it works !Date: 11-06-2004 21:56 by zjs2k

No page content shows!

Really don't know what's happening. I have TYPO3 3.6.1 and latest TemplaVoila. I used the leftover dummy site from "Modern Template Building" tutorials, but I removed all the templates and contents before starting this one. I checked all the XML codes listed on this page and nothing looks wrong, except no page content is shown. The css works, the menu shows up. Just the main page content isn't there. Checking the html source, all I got is . Any one else has similiar problem?Date: 25-08-2004 16:52 by ganast

Possible solution to blank screen

I too had this infuriating problem on my third TV site... didn't have the problem on the first two. As far as I can tell the problem originated from some TS that I think I copy/pasted from somewhere in the documentation... but cannot find now (?!) I used this:

(wrong) page.10.value = tx_templavoila_pi1->main_page instead of this:

(right) page.10.userFunc = tx_templavoila_pi1->main_pageDate: 24-08-2004 15:07 by magelan2k

Same experience

The same is true for me. I went through step by step the tutorial, but when I insert the example page content, nocontent is shown except the template. I tried another content type during mapping:

"plain input field": then the content was displayed. But this is not what was intended.

Creating the dynamic menu

The menu we want in the left table cell will be done with exactly the same TypoScript code as used for the MTB/1 tutorial. Nothing is different here; TypoScript turns out to be quite effective for configuring menus and image generation.

So, basically lets copy and paste the code listing from MTB/1 with one exception; "temp.menu_1" is changed to "lib.menu_1":

# Menu 1 cObject
lib.menu_1 = HMENU

# First level menu-object, textual
lib.menu_1.1 = TMENU
lib.menu_1.1 {
  # Normal state properties
NO.allWrap =
  NO.stdWrap.htmlSpecialChars = 1
  # Enable active state and set properties:
  ACT = 1
  ACT.stdWrap.htmlSpecialChars = 1
ACT.allWrap =
}

# Second level menu-object, textual
lib.menu_1.2 = TMENU
lib.menu_1.2 {
  # Normal state properties
NO.allWrap =
  NO.stdWrap.htmlSpecialChars = 1
  # Enable active state and set properties:
  ACT = 1
  ACT.stdWrap.htmlSpecialChars = 1
ACT.allWrap =
}

(Taken from the chapter "Adding XHTML compliancy")

Copy this listing into the Setup field of the Template Record:


tx_oodocs_db638c18f8.png

In MTB/1 we have to refer to or copy this definition of a HMENU object. In this case we need to do the same in principle - but the reference must be set in the Data Structure we just created! Here there will already be a dummy-pointer to "lib.myObject" - but we will change that!

So what you do is click the DS records icon, select "Edit":

tx_oodocs_a2821c3027.png

In the field "Data Structure XML" you will find the DS XML and for the element "<field_menu>" there is "application" configuration for TemplaVoila which contains a default reference to "lib.myObject" - this is the object path from the TypoScript Template record which will render the contents for this field. So just change this to "lib.menu_1" and you are set!

tx_oodocs_033a0bb264.png

You may look at the page again:


tx_oodocs_a36a1231f4.png

It hasn't become nicer but at least the menu is there!

User annotations:

Date: 28-09-2004 23:24 by ppuj

version 3.7.0 - change for menu

A) haven't exactly the same but in place of "field menu" >> find "field_be5c73" because ..at the step . "1.2.6 Creating the Template Object for the page template" i created "Add an element representing the menu:" whithout put any name in ... so script generated "field_be5c73" (The name "field_menu" is prefixed "field_" which is a best-practice convention. You can use other field names if you like.) OR neither .. 2) there is two places have to be changed .. right ? objPath>lib.menu_1 TypoScriptObjPath>lib.menu_1 And all goes

Code Listing:

<field_be5c73 type="array">
<tx_templavoila type="array">
<title>Main menu</title>
<description>Map element to Html element including Dummy menu</description>
<sample_data type="array">
<numIndex index="0">[le menu dynamique vient ici]</numIndex>
</sample_data>
<eType>TypoScriptObject</eType>
<tags>*:inner</tags>
<eType_EXTRA type="array">
<objPath>lib.menu_1</objPath>
</eType_EXTRA>
<TypoScriptObjPath>lib.menu_1</TypoScriptObjPath>
</tx_templavoila>
</field_be5c73>

Setting the stylesheet and <body> tag

The final step is to edit the Template Object which we were not able to do when we created the DS and TO; configuring inclusions from the header and <body> tag!

This is a walk in the park - just like most other things with TemplaVoila. Simply click the icon of the TO record, select "TemplaVoila":

tx_oodocs_f59bf84666.png

Then select the option "Select HTML header part":

tx_oodocs_825e88a2ec.png

Then you select to include the two stylesheet definitions and the body tag. We don't want the charset definitions since TYPO3 will automatically render that for us (which is the case with most <meta> tags). As a rule of thumb you should include all style, link and script sections you encounter here!

Finally, press save.

And if you dare - look at your website after clearing the cache:


tx_oodocs_b2b1d5ea35.png

tx_oodocs_491b99fcbc.png

And... Voila!

tx_oodocs_f05aea8113.png

For the curious souls you can also see how nicely this works by looking into the HTML source:


tx_oodocs_b50203ca51.png

This demonstrates how cleanly the selected header parts and the body tag from the template file has been included into the header which TYPO3 always has to control for purposes like automated charset, title tag value and JavaScript sections which might depend on such as dynamic menus etc.

Summary

Let's summarize the steps involved in this process, rearranging them in optimum order:

  • Template Files: Placed pre-made HTML files from a designer in "fileadmin/template/main/"
    You can ask an HTML designer to create basically any design he likes as long as it is valid HTML, nested correctly and generally clean (otherwise the mapper will have its problems).
  • Extensions: Installed TemplaVoila and CSS Styled Content
    No problem, GPL is here to serve us!
  • Storage Folder: Configured a storage folder for the website.
    Nice thing to have anyways - use it for your frontend users as well! This is recommended "best-practice".
  • TypoScript Template record: We created a simple TypoScript Template record in the root of the website;
  • Contained a basic call to a USER cObject triggering TemplaVoila's plugin "tx_templavoila_pi1"
  • Including the static template "CSS Styled Content"
  • Included a HMENU definition in object path "lib.menu_1"
  • Create DS/TO: Creating a Data Structure (DS) and Template Object (TO) for the main page template
  • First step: Create the DS and TO records
  • Second step: Include certain <head> parts and <body> tag.
  • Setting page template: Edited the header of the root page, setting the Page Template Data Structure and Template Object.
  • Added dummy page content: Created page content elements with TemplaVoilas "Web > Page" module - just for testing purpose.

Creating additional page templates

With the method shown in the previous section of this tutorial the next question is; how can we define more templates for alternative purposes?

This could include:

  • Templates for print-versions or other languages?
  • Templates for sub sections of the website?
  • Templates with 2 columns (other Data Structures)?

All these problems are easy to solve and they follow the same principles as used for the main template. Therefore in the coming chapters we will focus on what is different and assume that you can handle what has already been explained earlier without further introduction.

Modifying a formerly made DS/TO

The first step we want to take is to create a print-version template based on the HTML file "template_page_print.html". However it suddenly strikes us that the link "Back to normal version" (see buttom of file) has a counterpart in the main template, "Print version" - and we didn't map this field before! D'oh.

So, we have to take a little detour now since we would like to have that link mapped to a dynamic destination value of course.

In a situation like this what you want to do first and foremost is to modify the Data Structure to include the capability to map the href-attribute of a link. You have two options:

  • Modify the DS XML inside the DS record by hand. This is hard and requires knowledge of the Data Structure format, but can be done at any time you like regardless of other custom modifications.
  • Modify the DS by "re-creating" the DS/TO we made earlier. This is fun - but will remove all custom changes made to the DS XML - in our case the TypoScript Object path "lib.menu_1"!

We choose the fun option.

So, click the icon of the TO record, select TemplaVoila and then click the button "Modify DS / TO":

tx_oodocs_ed4087fb69.png

After clicking "Yes" to a warning box you will see this screen:


tx_oodocs_4cc31c9f73.png

Enter the fieldname (here "field_printVersionUrl") and press "Add". Then fill in the form. In particular set the Mapping Type to "Attribute" since we want to set a value in an HTML element attribute (<a href="...">), selecting Editing Type to "TypoScript Object Path" (we will have to dynamically set the link value) and if you like, you can set the Mapping rules to "a:attr:href" - meaning "map this DS element only to an "href" attribute of an <a>-tag!"

tx_oodocs_4171224ccc.png

Add the DS element and map it:


tx_oodocs_704bdf3f2f.png

The only choice is "ATTRIBUTE "href" (= #)" so you will select that:


tx_oodocs_342035e938.png

Then, press the "Set" button and in the next screen you will update the original DS/TO set:


tx_oodocs_39f6b941d7.png
This has saved the modified Data Structure and Template Object back. Now, there are two things to remember:

  • Any custom modifications to the DS XML will have to be redone most likely. (In our case that is the change of the TypoScript object path from "lib.myObject" to "lib.menu_1")
  • Any mappings of header parts or body tag in the TO will be lost. Redo them.
  • Any other Template Objects pointing to this DS might also have to have the new field mapped to the "Print version" link they might contain.

Fixing the DS XML and TO:

Edit the DS record and change in the XML the values for <TypoScriptObjPath>:

  • lib.myObject to lib.menu_1 (for <field_menu>)
  • lib.myObject to lib.print_url (for <field_printversionurl>)

tx_oodocs_b24a7d1637.png

After fixing the DS record, open the TO record with TemplaVoila and map the header parts and body tag again. See former chapter.

Then save - and maybe clear cache / preview that you site is still working...

Rendering the Print Version URL

In order to insert the URL to the Print Version all we have to do is to render it with a cObject in the TypoScript template, object path "lib.print_url":

#Print Version URL:
lib.print_url = TEXT
lib.print_url.value = index.php?id={page:uid}&print=1&no_cache=1
lib.print_url.htmlSpecialChars = 1
lib.print_url.insertData = 1
[globalVar = GP:print > 0]
lib.print_url.value = index.php?id={page:uid}
[global]

This code will insert a link pointing to the current page but with the "&print=1" parameter. Further, if the &print-parameter is set and a print template presumably is used the link will point back to the non-print page - thus working in the other direction as well!

User annotations:

Date: 28-09-2004 23:55 by ppuj

V3.7.0 - No change again for "lib.myObject" to "lib.menu_1")

Any custom modifications to the DS XML will have to be redone most likely. (In our case that is the change of the TypoScript object path from "lib.myObject" to "lib.menu_1") Despite i updated, i kept last change .. so only "field_printversionurl" "lib.myObject" occurence to change

A print version

For the print version of our website we have a template prepared from the designer. This is found in the file "template_page_print.html":

tx_oodocs_b8abf11701.png

This print template is supposed to be compatible with the main template, "template_page.html", although the menu field will not be mapped then. Therefore we will use the same DS as for the main template. This means we will not be creating a new DS and TO like previously done - only create a new TO pointing to the same DS but to a new file!

To complete the integration of a print version we have to

  • Create a TO record, pointing to the template file and DS needed. Set it as a child to the main template.
  • Map the TO record with TemplaVoila.

Create the TO

Create a new TO:


tx_oodocs_c12dabd282.png

Then enter the information for the TO:


tx_oodocs_7b4ce8a301.png

Please notice:

  • Make sure to make the template a sub-template of the main template! This means that this template in it self cannot be selected in TYPO3 at other places since it is a special version of another template and automatically selected for its purpose by TemplaVoila.
  • Set the file reference to the print version available.
  • Select the type of rendering to "Printer Friendly" - this will instruct TemplaVoila to use this TO record if the "&print=1" parameter is set and the main template will be used otherwise.

Then save and close.

tx_oodocs_007db57ed3.png

Now, click the icon of the new TO record again and select TemplaVoila:


tx_oodocs_7301f8eb77.png

Then you will see that the DS from the main template is indeed selected but no mapping information has been collected as of yet - obviously, since the TO is brand new and we are going to do the mapping now!

tx_oodocs_cb623cb152.png

Now, do the mapping, just like you did with the main template, just leave the "Main menu" element out. When you are done, press the "Preview" button - this will show you that the "Page content" sample data is inserted:


tx_oodocs_c13aada242.png

You can even click the "Back to normal version" link and a little JavaScript Alert will pop up!

Before you are done, enable "Select HTML header parts" and do your selection there:


tx_oodocs_5c797b57b5.png

Then press "Save".

You are done! When you click the link in the bottom of the frontpage you will see the print version right away!

tx_oodocs_67238e15ea.png

(If you don't see this, make sure that you didn't forget to paste in the TypoScript code in the previous chapter!)

User annotations:

Date: 06-10-2004 23:30 by vincnet

Printing with CSS

My annotation might be off topic, because this document handles how to deal with this very nice templating concept. However, hope I don't bother anyone, making a printable version of a page is easily done with CSS media types - which is a commonly forgotten feature. Put this in the link to the stylesheet.css (in the header): media="screen,print" In your stylesheet.css define the areas (div's for example) that are shown and not shown on the printed version and areas that are shown and not shown on the screen version. You can put specific mark up, for instance another font type and size, another width (important if your webpage is let's say 1000px or 100% wide), etc.

 @media print {
   #centre {
     width: 460px; /*fixed width for A4 paper*/
   }
   #claimer {
     border: solid black 2px;
     padding: 4px;
     width: 60%;
   }
   *#header_1, *#header_2, *#header_3, *#left, *#right    {
     display: none; /*not shown on the printed paper*/
   }
  }
 
 @media screen {
   #claimer {
     display: none; /*not shown on the screen*/
   }
 }

You can print by the button on the browser or by a print button somewhere on the page. More on a.o. http://www.w3schools.com/css/css_mediatypes.asp

Code Listing: Use CSS media types for printing mark up, if you like.

Alternative template for a sub section

In this example we want to create an alternative template for a sub section of the website:


tx_oodocs_5f550c843f.png

(This template is the file "template_page_xtra.html")

The section will be an extranet for customers and password protected as well - but that is not relevant here. All we want to know is - how can we enable TYPO3 to select an alternative template for a section of the website?

In this case it is very easy - it turns out that this template design can use the same Data Structure as the main template.

Create a new TO

Basically the steps are the same as for the print version template; create a new TO. But there are some different settings:


tx_oodocs_eaf8d19319.png

Notice:

  • The main Data Structure has been selected for the TO
  • This is not a sub-template of any other - thus it will be a fully valid alternative to the main template for pages!

Now, save and close. Then click the TO records icon and select "TemplaVoila". You should now begin mapping the elements:


tx_oodocs_f4c0408e75.png


When you are done the Data Structure listing should look like this:


tx_oodocs_0916b5ba1d.png

You can see that the "Print version link URL" has not been mapped - since there was no such link in the template file.

Remember to also select the appropriate header parts to include:


tx_oodocs_683b9dd661.png

... and Save.

Select the alternative templates for a sub section

You want to apply this template to all subpages of "Licensing" page - basically those marked here:


tx_oodocs_afbc9c9936.png

To do so, edit the page header of the "Licensing" page:


tx_oodocs_822877cf7e.png

In the page header, set "Subpages - Page Template Structure" to "Page - Main" (which it basically already is, inheriting from the root page, but...:-)

Then select the Template Design (TO record) labeled "Page - Extranet":

tx_oodocs_04ca2ac77a.png

Thats all!

tx_oodocs_4dcee54b3a.png

If you wanted to include the page "Licensing" in the section having the alternative template design you could have done so by setting the value of the "Page Template Selector" rather than "Subpages - Page Template Selector".

Dummy content on the page?

Well, maybe we were a little hasty. What about putting some content elements on the page to test?

See, in this case you cannot just copy/paste elements as you are used to. Remember, for TemplaVoila it is not enough to just copy a content element onto a page - you have to bring it into the hierarchy of references going from the page to the elements. But this is easily done. Just use the new Web > Page module that TemplaVoila provides:


With that module, go to the root page and click the "Reference" icon:


tx_oodocs_e8a62293de.png

Then go to the "License A" page and click the paste icon:


tx_oodocs_b9d3d49581.png

What you will see now is a reference created to the element on the root page - thus the two pages are sharing a content element! The reference is yellow because the content element is located externally from this page - namely on the root page!

tx_oodocs_204f788f6e.png

Testing the frontend again brings even better results:


tx_oodocs_a3e5c80243.png

Creating a two-column page?

What about that? Two columns on a page. Or even more. Or "zones". Or... you name it!

None of this is a problem for TemplaVoila - rather it is the very reason for its existence - the need for this kind of extreme flexibility.

In the case of a two-column layout there is a template file, "template_page_left_col.html", which contains an additional left column under the menu.

tx_oodocs_9eef929b5b.png

We are now going to create a new DS and TO after the same principles by which we made the main template:


tx_oodocs_d9faddab8e.png

Now, you do the mapping of the ROOT, Page content and Menu element just like with the main template. No changes.

During the mapping process we find that the old way of mapping to the menu is not possible anymore without wiping out the
tag which is surrounding the left column. The reason is that both the menu and the left column
sections are in the same <td> tag. This is illustrated in this screenshot.

tx_oodocs_49a310b9b1.png

We could now change the template HTML to yield a better structure for our mapping needs. In some cases that is needed. However, we can in fact map this anyways using a mapping mode known as "range". To map the menu you simply click the first
element and in the mapping mode selector you select the second-last
tag - thereby indicating that you want to grab all the
tags from the one you clicked and to the one selected.

tx_oodocs_07d157526d.png

For the left column
its just trivial mapping, no adventurous features to use there, sorry...

Result DS

The resulting DS looks like this:


tx_oodocs_05c2ab9046.png

In this case we were too lazy to add mapping instructions and mapping rules etc. However what was very important is the settings for the "Left content" field (field_left) and the "Page content" field (field_content). There are two major points:

  • "Page content" and "Left content" should both have the Editing type "Content elements". This is necessary if you want TemplaVoila to allow content into the cells!
  • You should use "field_content" for the "Page content" field name (while for the "new" column, "Left content" you can choose any you like). The reason is that you gain compatibility between this data structure and the main data structure if you use the same field name - otherwise reference information to content elements will be lost! Obviously.

Finally, you create the DS and TO:


tx_oodocs_9d557bb140.png

Before you are done with the DS / TO work you have to

  • Set which header parts to include for the TO
  • Modify the DS XML so "lib.menu_1" is referred to.

You can do that now.

Setting the new Page Template Structure

We want to apply the two-column design to this section of the website:


tx_oodocs_5b215ce167.png

Just like with the Extranet template we edit the page header of "Terms & Conditions". Notice how we have two possibilities for Page Template Structures:


tx_oodocs_5ac7b509eb.png

As soon as you select the Template Structure "Page - 2Col" and save you will see that the FlexForm field called "Content:" changed to include two content element fields!

tx_oodocs_3955dca43a.png

This shows a glimpse of what FlexForms can offer since the content of these two fields are stored in an XML data structure in a single database field rather than two separate - thus there are no limits to how many fields you can have in a form and how much nesting you can apply to them. Anyways, more about this later.

Before you exit the page header you must also select the template on the second pass:


tx_oodocs_9d91ebbefc.png

Adding dummy content again

Before we test our solution we will create a few references (or copies if you like) of the dummy content element on the frontpage. We notice how the Web > Page module has automatically reflected the reality of two content columns which is now the case for the section "Terms & Conditions" on the website:


tx_oodocs_a9e91a09e0.png

Now, we can preview:


tx_oodocs_f429086d3f.png

Precisely as it should be... :-)

User annotations:

Date: 29-09-2004 11:20 by ppuj

Setting the stylesheet and tag

Don't forget to specify CssStykesheet ... refer to : T3Doc/Futuristic Template Building section Setting_the_stylesheet

"filed_***" and compatibility between this data structure and the main data structure

As before, i didn't fill the field name, TYPO3 generate a name "field_be5c73" " So for me!!! reference information to content elements will be lost! as specified You should use "field_content" for the "Page content" field name . The reason is that you gain compatibility between this data structure and the main data structure if you use the same field name - otherwise reference information to content elements will be lost! Obviously.Date: 29-09-2004 10:56 by ppuj

Modify the DS XML so "lib.menu_1" is referred to

what i've done is to >> - in DS, Line "Menu ..." table after occurence was created 1) Click on "Change mode" and inside the label of reference 2) appears with "lib.myObject" and change it to "lib.menu_1" 3) save .. So no necessary to change Xml laterDate: 23-06-2004 16:31 by scheuer

Little change in Menu-item

>>Now, you do the mapping of the ROOT, Page content and Menu element just like with the main template. No changes. For me the Range selection didn't work until I removed the *:inner from the mapping rules. So.....almost no changes :-)

Icons for TOs and DSs

A really nice touch of DS and TO records is that you can attach icons to them which and used in the forms where people select them as templates/data structures.

Consider this example:


tx_oodocs_890e7f97db.png

This is the root page of the website we are working on here. All that is done to it is that the DS and TO records has got icons attached to them - which are in turn shown here.

By using icons for the Data Structure you can easily describe the abstract mode of a Data Structure; basically what possibilities there are. And for Template Object you can show people which designs are available for the selected Data Structures.

For both TO and DS record there are fields for the icons in their records. Just make sure to prepare the icons first; they are not automatically rescaled by the system:


tx_oodocs_c12b7f6dfa.png

User annotations:

Date: 29-09-2004 11:57 by ppuj

which one!!

1) Copy /typo3conf/ext/doc_tut_fb1/ds_to_icons Directory to /fileadmin/user_upload 2) StorageFolder/List choose to Edit TO & DS occurence - Pink image is to include in Data Structure EdiT - Image vignette is to include in Template Object EdiT Going to RootPage - EditPage, Y'll find results ..


Again and again ...

One said "Use div elements instead of tables". You said "Ah", kept the tables and used div elements for lists".


This document is devided into two parts. Go to the next page Flexible Content Elements >>