DEPRECATION WARNING

This documentation is not using the current rendering mechanism and will be deleted by December 31st, 2020. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

Introduction

TemplaVoilà! Plus extends the Data Structure XML with a set of tags which defines two things related to TemplaVoilà! Plus:

  • Mapping: Definition of mapping rules, descriptions, sample data, and field type preset
  • Rendering: Definition of TypoScript code, Object Path, processing flags and constants

<T3DataStructure> extensions for “<tx_templavoilaplus>”

Array” Elements:

Element

Element

Description

Description

Sub-elements

Sub-elements

Element

<[application tag]>

Description

In this case the application tag is “<tx_templavoilaplus>”

Sub-elements

<title>

<description>

<tags>

<sample_data>

<sample_order>

<eType>

<TypoScriptObjPath>

<TypoScript>

<proc>

<ruleConstants>

<ruleRegEx>

<ruleDefaultElements>

<langOverlayMode>

<preview>

Element

<ROOT><tx_templavoilaplus>

Description

For <ROOT> elements in the DS

Sub-elements

<title>

<description>

<pageModule>

Element

<pageModule>

Description

A bunch of config options which take influence on the rendering in the page module.

Sub-elements

<displayHeaderFields>

<titleBarColor>

Element

<sample_data>

Description

Sample data, defined in numeric array. Sample data is selected randomly from these options

Sub-elements

<n[0-x]>

Element

<sample_order>

Description

For <section>s: Defines a set of array objects to display as sample data. Each value in this numerical array points to a fieldname in the object <el> array.

Sub-elements

<n[0-x]>

Element

<TypoScript_constants>

Description

Sub-elements

<[constant_name]>

Element

<proc>

Description

Processing options (during rendering)

Sub-elements

<stdWrap>

<int>

<HSC>

Value” Elements:

Element

Element

Format

Format

Description

Description

Element

<meta><sheetSelector>

Format

string

Description

Defining a file/class with PHP code to evaluation sheet selection in frontend.

Its a getUserObject reference a la “EXT:user_myext/class.user_myext_selectsheet.php:&amp;user_myext_selectsheet” where the class user_myext_selectsheet contains a function, selectSheet(), which returns the sheet key, eg. “sDEF” for default sheet.

Notice about using sheets in frontend rendering (pi1):

This feature is fairly advanced and still needs some development and documentation. Here are some points to observe:

  • When sheets are defined the template also needs to be remapped!
  • If no mapping exists for other keys than “sDEF” then they will default to use the mapping for “sDEF”. Thus it can save you a little on mapping the same over and over again if all sheets use the same template.
  • When using sheets the local processing XML also needs to be wrapped in eg. “<sheet><sDEF> …. </sheet></sDEF>”
  • The selection of sheets should be careful to select only based on parameters that are safely cached. This can be done if parameters are known to be cHash protected - or if the page cache is disabled of course.

Element

<meta><disableDataPreview>

Format

boolean 0/1

Description

If configured the datapreview within the page-module for the element is turned off.

Element

<meta><noEditOnCreation>

Format

boolean 0/1

Description

If configured the editing form, which would usually show up after a new content element was created, is skipped. This can be used for elements which server the purpose of a container.

This setting can be overwritten with local processing setup.

Element

<meta><default><TCEForms>

Format

Description

Can be used to define default-values for the parent-record.

Example (mostly used for container elements):

<meta type=”array”>

<langDisable>1</langDisable>

<default>

<TCEForms>

<sys_language_uid>-1</sys_language_uid>

</TCEForms>

</default>

</meta>

Element

<title>

Format

string

Description

The title displayed in the mapping view

Element

<description>

Format

string

Description

Mapping instructions / description, shown in mapping view.

Element

<tags>

Format

string

Description

commalist of tag rules. A tag rule is defined as [tagname]:[mapping- mode]:[attribute]

Examples are:

  • table:outer,div,body:inner,td:inner
  • *:attr:href
  • a:attr:*
  • *:inner,a:attr:href,a:attr:src

Element

<eType>

Format

string

Description

Value pointing to a TCEforms preset. Used for building of Data Structures with TemplaVoilà Plus. Automatically set and controlled. This tag only used internally by the mapping tool.

Element

<oldStyleColumnNumber>

Format

integer

Description

@TODO This part seams out of date By setting this tag to an integer value (usually between 0 and 3), you define to which tt_content column number this field relates. This information is used by the list module, frontend editing and all other places which work with the older column paradigm.

If you want to convert a pre-TemplaVoila site to a TemplaVoila site with the migration wizard you also have to make sure setting oldStyleColumnNumber tags for your content areas.

Note: Each value can only be used once in a data structure and this usage makes only sense in page templates!

Note: By default this setting is also used for content areas within flexible content elements. The elements which are nested within these flexible content element will use their parent’s setting. If you want to avoid this, just remove the setting from the flexible content element.

Background information:

Before TemplaVoila existed, the content on a page was arranged by assigning each content element to a certain column id. By default four columns were available: “Normal” (id=0), “Left” (id=1), “Right” (id=2) and “Border” (id=3).

Some parts of TYPO3 and some extensions are not aware of the different way TemplaVoila structures content. If you create or move a content element with the List module, the element possibly does not appear at the position where you expect it, because the list module doesn’t know which content area reflects the “Normal” column.

Example:

<T3DataStructure>
   <ROOT>
      <el>
         <field_maincontent>
            <tx_templavoilaplus>
               <oldStyleColumnNumber>0</oldStyleColumnNumber>
