TYPO3 12.4 API: FlexFormTools

FlexFormTools

Contains functions for manipulating flex form data

The data structure identifier (array) has several commonly used elements (keys), but is generally undefined. Users of this system should be extra careful of what array keys are defined or not.

Recommended keys include:

type
tableName
fieldName
dataStructureKey

Properties

$callBackObj : object: Reference to object called
$cleanFlexFormXML : array<string|int, mixed>: Used for accumulation of clean XML
$flexArray2Xml_options : array<string|int, mixed>: Options for array2xml() for flexform.
$reNumberIndexesOfSectionData : bool: If set, section indexes are re-numbered before processing

Methods

__construct() : mixed
cleanFlexFormXML() : string: Cleaning up FlexForm XML to hold only the values it may according to its Data Structure. Also the order of tags will follow that of the data structure.
cleanFlexFormXML_callBackFunction() : mixed: Call back function for \TYPO3\CMS\Core\Configuration\FlexForm\FlexFormTools class Basically just setting the value in a new array (thus cleaning because only values that are valid are visited!)
flexArray2Xml() : string: Convert FlexForm data array to XML
getDataStructureIdentifier() : string: The method locates a specific data structure from given TCA and row combination and returns an identifier string that can be handed around, and can be resolved to a single data structure later without giving $row and $tca data again.
migrateFlexFormTcaRecursive() : array<string|int, mixed>: Recursively migrate flex form TCA
parseDataStructureByIdentifier() : array<string|int, mixed>: Parse a data structure identified by $identifier to the final data structure array.
removeElementTceFormsRecursive() : array<string|int, mixed>: Remove "TCEforms" key from all elements in data structure to simplify further parsing.
traverseFlexFormXMLData() : bool|string: Handler for Flex Forms
traverseFlexFormXMLData_recurse() : void: Recursively traversing flexform data according to data structure and element data
convertDataStructureToArray() : array<string|int, mixed>
ensureDefaultSheet() : array<string|int, mixed>: Ensures a data structure has a default sheet, and no duplicate data
executeCallBackMethod() : mixed: Execute method on callback object
getDataStructureIdentifierFromRecord() : array<string|int, mixed>: The data structure is located in a record. This method resolves the record and returns an array to identify that record.
getDataStructureIdentifierFromTcaArray() : array<string|int, mixed>: Find matching data structure in TCA ds array.
getDefaultIdentifier() : array<string|int, mixed>: Returns the default data structure identifier.
getDefaultStructureForIdentifier() : string
prepareCategoryFields() : array<string|int, mixed>: Prepare type=category fields if given.
prepareFileFields() : array<string|int, mixed>: Prepare type=file fields if given.
resolveFileDirectives() : array<string|int, mixed>: Resolve FILE:EXT and EXT: for single sheets

$callBackObj

Reference to object called


        public
            object
    $callBackObj

$cleanFlexFormXML

Used for accumulation of clean XML


        public
            array<string|int, mixed>
    $cleanFlexFormXML
     = []

$flexArray2Xml_options

Options for array2xml() for flexform.


        public
            array<string|int, mixed>
    $flexArray2Xml_options
     = ['parentTagMap' => ['data' => 'sheet', 'sheet' => 'language', 'language' => 'field', 'el' => 'field', 'field' => 'value', 'field:el' => 'el', 'el:_IS_NUM' => 'section', 'section' => 'itemType'], 'disableTypeAttrib' => 2]

This will map the weird keys from the internal array to tags that could potentially be checked with a DTD/schema

$reNumberIndexesOfSectionData

If set, section indexes are re-numbered before processing


        public
            bool
    $reNumberIndexesOfSectionData
     = false

__construct()


    public
                    __construct([EventDispatcherInterface|null $eventDispatcher = null ]) : mixed

Parameters

$eventDispatcher : EventDispatcherInterface|null = null

cleanFlexFormXML()

Cleaning up FlexForm XML to hold only the values it may according to its Data Structure. Also the order of tags will follow that of the data structure.


    public
                    cleanFlexFormXML(string $table, string $field, array<string|int, mixed> $row) : string

BE CAREFUL: DO not clean records in workspaces unless IN the workspace! The Data Structure might resolve falsely on a workspace record when cleaned from Live workspace.

Parameters

