260 lines
9.1 KiB
ReStructuredText
260 lines
9.1 KiB
ReStructuredText
.. include:: /Includes.rst.txt
|
|
|
|
.. _breaking-107047-1751982363:
|
|
|
|
==================================================================
|
|
Breaking: #107047 - Remove pointer field functionality of TCA flex
|
|
==================================================================
|
|
|
|
See :issue:`107047`
|
|
|
|
Description
|
|
===========
|
|
|
|
One of the main features of TCA is the concept of *record types*. This allows
|
|
using a single table for different purposes and in different contexts. The
|
|
most well-known examples are the "Page Types" of the :sql:`pages` table and the
|
|
"Content Types" of the :sql:`tt_content` table. For every specific type, it is
|
|
possible to define which fields to display and to customize their
|
|
configuration.
|
|
|
|
A special case historically has been plugin registration, which for a long
|
|
time used the so-called *subtypes* feature of TCA. This was an additional layer
|
|
below record types, configured using `subtype_value_field` (commonly
|
|
`list_type`), and optionally `subtypes_addlist` and
|
|
`subtypes_excludelist` to add or remove fields depending on the selected
|
|
subtype.
|
|
|
|
FlexForms attached to such subtypes were configured using
|
|
`ds_pointerField` (typically pointing to `list_type,CType`). This came in
|
|
combination with the corresponding `ds` configuration, which was an array
|
|
with keys combining the pointer fields, for example:
|
|
|
|
.. code-block:: php
|
|
|
|
'ds_pointerField' => 'list_type,CType',
|
|
'ds' => [
|
|
'news_pi1,list' => 'FILE:EXT:news/Configuration/FlexForm.xml',
|
|
'default' => 'FILE:...'
|
|
],
|
|
|
|
Over recent TYPO3 versions, this approach has been deprecated in favor of
|
|
using record types exclusively for plugin registration via the `CType` field,
|
|
making configuration cleaner and easier to understand.
|
|
|
|
The special plugin content element (`CType=list`) and the corresponding plugin
|
|
subtype field `list_type` have been deprecated in
|
|
:ref:`deprecation-105076-1726923626` and removed in
|
|
:ref:`breaking-105377-1729513863`.
|
|
See also :ref:`important-105538-1730752784` for related information about
|
|
:php:`ExtensionUtility::configurePlugin()` and
|
|
:php:`ExtensionManagementUtility::addTcaSelectItemGroup()`.
|
|
|
|
With this change, support for `ds_pointerField` and the multi-entry
|
|
`ds` array format has now been removed. The `ds` option now points to
|
|
a single FlexForm, either directly or via a `FILE:` reference.
|
|
|
|
FlexForms must instead be assigned via standard `types` configuration
|
|
using `columnsOverrides`.
|
|
|
|
This also affects the *data structure identifier*, which in the commonly used
|
|
`tca` type is the `dataStructureKey`. It is now set to `default` if the
|
|
table does not support record types or no record type-specific configuration
|
|
exists. Otherwise, the `dataStructureKey` is set to the corresponding
|
|
record type value, for example `textpic`.
|
|
|
|
This change affects the following PSR-14 events:
|
|
|
|
* :php-short:`\TYPO3\CMS\Core\Configuration\Event\AfterFlexFormDataStructureIdentifierInitializedEvent`
|
|
* :php-short:`\TYPO3\CMS\Core\Configuration\Event\AfterFlexFormDataStructureParsedEvent`
|
|
* :php-short:`\TYPO3\CMS\Core\Configuration\Event\BeforeFlexFormDataStructureIdentifierInitializedEvent`
|
|
* :php-short:`\TYPO3\CMS\Core\Configuration\Event\BeforeFlexFormDataStructureParsedEvent`
|
|
|
|
A fallback for TYPO3 v14 resolves comma-separated `dataStructureKey`
|
|
values (for example, `list_type,CType`) to `CType`. Such comma-separated
|
|
keys were used to address flex form fields in page TSconfig overrides via
|
|
`TCEFORM.<table>.<field>.<dataStructureKey>` and in backend user exclude-field
|
|
definitions via `<table>:<field>;<dataStructureKey>`. This fallback emits a
|
|
PHP deprecation notice and is removed in TYPO3 v15, so page TSconfig and
|
|
exclude-field addressing then use the data structure key as-is (the record
|
|
type value, for example `textpic`).
|
|
|
|
To address circular dependencies during schema building,
|
|
:php-short:`\TYPO3\CMS\Core\Configuration\FlexForm\FlexFormTools` now supports
|
|
both TCA Schema objects and raw TCA configuration arrays as input. The
|
|
following methods accept a union type :php:`array|TcaSchema` for the new
|
|
:php:`$schema` parameter:
|
|
|
|
* :php:`getDataStructureIdentifier()`
|
|
* :php:`parseDataStructureByIdentifier()`
|
|
* :php:`cleanFlexFormXML()`
|
|
|
|
Previously, these methods relied on :php:`$GLOBALS['TCA']` internally, which
|
|
caused architectural issues. They now operate directly on the provided schema.
|
|
|
|
All calls to these methods should provide the :php:`$schema` parameter with
|
|
either a :php-short:`\TYPO3\CMS\Core\Schema\TcaSchema` instance or a raw TCA
|
|
configuration array. Since data structure resolution can be customized by
|
|
extensions, the parameter is not strictly mandatory, but it is strongly
|
|
recommended to provide it in most cases. An
|
|
:php-short:`\TYPO3\CMS\Core\Configuration\FlexForm\Exception\InvalidTcaSchemaException`
|
|
will be thrown if schema resolution is required but no schema is passed.
|
|
|
|
This change also enables components like
|
|
:php-short:`\TYPO3\CMS\Core\Schema\RelationMapBuilder` to use
|
|
:php-short:`\TYPO3\CMS\Core\Configuration\FlexForm\FlexFormTools` during schema
|
|
building, even when only raw TCA is available.
|
|
|
|
For further details on the enhanced FlexFormTools functionality, see
|
|
:ref:`feature-107047-1751984817`.
|
|
|
|
The following class has been removed as it is no longer required:
|
|
|
|
* :php-short:`\TYPO3\CMS\Core\Configuration\FlexForm\Exception\InvalidCombinedPointerFieldException`
|
|
|
|
Impact
|
|
======
|
|
|
|
**FlexForm Pointer Field Removal**
|
|
|
|
Any TCA definition that still uses :php:`ds_pointerField` or a `ds`
|
|
array with multiple entries (for example `news_pi1,list`) will no longer work
|
|
and might cause rendering errors.
|
|
|
|
**FlexFormTools Schema Parameter**
|
|
|
|
All code calling :php-short:`\TYPO3\CMS\Core\Configuration\FlexForm\FlexFormTools`
|
|
methods (:php:`getDataStructureIdentifier()`,
|
|
:php:`parseDataStructureByIdentifier()`, :php:`cleanFlexFormXML()`) must be
|
|
updated to provide the required :php:`$schema` parameter.
|
|
|
|
Affected installations
|
|
======================
|
|
|
|
**FlexForm Pointer Field Removal**
|
|
|
|
All installations using :php:`ds_pointerField` (as the pointer field
|
|
functionality has been removed entirely) or an array-like structure for
|
|
`ds` in their TCA field type `flex` configuration.
|
|
|
|
**FlexFormTools Schema Parameter**
|
|
|
|
All installations with custom code that directly call
|
|
:php-short:`\TYPO3\CMS\Core\Configuration\FlexForm\FlexFormTools` methods
|
|
without providing the :php:`$schema` parameter.
|
|
This includes custom extensions or TYPO3 Core patches using these methods.
|
|
|
|
A TCA migration automatically converts single-entry `ds` arrays.
|
|
Multi-entry definitions require manual migration, as they must be aligned with
|
|
the correct record type configuration, which may require additional
|
|
configuration changes beforehand.
|
|
|
|
Example for single-entry migration:
|
|
|
|
**Before:**
|
|
|
|
.. code-block:: php
|
|
:caption: Migration of single-entry ds configuration (before)
|
|
|
|
'ds' => [
|
|
'default' => '<T3DataStructure>...',
|
|
],
|
|
|
|
**After:**
|
|
|
|
.. code-block:: php
|
|
:caption: Migration of single-entry ds configuration (after)
|
|
|
|
'ds' => '<T3DataStructure>...',
|
|
|
|
Migration
|
|
=========
|
|
|
|
**FlexForm Pointer Field Migration**
|
|
|
|
**Before:**
|
|
|
|
.. code-block:: php
|
|
|
|
'ds_pointerField' => 'list_type,CType',
|
|
'ds' => [
|
|
'news_pi1,list' => 'FILE:EXT:news/Configuration/FlexForm.xml',
|
|
'default' => '<T3DataStructure>...',
|
|
],
|
|
|
|
**After:**
|
|
|
|
.. code-block:: php
|
|
|
|
'columns' => [
|
|
'pi_flexform' => [
|
|
'config' => [
|
|
'ds' => '<T3DataStructure>...',
|
|
],
|
|
],
|
|
],
|
|
'types' => [
|
|
'news_pi1' => [
|
|
'columnsOverrides' => [
|
|
'pi_flexform' => [
|
|
'config' => [
|
|
'ds' => 'FILE:EXT:news/Configuration/FlexForm.xml',
|
|
],
|
|
],
|
|
],
|
|
],
|
|
],
|
|
|
|
If no `columnsOverrides` is defined, the default `ds` value of the
|
|
field configuration will be used as before.
|
|
|
|
**FlexFormTools Schema Parameter Migration**
|
|
|
|
**Before:**
|
|
|
|
.. code-block:: php
|
|
|
|
use TYPO3\CMS\Core\Configuration\FlexForm\FlexFormTools;
|
|
use TYPO3\CMS\Core\Utility\GeneralUtility;
|
|
|
|
$flexFormTools = GeneralUtility::makeInstance(FlexFormTools::class);
|
|
$identifier = $flexFormTools->getDataStructureIdentifier(
|
|
$fieldTca,
|
|
'tt_content',
|
|
'pi_flexform',
|
|
$row
|
|
);
|
|
|
|
**After:**
|
|
|
|
.. code-block:: php
|
|
|
|
use TYPO3\CMS\Core\Configuration\FlexForm\FlexFormTools;
|
|
use TYPO3\CMS\Core\Schema\TcaSchemaFactory;
|
|
use TYPO3\CMS\Core\Utility\GeneralUtility;
|
|
|
|
$flexFormTools = GeneralUtility::makeInstance(FlexFormTools::class);
|
|
|
|
// Option 1: Using TCA Schema object (recommended for normal usage)
|
|
$tcaSchemaFactory = GeneralUtility::makeInstance(TcaSchemaFactory::class);
|
|
$tcaSchema = $tcaSchemaFactory->get('tt_content');
|
|
$identifier = $flexFormTools->getDataStructureIdentifier(
|
|
$fieldTca,
|
|
'tt_content',
|
|
'pi_flexform',
|
|
$row,
|
|
$tcaSchema
|
|
);
|
|
|
|
// Option 2: Using raw TCA array (for schema building contexts)
|
|
$rawTca = $fullTca['tt_content'];
|
|
$identifier = $flexFormTools->getDataStructureIdentifier(
|
|
$fieldTca,
|
|
'tt_content',
|
|
'pi_flexform',
|
|
$row,
|
|
$rawTca
|
|
);
|
|
|
|
.. index:: Backend, FlexForm, TCA, PartiallyScanned, ext:core
|