When you map an element from a Data Structure to a position in HTML it is expect that some dynamic content is inserted in that position at render time. There are various ways of determine the output:
By default the field content is inserted directly. Possibly configured with a few available flags like “htmlspecialchars()” processing, integer conversion or passing to stdWrap function (known from TypoScript)
Alternatively, you can enter a TypoScript content object array (COA) which will be executed. This can be used for building menus, graphics or just plain processing if you please. In this way you work with TypoScript in the context where it is used.
Alternatively, you can also call a TypoScript object path from the main TypoScript Template of your website. This means you keep your TypoScript at a central place.
Default pass-through of content
In this example the content of the field “field_paragraph” is processed only by htmlspecialchars() because the <HSC> tag is set in line 106:
98: <field_paragraph>
99: <tx_templavoila>
100: <title>Paragraph</title>
101: <sample_data>
102: <n0></n0>
103: </sample_data>
104: <eType>text</eType>
105: <proc>
106: <HSC>1</HSC>
107: </proc>
108: </tx_templavoila>
...
117: </field_paragraph>
The options for default processing in the <proc> tag applies to all content (even that coming from TypoScript or TypoScript Object path tags) outputted and the options are:
<int> (boolean) - Forcing to integer before output
<HSC> (boolean) - Passing through the PHP function “htmlspecialchars()” which will provide protection for use of HTML and XSS attacks.
<stdWrap> (array) - stdWrap processing
TypoScript object path
Image processing
You can also use the <TypoScript> tag to perform processing on the values.
Before writing TypoScript you will need to know that
The value of the tag in the context of that TypoScript is found as the “current value” in TypoScript.
The value of all tags in the Data Structure from the same level is found in the internal data array and can be addressed with the “.field” attribute of stdWrap
9: <field_image>
10: <tx_templavoila>
11: <title>Image</title>
12: <tags>img</tags>
13: <TypoScript>
14: 10 = IMAGE
15: 10.file.import = uploads/tx_templavoila/
16: 10.file.import.current = 1
17: 10.file.import.listNum = 0
18: 10.file.maxW = 266
19: </TypoScript>
20: </tx_templavoila>
... 35: </field_image>
In the example above you can see how the field “field_image” from the Data Structure is processed as if it contains an image. The TypoScript configures the path of the image (line 15), loads the “current” value (line 16) and selects the first image in the list (should there be more than one) (line 17) and finally the maximum width is set to 266 (line 18)
When you select “Editing Types” during the kickstarting process of DS/TOs this kind of default TypoScript configurations is what you get! You can always edit the Data Structure and change them to whatever you need them to do!
Graphical headers
Now comes a more complicated example. The code here combines two fields into one rendering of a graphical headline where the content of both fields will show up.
Lets look at the code listing:
36: <field_header>
37: <tx_templavoila>
38: <title>Header1</title>
39: <sample_data>
40: <n0>Lorem Ipsum Dolor</n0>
41: </sample_data>
42: <tags>img</tags>
43: <TypoScript_constants>
44: <textColor>black</textColor>
45: <text2Color>{$_CONSTANTS.colorSet.gray7}</text2Color> 46: <backColor>{$_CONSTANTS.colorSet.white}</backColor>47: </TypoScript_constants>
48: <TypoScript>
49: 10 = IMAGE
50: 10.file = GIFBUILDER
51: 10.file { 52: XY = 200,45
53: backColor = {$backColor}54:
55: 10 = TEXT
56: 10.text.current = 1
57: 10.text.case = upper
58: 10.fontColor = {$textColor} 59: 10.fontFile = {$TSconst.font_bold}60: 10.niceText = 1
61: 10.offset = {$textPosition}62: 10.fontSize = 20
63:
64: 20 = TEXT
65: 20.text.field = field_header2
66: 20.text.case = upper
67: 20.fontColor = {$text2Color} 68: 20.fontFile = {$TSconst.font_light}69: 20.niceText = 1
70: 20.offset = {$text2Position}71: 20.fontSize = 18
72: }
73: </TypoScript>
74: </tx_templavoila>
75: <TCEforms>
76: <config>
77: <type>input</type>
78: <size>48</size>
79: <eval>trim</eval>
80: </config>
81: <label>Header (colored)</label>
82: </TCEforms>
83: </field_header>
84: <field_header2>
85: <type>no_map</type>
86: <tx_templavoila>
87: <title>Header2</title>
88: </tx_templavoila>
89: <TCEforms>
90: <config>
91: <type>input</type>
92: <size>48</size>
93: <eval>trim</eval>
94: </config>
95: <label>Subheader (gray)</label>
96: </TCEforms>
97: </field_header2>
The two fields are “field_header” and “field_header2”.
Notice how the “<type>” of “field_header2” is set to “no_map” - this is done because this field in the Data Structure exists only for backend input to support the rendering of “field_header” which is mapped to the HTML template!
In line 55 and 64 a “TEXT” GIFBUILDER is created, one for each field.
In line 56 the “current value” is loaded for the first TEXT object - thus getting the value of “field_header”
In line 65 the value of the field “field_header2” is fetched by the “.field” attribute of TypoScript - we can do that because all values of the tags on the same level as “field_header” is found internally in cObj->data array
TypoScript Constants in Data Structures
In the above example you can also see how certain values in the TypoScript code comes from constants (lines 53, 58, 59, 61, 67, 68 and 70). This is as we know it from TypoScript Template records - but the constants are coming from the local scope of this TypoScript code! That means only the constants defined by the tags in line 44-46 can be used! That means {$textColor}, {$text2Color}, {$backColor}
Constants in Constants
In line 43-47 you can also see that some of these constants are referring back to other values, for example “{$_CONSTANTS.colorSet.white}” - these values are object paths pointing to the TypoScript Template Setup field (not the Constants field!)
In this case those value would be found in the TypoScript Object Tree at these positions:
These values are set by first setting this in the Constants field of the TypoScript Template record:
# Define color sets:
colorSet.gray1 = #B4B3B3
colorSet.gray2 = #333333
colorSet.gray3 = #eeeeee
colorSet.gray4 = #F7F7F7
colorSet.gray5 = #555555
colorSet.gray6 = #444444
colorSet.gray7 = #828282
colorSet.red = #E80C0E
colorSet.orange = #FF7200
colorSet.TO1 = #BA3957
colorSet.TO2 = #217EA1
colorSet.TO3 = #849724
colorSet.TO4 = #608375
colorSet.TO5 = #7469A4
colorSet.TO6 = #96AA00
colorSet.white = #FFFFFF
# Define font sets:
font.light = EXT:user_3dsplm/fonts/FRANGWC_.TTF
font.medium = EXT:user_3dsplm/fonts/FRANGMC_.TTF
font.bold = EXT:user_3dsplm/fonts/FRANGDC_.TTF
Then in the Setup field of the Template Record you will find these lines:
# Moving constants into the Setup scope (for use from PHP scripts and Template Objects)
_CONSTANTS.colorSet { gray1 = {$colorSet.gray1} gray2 = {$colorSet.gray2} gray3 = {$colorSet.gray3} gray4 = {$colorSet.gray4} gray5 = {$colorSet.gray5} gray6 = {$colorSet.gray6} gray7 = {$colorSet.gray7} red = {$colorSet.red} orange = {$colorSet.orange} TO1 = {$colorSet.TO1} TO2 = {$colorSet.TO2} TO3 = {$colorSet.TO3} TO4 = {$colorSet.TO4} TO5 = {$colorSet.TO5} TO6 = {$colorSet.TO6} white = {$colorSet.white}}
_CONSTANTS.font { light = {$font.light} medium = {$font.medium} bold = {$font.bold}}
Constants directly from the Setup field
Finally in line 59 and 68 the constant has a special prefix, “TSconst.” and when that is found the constant is a reference to the object path “plugin.tx_templavoila_pi1.[constant]”, thus in this case “plugin.tx_templavoila_pi1.TSconst.font_bold”
These values were also set from constants in the TypoScript Template record (see above):
plugin.tx_templavoila_pi1.TSconst { font_light = {$font.light} font_medium = {$font.medium} font_bold = {$font.bold} color_red = {$colorSet.red} color_white = {$colorSet.white} color_gray4 = {$colorSet.gray4}}
These options might seem a bit confusing but the implementation is like this for performance reasons. You will most likely think that the logic is to set object paths from the TypoScript Constants field, not the Setup field. However this is not possible at render-time since constants are substituted in TypoScript at parse time (and that result is cached).
Therefore if you want to channel TypoScript Constants into your Data Structures you should set the constants in object paths (like “_CONSTANTS.colorSet.white”) from where you can insert them into the constants defined in <TypoScript_constants>
Overriding values from Template Objects
Mainly, processing instructions of all kinds are stored in the Data Structures. However if can be necessary to override some of these values from the Template Objects. That is easily done by setting alternative values for the tags inside the <tx_templavoila> tag of a Data Structure using the “Local Processing (XML)” field of Template Objects:
The XML content looks like this in color markup:
1: <T3DataStructure>
2: <ROOT>
3: <el>
4: <field_header>
5: <tx_templavoila>
6: <TypoScript_constants>
7: <textXY>266,50</textXY>
8: <textColor>{$_CONSTANTS.colorSet.TO3}</textColor>9: <textPosition>0,21</textPosition>
10: <text2Position>0,42</text2Position>
11: </TypoScript_constants>
12: <TypoScript>
13: 10 = IMAGE
14: 10.file = GIFBUILDER
15: 10.file { 16: XY = {$textXY} 17: backColor = {$backColor}18:
19: 10 = TEXT
20: 10.text.current = 1
21: 10.text.case = upper
22: 10.fontColor = {$textColor}23: 10.fontFile = EXT:user_3dsplm/fonts/FRANGDC_.TTF
24: 10.niceText = 1
25: 10.offset = {$textPosition}26: 10.fontSize = 18
27:
28: 20 = TEXT
29: 20.text.field = field_header2
30: 20.text.case = upper
31: 20.fontColor = {$text2Color}32: 20.fontFile = EXT:user_3dsplm/fonts/FRANGWC_.TTF
33: 20.niceText = 1
34: 20.offset = {$text2Position}35: 20.fontSize = 18
36: }
37: </TypoScript>
38: </tx_templavoila>
39: </field_header>
40: </el>
41: </ROOT>
42: </T3DataStructure>
Notice that all values overriding the Data Structure is at the exact same location of the XML structure as they are in the Data Structure XML!
In this example lines 7- 10 overrides the constants with other colors.
Further the TypoScript is even changed (although that is usually not needed if you use constants correctly) in lines 13 - 36
Loading and restoring TypoScript register values
Assume that you are creating a page template with two areas of content of differing width. Normally you set one global setting for the maximum image width in the Constants setup of your templates:
styles.content.imgtext.maxW = 600
styles.content.imgtext.maxWInText = 300
However, you want to override this value when content is rendered inside the smaller of the two columns (since that was designed for secondary content.
This is easily done by a small modification to the field in the Data Structure which renders the content elements inside:
13: <field_ce_right>
14: <tx_templavoila>
15: <title>Right Column</title>
...
20: <TypoScript>
21:
22: 5 = LOAD_REGISTER
23: 5.maxImageWidthInText = 100
24: 5.maxImageWidth = 180
25:
26: 10= RECORDS
27: 10.source.current=1
28: 10.tables = tt_content
29:
30: 15 = RESTORE_REGISTER
31:
32: </TypoScript>
33: </tx_templavoila>
...
46: </field_ce_right>
In this example line 26-28 is what you normally find as preset TypoScript rendering when you select the Editing Type “Content Elements”. Line 22-24 on the other hand is manually inserted and will load the internal registers with values that will override the settings from the Constants while rendering content inside this column. Line 30 makes sure to restore the old state again.
Using CDATA
When editing TypoScript in Data Structures you might quickly find it very useful to wrap the content in CDATA tags to avoid parsing of the content. This is true especially when you enter HTML codes for wrapping etc.
Using the CDATA tags looks like this (line 13 and 17):
12: <TypoScript>
13: <![CDATA[
14: 10 = TEXT
15: 10.current = 1
16: 10.wrap = <b> | </b>
17: ]]>
18: </TypoScript>
The alternative looks like this (using the HTML entities < and > for < and >):
12: <TypoScript>
13: 10 = TEXT
14: 10.current = 1
15: 10.wrap = >b< | >/b<
16: </TypoScript>
The mapping from TemplaVoila is designed to work without anything but pure HTML. However if you rearrange elements in the HTML source and wants to do a re-mapping you might find that everything fails. Therefore it is a good idea to “tag” cornerstone elements with an “id” attribute or class attribute. These are a part of the “HTML-path” which is used to identify an element in a template. And if you use ids at strategically good places (like the wrapping <div> elements in the template_ce.html) you will come a long way.
Cached templates
Also notice; if a template file changes or even is deleted, the Template Objects will still work since they cache a parsed version of the mapped template in the moment you save them! Therefore they are very robust and only missing images, stylesheets etc. used by the templates will break.
Other features than mandatory caching will come later.