$table : string: Table name
$field : string: Field name of the flex form field in which the XML is found that should be cleaned.
$row : array<string|int, mixed>: The record

Return values

string —

Clean XML from FlexForm field

cleanFlexFormXML_callBackFunction()

Call back function for \TYPO3\CMS\Core\Configuration\FlexForm\FlexFormTools class Basically just setting the value in a new array (thus cleaning because only values that are valid are visited!)


    public
                    cleanFlexFormXML_callBackFunction(array<string|int, mixed> $dsArr, mixed $data, array<string|int, mixed> $PA, string $path, FlexFormTools $pObj) : mixed

Parameters

$dsArr : array<string|int, mixed>: Data structure for the current value
$data : mixed: Current value
$PA : array<string|int, mixed>: Additional configuration used in calling function
$path : string: Path of value in DS structure
$pObj : FlexFormTools: caller

flexArray2Xml()

Convert FlexForm data array to XML


    public
                    flexArray2Xml(array<string|int, mixed> $array[, bool $addPrologue = false ]) : string

Parameters

$array : array<string|int, mixed>: Array to output in <T3FlexForms> XML
$addPrologue : bool = false: If set, the XML prologue is returned as well.

Return values

string —

XML content.

getDataStructureIdentifier()

The method locates a specific data structure from given TCA and row combination and returns an identifier string that can be handed around, and can be resolved to a single data structure later without giving $row and $tca data again.


    public
                    getDataStructureIdentifier(array<string|int, mixed> $fieldTca, string $tableName, string $fieldName, array<string|int, mixed> $row) : string

Note: The returned syntax is meant to only specify the target location of the data structure. It SHOULD NOT be abused and enriched with data from the record that is dealt with. For instance, it is now allowed to add source record specific date like the uid or the pid! If that is done, it is up to the hook consumer to take care of possible side effects, eg. if the data handler copies or moves records around and those references change.

This method gets: Source data that influences the target location of a data structure This method returns: Target specification of the data structure

This method is "paired" with method getFlexFormDataStructureByIdentifier() that will resolve the returned syntax again and returns the data structure itself.

Both methods can be extended via events to return and accept additional identifier strings if needed, and to transmit further information within the identifier strings.

Note that the TCA for data structure definitions MUST NOT be overridden by 'columnsOverrides' or by parent TCA in an inline relation! This would create a huge mess.

Note: This method and the resolving methods below are well unit tested and document all nasty details this way.

Parameters

$fieldTca : array<string|int, mixed>: Full TCA of the field in question that has type=flex set
$tableName : string: The table name of the TCA field
$fieldName : string: The field name
$row : array<string|int, mixed>: The data row

Return values

string —

Identifier JSON string

migrateFlexFormTcaRecursive()

Recursively migrate flex form TCA


    public
                    migrateFlexFormTcaRecursive(array<string|int, mixed> $structure) : array<string|int, mixed>

Parameters

$structure : array<string|int, mixed>

Return values

array<string|int, mixed>

parseDataStructureByIdentifier()

Parse a data structure identified by $identifier to the final data structure array.


    public
                    parseDataStructureByIdentifier(string $identifier) : array<string|int, mixed>

This method is called after getDataStructureIdentifier(), finds the data structure and returns it.

Hooks allow to manipulate the find logic and to post process the data structure array.

Note that the TCA for data structure definitions MUST NOT be overridden by 'columnsOverrides' or by parent TCA in an inline relation! This would create a huge mess.

After the data structure definition is found, the method resolves:

FILE:EXT: prefix of the data structure itself - the ds is in a file
FILE:EXT: prefix for sheets - if single sheets are in files
Create an sDEF sheet if the data structure has non, yet.

After that method is run, the data structure is fully resolved to an array, and same base normalization is done: If the ds did not contain a sheet, it will have one afterwards as "sDEF"

This method gets: Target specification of the data structure. This method returns: The normalized data structure parsed to an array.

Read the unit tests for nasty details.

Parameters

$identifier : string: JSON string to find the data structure location

Return values

array<string|int, mixed> —

Parsed and normalized data structure

removeElementTceFormsRecursive()

Remove "TCEforms" key from all elements in data structure to simplify further parsing.


    public
                    removeElementTceFormsRecursive(array<string|int, mixed> $structure) : array<string|int, mixed>

