TemplaVoila/FTB1
From TYPO3Wiki
<< Back to Administrators page
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/opl.shtml
The content of this document is related to TYPO3 - a GNU/GPL CMS/Framework available from www.typo3.com
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:
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:
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:
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!
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:
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:
Here follows some commentary on this HTML template and the challenges we are facing:
- 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! - 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!- 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.
[edit]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:
For TemplaVoila you should make sure to enable the Page Template Selector in the update screen:
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.
[edit]"css_styled_content"
Now, install CSS Styled Content extension:
[edit]User annotations:
Date: 20-05-2004 15:37 by stephenwallis
[edit]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
[edit]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
[edit]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
[edit]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).[edit]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.
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":
That's it.
[edit]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:
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:
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.
[edit]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":
This will bring you to the mapping interface of TemplaVoila:
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.
[edit]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!
[edit]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:
(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:
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:
You can repeat this process for the page content:
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:
[edit]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":
This brings you a little form for the "ROOT" element where you can select mapping type:
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".
The result is this:
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:
Notice that we do not have other options that "INNER" this time:
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:
Now, do the final mapping of the "Page content" DS element:
Like with the other elements, just map it to "INNER" again.
You should see this result:
You can always verify a mapping by clicking the "HTML-path" link. This will shown only the mapped portion of the template marked-up:
[edit]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:
This will render this "Mapping Window" for you:
[edit]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...
... 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!)
If everything went well you should see this acknowledgment:
And in the "Storage Folder" page you will find the DS and TO records just created!
[edit]User annotations:
Date: 05-09-2004 10:42 by ries
[edit]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
[edit]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
[edit]Incorrect spelling in "Create Data Structure / Template Object" Form label
Change "Titel of DS/TO" to "Title of DS/TO"
[edit]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":
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):
Then save - maybe even click "Save Document and View":
... and as a reward you will see this:
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
[edit]User annotations:
Date: 10-05-2004 18:55 by nadine1978
[edit]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
[edit]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
[edit]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
[edit]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!!!
[edit]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:
Save and close.
[edit]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:
This inserts a new content element. Edit that:
Here we added some of the dummy text from the template file:
Close, and you will see this:
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:
Still not that pretty - we clearly miss the stylesheet. Well...
[edit]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:
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:
If you study this XML code you will find that for the field name "field_content" there is a section defining some "TCEforms" values (lines 35-46) - in fact this is what rendered the field with relations to the Content Elements:
1: <T3DataStructure> 2: <ROOT> 3: <tx_templavoila> .... 20: </field_menu> 21: <field_content> .... 35: <TCEforms> 36: <config> 37: <type>group</type> 38: <internal_type>db</internal_type> 39: <allowed>tt_content</allowed> 40: <size>5</size> 41: <maxitems>200</maxitems> 42: <minitems>0</minitems> 43: <show_thumbs>1</show_thumbs> 44: </config> 45: <label>Page content</label> 46: </TCEforms> 47: </field_content> 48: </el> 49: </ROOT> 50: </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:
1: <?xml version="1.0" encoding="iso-8859-1" standalone="yes" ?> 2: <T3FlexForms> 3: <meta> 4: <currentSheetId>sDEF</currentSheetId> 5: </meta> 6: <data> 7: <sDEF> 8: <lDEF> 9: <field_content> 10: <vDEF>1</vDEF> 11: </field_content> 12: </lDEF> 13: </sDEF> 14: </data> 15: </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 the lines 29-33 (gray background):
.... 21: <field_content> 22: <tx_templavoila> 23: <title>Page content</title> 24: <description>Map this to the container element for page content</description> 25: <sample_data> 26: <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> 27: </sample_data> 28: <eType>ce</eType> 29: <TypoScript></font> 30: 10= RECORDS</font> 31: 10.source.current=1</font> 32: 10.tables = tt_content</font> 33: </TypoScript></font> 34: </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>.
[edit]User annotations:
Date: 28-09-2004 23:14 by ppuj
[edit]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
[edit]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
[edit]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
[edit]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
[edit]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.
[edit]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 = <div class="menu1-level1-no"> | </div> NO.stdWrap.htmlSpecialChars = 1 # Enable active state and set properties: ACT = 1 ACT.stdWrap.htmlSpecialChars = 1 ACT.allWrap = <div class="menu1-level1-act"> | </div> } # Second level menu-object, textual lib.menu_1.2 = TMENU lib.menu_1.2 { # Normal state properties NO.allWrap = <div class="menu1-level2-no"> | </div> NO.stdWrap.htmlSpecialChars = 1 # Enable active state and set properties: ACT = 1 ACT.stdWrap.htmlSpecialChars = 1 ACT.allWrap = <div class="menu1-level2-act"> | </div> }(Taken from the chapter "Adding XHTML compliancy")
Copy this listing into the Setup field of the Template Record:
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":
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!
You may look at the page again:
It hasn't become nicer but at least the menu is there!
[edit]User annotations:
Date: 28-09-2004 23:24 by ppuj
[edit]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>
[edit]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":
Then select the option "Select HTML header part":
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:
And... Voila!
For the curious souls you can also see how nicely this works by looking into the HTML source:
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.
[edit]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.
[edit]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.
[edit]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":
After clicking "Yes" to a warning box you will see this screen:
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!"
Add the DS element and map it:
The only choice is "ATTRIBUTE "href" (= #)" so you will select that:
Then, press the "Set" button and in the next screen you will update the original DS/TO set:
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.
[edit]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>)
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...
[edit]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]</font> lib.print_url.value = index.php?id={page:uid} [global]</font>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!
[edit]User annotations:
Date: 28-09-2004 23:55 by ppuj
[edit]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
[edit]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":
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.
[edit]Create the TO
Create a new TO:
Then enter the information for the TO:
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.
Now, click the icon of the new TO record again and select TemplaVoila:
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!
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:
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:
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!
(If you don't see this, make sure that you didn't forget to paste in the TypoScript code in the previous chapter!)
[edit]User annotations:
Date: 06-10-2004 23:30 by vincnet
[edit]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.
[edit]Alternative template for a sub section
In this example we want to create an alternative template for a sub section of the website:
(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.
[edit]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:
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:
When you are done the Data Structure listing should look like this:
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:
... and Save.
[edit]Select the alternative templates for a sub section
You want to apply this template to all subpages of "Licensing" page - basically those marked here:
To do so, edit the page header of the "Licensing" page:
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":
Thats all!
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".
[edit]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:
Then go to the "License A" page and click the paste icon:
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!
Testing the frontend again brings even better results:
[edit]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.
We are now going to create a new DS and TO after the same principles by which we made the main template:
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 thetag which is surrounding the left column. The reason is that both the menu and the left columnsections are in the same <td> tag. This is illustrated in this screenshot.
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-lasttag - thereby indicating that you want to grab all thetags from the one you clicked and to the one selected.
For the left column
its just trivial mapping, no adventurous features to use there, sorry...[edit]Result DS
The resulting DS looks like this:
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:
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.
[edit]Setting the new Page Template Structure
We want to apply the two-column design to this section of the website:
Just like with the Extranet template we edit the page header of "Terms & Conditions". Notice how we have two possibilities for Page Template Structures:
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!
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:
[edit]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:
Now, we can preview:
Precisely as it should be... :-)
[edit]User annotations:
Date: 29-09-2004 11:20 by ppuj
[edit]Setting the stylesheet and tag
Don't forget to specify CssStykesheet ... refer to : T3Doc/Futuristic Template Building section Setting_the_stylesheet
[edit]"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
[edit]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
[edit]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 :-)
[edit]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:
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:
[edit]User annotations:
Date: 29-09-2004 11:57 by ppuj
[edit]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 ..
[edit]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 >>
- 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?)
