TYPO3 offers an XML format, T3DataStructure, which defines a hierarchical data structure. In itself the data structure definition does do much - it is only a back bone for higher level applications which can add their own configuration inside.
Such applications can be:
“FlexForms” - a TCEform type which will allow users to build information hierarchies (in XML) according to the Data Structure. In this sense the Data Structure is like a DTD for the backend which can render a dynamic form based on the Data Structure
“TemplaVoila” - an extension which uses the Data Structure as backbone for mapping template HTML to data.
This documentation of a data structure will document the general aspects of the XML format and leave the details about FlexForms and TemplaVoila to be documented elsewhere.
Some other facts about Data Structures (DS):
A Data Structure is defined in XML with the document tag named “<T3DataStructure>”
The XML format generally complies with what can be converted into a PHP array by t3lib_div::xml2array() - thus it directly reflects how a multidimensional PHP array is constructed.
A Data Structure can be arranged in a set of “sheets”. The purpose of sheets will depend on the application. Basically sheets are like a one-dimensional internal categorization of Data Structures.
Parsing a Data Structure into a PHP array is incredibly easy - just pass it to t3lib_div::xml2array() (see example below)
“DS” is sometimes used as short for Data Structure
This is the elements and their nesting in the Data Structure. This could probably be expressed by a DTD or XML schema (anyone?). In this case I will just express it by an explanation of words.
Elements nesting other elements (“Array” elements):
All elements defined here cannot contain any string value but must contain another set of elements.
(In a PHP array this corresponds to saying that all these elements must be arrays.)
Element | Description | Child elements |
|---|---|---|
<T3DataStructure> | Document tag | <meta> <ROOT> or <sheets> |
<meta> | Can contain application specific meta settings | |
<ROOT> <[field name]> | Defines an “object” in the Data Structure
| <type> <section> <el> <[application tag]> |
<sheets> | Defines a collection of “sheets” which is like a one-dimensional list of independant Data Structures | <[sheet name]> |
<[sheet ident]> | Defines an independant data structure starting with a <ROOT> tag. Notice: Alternatively it can be a plain value referring to another XML file which contains the <ROOT> structure. See example below. | <ROOT> |
<el> | Contains a collection of Data Structure “objects” | <[field name]> |
Elements containing values (“Value” elements):
All elements defined here must contain a string value and no other XML tags whatsoever!
(In a PHP array this corresponds to saying that all these elements must be strings or integers.)
Element | Format | Description |
|---|---|---|
<type> | Keyword string: “array”, [blank] (=default) | Defines the type of object.
Notice: If the object was <ROOT> this tag must have the value “array” |
<section> | Boolean, 0/1 | Defines for an object of the type <array> that it must contain other “array” type objects. The meaning of this is application specific; For FlexForms it will allow the user to select between possible arrays of objects to create in the form. For TemplaVoila it will select a “container” element for another set of elements inside. This is quite fuzzy unless you understand the contexts. |
Example: FlexForm configuration in “mininews” extension
Simple example of a data structure used to define a FlexForm element in TCEforms. Notice the application specific section <TCEforms> (see documentation for FlexForms).
<T3DataStructure>
<meta>
<langDisable>1</langDisable>
</meta>
<ROOT>
<type>array</type>
<el>
<field_templateObject>
<TCEforms>
<label>LLL:EXT:mininews/locallang_db.php:tt_content.pi_flexform.select_template</label>
<config>
<type>select</type>
<items>
<numIndex index=”0”>
<numIndex index=”0”></numIndex>
<numIndex index=”1”>0</numIndex>
</numIndex>
</items>
<foreign_table>tx_templavoila_tmplobj</foreign_table>
<foreign_table_where>
AND tx_templavoila_tmplobj.pid=###STORAGE_PID###
AND tx_templavoila_tmplobj.datastructure="EXT:mininews/template_datastructure.xml"
AND tx_templavoila_tmplobj.parent=0
ORDER BY tx_templavoila_tmplobj.title
</foreign_table_where>
<size>1</size>
<minitems>0</minitems>
<maxitems>1</maxitems>
</config>
</TCEforms>
</field_templateObject>
</el>
</ROOT>
</T3DataStructure>
Example #2
More complex example of a FlexForms structure, using two sheets, “sDEF” and “s_welcome” (snippet from “newloginbox” extension).
<T3DataStructure>
<sheets>
<sDEF>
<ROOT>
<TCEforms>
<sheetTitle>LLL:EXT:newloginbox/locallang_db.php:tt_content.pi_flexform.sheet_general</sheetTitle>
</TCEforms>
<type>array</type>
<el>
<show_forgot_password>
<TCEforms>
<label>LLL:EXT:newloginbox/locallang_db.php:tt_content.pi_flexform.show_forgot_password</label>
<config>
<type>check</type>
</config>
</TCEforms>
</show_forgot_password>
</el>
</ROOT>
</sDEF>
<s_welcome>
<ROOT>
<TCEforms>
<sheetTitle>LLL:EXT:newloginbox/locallang_db.php:tt_content.pi_flexform.sheet_welcome</sheetTitle>
</TCEforms>
<type>array</type>
<el>
<header>
<TCEforms>
<label>LLL:EXT:newloginbox/locallang_db.php:tt_content.pi_flexform.header</label>
<config>
<type>input</type>
<size>30</size>
</config>
</TCEforms>
</header>
<message>
<TCEforms>
<label>LLL:EXT:newloginbox/locallang_db.php:tt_content.pi_flexform.message</label>
<config>
<type>text</type>
<cols>30</cols>
<rows>5</rows>
</config>
</TCEforms>
</message>
</el>
</ROOT>
</s_welcome>
</sheets>
</T3DataStructure>
If Data Structures are arranged in a collection of sheets you can choose to store one or more sheets externally in separate files. This is done by setting the value of the <[sheet ident]> tag to a relative file reference instead of being a definition of the <ROOT> element.
Example
Taking the Data Structure from Example #2 above we can now rearrange it in three files:
Main Data Structure:
<T3DataStructure>
<sheets>
<sDEF>fileadmin/sheets/default_sheet.xml</sDEF>
<s_welcome>fileadmin/sheets/welcome_sheet.xml</s_welcome>
</sheets>
</T3DataStructure>
fileadmin/sheets/default_sheet.xml
<T3DataStructure>
<ROOT>
<TCEforms>
<sheetTitle>LLL:EXT:newloginbox/locallang_db.php:tt_content.pi_flexform.sheet_general</sheetTitle>
</TCEforms>
<type>array</type>
<el>
<show_forgot_password>
<TCEforms>
<label>LLL:EXT:newloginbox/locallang_db.php:tt_content.pi_flexform.show_forgot_password</label>
<config>
<type>check</type>
</config>
</TCEforms>
</show_forgot_password>
</el>
</ROOT>
</T3DataStructure>
fileadmin/sheets/welcome_sheet.xml
<T3DataStructure>
<ROOT>
<TCEforms>
<sheetTitle>LLL:EXT:newloginbox/locallang_db.php:tt_content.pi_flexform.sheet_welcome</sheetTitle>
</TCEforms>
<type>array</type>
<el>
<header>
<TCEforms>
<label>LLL:EXT:newloginbox/locallang_db.php:tt_content.pi_flexform.header</label>
<config>
<type>input</type>
<size>30</size>
</config>
</TCEforms>
</header>
<message>
<TCEforms>
<label>LLL:EXT:newloginbox/locallang_db.php:tt_content.pi_flexform.message</label>
<config>
<type>text</type>
<cols>30</cols>
<rows>5</rows>
</config>
</TCEforms>
</message>
</el>
</ROOT>
</T3DataStructure>
You can syntax highlight a data structure using the extension “extdeveval” and the code highlighter. Just copy the DS XML content into the form:
You can convert a Data Structure XML document into a PHP array by the function t3lib_div::xml2array(). Taking the simple DS above:
<T3DataStructure>
<meta>
<langDisable>1</langDisable>
</meta>
<ROOT>
<type>array</type>
<el>
<field_templateObject>
<TCEforms>
<label>LLL:EXT:mininews/locallang_db.php:tt_content.pi_flexform.select_template</label>
<config>
<type>select</type>
<items>
<numIndex index=”0”>
<numIndex index=”0”></numIndex>
<numIndex index=”1”>0</numIndex>
</numIndex>
</items>
<foreign_table>tx_templavoila_tmplobj</foreign_table>
<foreign_table_where>
AND tx_templavoila_tmplobj.pid=###STORAGE_PID###
AND tx_templavoila_tmplobj.datastructure="EXT:mininews/template_datastructure.xml"
AND tx_templavoila_tmplobj.parent=0
ORDER BY tx_templavoila_tmplobj.title
</foreign_table_where>
<size>1</size>
<minitems>0</minitems>
<maxitems>1</maxitems>
</config>
</TCEforms>
</field_templateObject>
</el>
</ROOT>
</T3DataStructure>
Passing this to the xml2array function and you will get an array like this (screen shot from “extdeveval”):
As you can see the format of the XML generated by t3lib_div::array2xml() is designed to reflect the array structures PHP can contain and thus the transformation to and from XML with the functions t3lib_div::array2xml() and t3lib_div::xml2array() is very easy and quick.
API functions for sheets
If you have a DS with sheets inside you might need to resolve the references:
<T3DataStructure>
<sheets>
<sDEF>fileadmin/sheets/default_sheet.xml</sDEF>
<s_welcome>fileadmin/sheets/welcome_sheet.xml</s_welcome>
</sheets>
</T3DataStructure>
This is done by t3lib_div::resolveSheetDefInDS() or t3lib_div::resolveAllSheetsInDS(). In fact, even if you don't have sheets in your file but just want to stay compatible with DS XML with sheets you should use this function. For instance these function calls will parse the DS into an array (screen shot above) and resolve the sheet definition, in this case creating a default sheet “sDEF” (screen shot below):
$treeDat = t3lib_div::xml2array($inputCode);
$treeDat = t3lib_div::resolveAllSheetsInDS($treeDat);
For a more practical understanding of Data Structures you should study some of the applications of Data Structures:
FlexForms - using Data Structures as a “DTD” for rendering a hierarchical editing form which saves the content back into XML
TemplaVoila - using Data Structures for mapping content to HTML template files.