Example config: ['config']['ds']['sheets']['sDEF']['ROOT']['el']['anElement']['TCEforms']['label'] becomes ['config']['ds']['sheets']['sDEF']['ROOT']['el']['anElement']['label']

and

['ROOT']['TCEforms']['sheetTitle'] becomes ['ROOT']['sheetTitle']

Parameters

$structure : array<string|int, mixed>

Internal

This method serves as a compatibility layer and will be removed in TYPO3 v13.

Return values

array<string|int, mixed>

traverseFlexFormXMLData()

Handler for Flex Forms


    public
                    traverseFlexFormXMLData(string $table, string $field, array<string|int, mixed> $row, object $callBackObj, string $callBackMethod_value) : bool|string

Parameters

$table : string: The table name of the record
$field : string: The field name of the flexform field to work on
$row : array<string|int, mixed>: The record data array
$callBackObj : object: Object in which the call back function is located
$callBackMethod_value : string: Method name of call back function in object for values

Return values

bool|string —

true on success, string if error happened (error string returned)

traverseFlexFormXMLData_recurse()

Recursively traversing flexform data according to data structure and element data


    public
                    traverseFlexFormXMLData_recurse(array<string|int, mixed> $dataStruct, array<string|int, mixed> $editData, array<string|int, mixed> &$PA[, string $path = '' ]) : void

Parameters

$dataStruct : array<string|int, mixed>: (Part of) data structure array that applies to the sub section of the flexform data we are processing
$editData : array<string|int, mixed>: (Part of) edit data array, reflecting current part of data structure
$PA : array<string|int, mixed>: Additional parameters passed.
$path : string = '': Telling the "path" to the element in the flexform XML

convertDataStructureToArray()


    protected
                    convertDataStructureToArray(string|array<string|int, mixed> $dataStructure) : array<string|int, mixed>

Parameters

$dataStructure : string|array<string|int, mixed>

Return values

array<string|int, mixed>

ensureDefaultSheet()

Ensures a data structure has a default sheet, and no duplicate data


    protected
                    ensureDefaultSheet(array<string|int, mixed> $dataStructure) : array<string|int, mixed>

Parameters

$dataStructure : array<string|int, mixed>

Return values

array<string|int, mixed>

executeCallBackMethod()

Execute method on callback object


    protected
                    executeCallBackMethod(string $methodName, array<string|int, mixed> $parameterArray) : mixed

Parameters

$methodName : string: Method name to call
$parameterArray : array<string|int, mixed>: Parameters

Return values

mixed —

Result of callback object

getDataStructureIdentifierFromRecord()

The data structure is located in a record. This method resolves the record and returns an array to identify that record.


    protected
                    getDataStructureIdentifierFromRecord(array<string|int, mixed> $fieldTca, string $tableName, string $fieldName, array<string|int, mixed> $row) : array<string|int, mixed>

The example setup below looks in current row for a tx_templavoila_ds value. If not found, it will search the rootline (the table is a tree, typically pages) until a value in tx_templavoila_next_ds or tx_templavoila_ds is found. That value should then be an integer, that points to a record in tx_templavoila_datastructure, and then the data structure is found in field dataprot:

fieldTca = [ 'config' => [ 'type' => 'flex', 'ds_pointerField' => 'tx_templavoila_ds', 'ds_pointerField_searchParent' => 'pid', 'ds_pointerField_searchParent_subField' => 'tx_templavoila_next_ds', 'ds_tableField' => 'tx_templavoila_datastructure:dataprot', ] ]

More simple scenario without tree traversal and having a valid data structure directly located in field theFlexDataStructureField.

fieldTca = [ 'config' => [ 'type' => 'flex', 'ds_pointerField' => 'theFlexDataStructureField', ] ]

Example return array: [ 'type' => 'record', 'tableName' => 'tx_templavoila_datastructure', 'uid' => 42, 'fieldName' => 'dataprot', ];

Parameters

$fieldTca : array<string|int, mixed>: Full TCA of the field in question that has type=flex set
$tableName : string: The table name of the TCA field
$fieldName : string: The field name
$row : array<string|int, mixed>: The data row

Return values

array<string|int, mixed> —

Identifier as array, see example above

getDataStructureIdentifierFromTcaArray()