...

Element

<TypoScriptObjPath>

Format

string

Description

TypoScript object path pointing to a TypoScript Template Content Object which will render the content represented by the element.

Very useful if you want to insert a menu which is defined by eg. “lib.myMenu” in the TypoScript Template of a website.

Element

<TypoScript>

Format

string

Description

TypoScript content.

Constants can be inserted

  • which are defined locally in <TypoScript_constants>, see below
  • In the TypoScript template of the website; In the Setup field you can set constants as properties (first level only) in “plugin.tx_templavoilaplus_pi1.TSconst” - those can be inserted by {$TSconst.[constant name]} in the <TypoScript> data!

General example:

<TypoScript>
<![CDATA[

10 = USER
10.userFunc = user_3dsplm_pi2->testtest
10.imageConfig {
  file.import.current = 1
  file.width = 100
}

]]>
</TypoScript>

Access other fields in the same data structure:

<TypoScript>
   10 = TEXT
   10.field = field_myotherfield
</TypoScript>

Display the page title:

<TypoScript>
   10 = TEXT
   10.data = page:title
</TypoScript>

Element

<[constant_name]>

Format

string

Description

A local TypoScript constant which can be inserted by {$[constant_name]} in <TypoScript> (see above)

Instead of setting a plain value you can also reference object path values from the sites TypoScript template by inserting a value like “{$lib.myConstant}”. Notice , the value will come from the Templates Setup field.

Example:

<TypoScript_constants>
  <backGroundColor>red</backGroundColor>
  <fontFile>{$_CONSTANTS.resources.fontFile}</fontFile>
</TypoScript_constants>

Here “_CONSTANTS.resources.fontFile” must be an object path with a value in the TypoScript template of the website!

Element

<int>

Format

boolean, 0/1

Description

Pass through intval() before output

Element

<HSC>

Format

boolean, 0/1

Description

Pass through htmlspecialchars() before output

Element

<stdWrap>

Format

string

Description

StdWrap properties as TypoScript, eg:

<proc>
        <stdWrap>
        trim = 1
        br = 1
        </stdWrap>
</proc>

Element

<langOverlayMode>

Format

string, keyword

Description

Setting the mode for content fallback when <meta><langChildren> and other languages are used in flexforms.

Normally inheritance from default language is enabled by default and globally disabled by the TypoScript setting “dontInheritValueFromDefault” if needed.

However through the Data Structure and TO / Local Processing XML you can overrule this per-field by this keyword.

In any case it only affects values from other languages than default and only if <langChildren> is enabled (thus using “vDEF” and sibling fields named “vXXX” for localization).

Keywords:

ifFalse - Content is inherited if it evaluates to false in PHP (meaning that zero and blank string falls back)

ifBlank - Content is inherited if it matched a blank string (trimmed)

never - Content is never inherited from default language!

removeIfBlank - If the value of this field is blank then the whole group of fields (element) is removed! This is a way of removing single elements for localizations in <langChildren>=1 constructions instead of inheriting content from default language.

[default] - If no keyword matches it uses the global mode.

Element

<displayHeaderFields>

Format

string

Description

A list of page-related fields which should be displayed as a header in the edit page view of the page module. By now, only table “page” is allowed / makes sense.

Note: This tag only takes effect when used in the top-level <tx_templavoilaplus> section, ie. one level below the <ROOT> tag.

img-8

Example:

<T3DataStructure>
   <ROOT>
      <tx_templavoilaplus>
         <pageModule>
            <displayHeaderFields>
               pages.keywords
               pages.mycustomfield
            </displayHeaderFields>
         </pageModule>
...

Element

<titleBarColor>

Format

color

Description

If you want to help your editors determining which data structure is used for the page they are currently working on, you may specify a color by using this tag. The title bar at the very top of the edit page screen will be displayed in that color.

You may use any value which is allowed in CSS (ie. “red” as well as “#FC2300” etc.)

Note: This tag only takes effect when used in the top-level <tx_templavoilaplus> section, ie. one level below the <ROOT> tag.

img-9

Example:

<T3DataStructure>
   <ROOT>
      <tx_templavoilaplus>
         <pageModule>
            <titleBarColor>orange</titleBarColor>
...

Element

<preview>

Format

String, keyword

Description

Keywords:

disable – Avoid that the TemplaVoilà! Plus page module includes the field into it’s data preview. That’s mainly meant keep the page modul nice and clean.

Element

Extensions to tags in the Data Structure

Element

<[field-name]><type>

Format

string

Description

In the Data Structure only “array” or blank makes sense. However for TemplaVoilà! Plus there is additional values possible, “attr” and “no_map”. This is a complete TemplaVoilà! Plus related overview of the <type> / <section> meanings:

  • <type>array</type> = Renders an array or objects
  • <type>array</type> + <section>1</section> = Renders a section which must contain other array-types (without <section> set!)
  • <type>attr</type> = The object is mapped to a HTML tag attribute .
  • <type>[blank]</type> = The object is mapped to a HTML tag element .
  • <type>no_map</type> = The object is not mappable (only editing in FlexForms eg.)

Sheets and TemplaVoilà! Plus

TemplaVoilà! Plus is compatible with definition of sheets. In that case a sheet <ROOT> element is shown in the mapping structure containing each sheet as <ROOT> elements under it. Even if multiple sheets are used TemplaVoilà! Plus renders only one sheet either determined by the sheetSelector or using the “sDEF” sheet by default.