Find matching data structure in TCA ds array.


    protected
                    getDataStructureIdentifierFromTcaArray(array<string|int, mixed> $fieldTca, string $tableName, string $fieldName, array<string|int, mixed> $row) : array<string|int, mixed>

Data structure is defined in 'ds' config array. Also, there can be a ds_pointerField

fieldTca = [ 'config' => [ 'type' => 'flex', 'ds' => [ 'aName' => '<T3DataStructure>...' OR 'FILE:...' ], 'ds_pointerField' => 'optionalSetting,upToTwoCommaSeparatedFieldNames', ] ]

This method returns an array of the form: [ 'type' => 'Tca:', 'tableName' => $tableName, 'fieldName' => $fieldName, 'dataStructureKey' => $key, ];

Example: [ 'type' => 'Tca:', 'tableName' => 'tt_content', 'fieldName' => 'pi_flexform', 'dataStructureKey' => 'powermail_pi1,list', ];

Parameters

$fieldTca : array<string|int, mixed>: Full TCA of the field in question that has type=flex set
$tableName : string: The table name of the TCA field
$fieldName : string: The field name
$row : array<string|int, mixed>: The data row

Return values

array<string|int, mixed> —

Identifier as array, see example above

getDefaultIdentifier()

Returns the default data structure identifier.


    protected
                    getDefaultIdentifier(array<string|int, mixed> $fieldTca, string $tableName, string $fieldName, array<string|int, mixed> $row) : array<string|int, mixed>

Parameters

$fieldTca : array<string|int, mixed>: Full TCA of the field in question that has type=flex set
$tableName : string: The table name of the TCA field
$fieldName : string: The field name
$row : array<string|int, mixed>: The data row

Return values

array<string|int, mixed>

getDefaultStructureForIdentifier()


    protected
                    getDefaultStructureForIdentifier(array<string|int, mixed> $identifier) : string

Parameters

$identifier : array<string|int, mixed>

Return values

string

prepareCategoryFields()

Prepare type=category fields if given.


    protected
                    prepareCategoryFields(array<string|int, mixed> $dataStructureSheets) : array<string|int, mixed>

NOTE: manyToMany relationships are not supported!

Parameters

$dataStructureSheets : array<string|int, mixed>

Return values

array<string|int, mixed> —

The processed $dataStructureSheets

prepareFileFields()

Prepare type=file fields if given.


    protected
                    prepareFileFields(array<string|int, mixed> $dataStructureSheets) : array<string|int, mixed>

Parameters

$dataStructureSheets : array<string|int, mixed>

Return values

array<string|int, mixed> —

The processed $dataStructureSheets

resolveFileDirectives()

Resolve FILE:EXT and EXT: for single sheets


    protected
                    resolveFileDirectives(array<string|int, mixed> $dataStructure) : array<string|int, mixed>

Parameters

$dataStructure : array<string|int, mixed>

Return values

array<string|int, mixed>

FlexFormTools

Table of Contents

Properties

Methods

Properties

$callBackObj

$cleanFlexFormXML

$flexArray2Xml_options

$reNumberIndexesOfSectionData

Methods

__construct()

Parameters

cleanFlexFormXML()

Parameters

Return values

cleanFlexFormXML_callBackFunction()

Parameters

flexArray2Xml()

Parameters

Return values

getDataStructureIdentifier()

Parameters

Tags

Return values

migrateFlexFormTcaRecursive()

Parameters

Return values

parseDataStructureByIdentifier()

Parameters

Tags

Return values

removeElementTceFormsRecursive()

Parameters

Return values

traverseFlexFormXMLData()

Parameters

Return values

traverseFlexFormXMLData_recurse()

Parameters

convertDataStructureToArray()

Parameters

Return values

ensureDefaultSheet()

Parameters

Return values

executeCallBackMethod()

Parameters

Return values

getDataStructureIdentifierFromRecord()

Parameters

Tags

Return values

getDataStructureIdentifierFromTcaArray()

Parameters

Tags

Return values

getDefaultIdentifier()

Parameters

Return values

getDefaultStructureForIdentifier()

Parameters

Return values

prepareCategoryFields()

Parameters

Return values

prepareFileFields()

Parameters

Return values

resolveFileDirectives()

Parameters

Return values