[TASK] Deprecate TCA subtypes

Documentation/ColumnsConfig/Type/Flex/Examples.rst

@@ -32,39 +32,25 @@ Notice the :xml:`<input_1>` tag:
 It's clear that the contents of :xml:`<input_1>` is a direct reflection of
 the field configurations we normally set up in the :php:`$GLOBALS['TCA']` array.
 
+..  _columns-flex-example-plugin:
 
 FlexForm in a plugin
 ====================
 
-The Data Structure for a FlexForm can also be loaded in the :sql:`pi_flexform`
+The data structure for a FlexForm can also be loaded in the :sql:`pi_flexform`
 field of the :sql:`tt_content` table by adding the following in the
-TCA Overrides of an extension:
+TCA Overrides of an extension, see this example from the extension :composer:`t3docs/blog-example`:
 
-..  code-block:: php
-    :caption: EXT:my_extension/Configuration/TCA/Overrides/tt_content.php
+..  literalinclude:: _CodeSnippets/_tt_content_plugin.php
+    :linenos:
+    :caption: EXT:blog_example/Configuration/TCA/Overrides/tt_content.php
 
-    $GLOBALS['TCA']['tt_content']['types']['list']['subtypes_addlist']['myextension_pi1']
-        = 'pi_flexform';
-    \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addPiFlexFormValue(
-        'myextension_pi1',
-        'FILE:EXT:examples/Configuration/FlexForms/Main.xml');
-
-In the first line the :sql:`tt_content` field :sql:`pi_flexform` is added to the display
-of fields when the plugin type is selected and set to :php:`myextension_pi1`. In the
-second line the DS xml file is configured to be the source of the FlexForm DS
-used.
-
-If we browse the definition for the :sql:`pi_flexform` field in :sql:`tt_content` below
-"columns" using the :guilabel:`Admin > Configuration` module for
-:guilabel:`$GLOBALS['TCA'] (Table configuration array)`,
-we can see the following:
-
-..  include:: /Images/Rst/PluginFlexFormConfigurationCheck.rst.txt
-
-As you can see there are quite a few extensions that have added pointers to
-their Data Structures. Towards the bottom we can find the one we have just been
-looking at.
+In line 18ff the field :sql:`pi_flexform` is added to the display
+of fields when the record type of the plugin is selected.
 
+In line 25ff the method `addPiFlexFormValue()` from class
+:php-short:`\TYPO3\CMS\Core\Utility\ExtensionManagementUtility` is used to
+register the FlexForm.
 
 ..  _columns-flex-example-sheets:
 ..  _tca_example_flex_1:

Documentation/ColumnsConfig/Type/Flex/_CodeSnippets/_tt_content_plugin.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
+use TYPO3\CMS\Extbase\Utility\ExtensionUtility;
+
+defined('TYPO3') or die();
+
+$pluginKey = ExtensionUtility::registerPlugin(
+    'blog_example',
+    'BlogList',
+    'List of Blogs (BlogExample)',
+    'blog_example_icon',
+    'plugins',
+    'Display a list of blogs',
+);
+
+ExtensionManagementUtility::addToAllTCAtypes(
+    'tt_content',
+    '--div--;Configuration,pi_flexform',
+    $pluginKey,
+    'after:subheader',
+);
+
+ExtensionManagementUtility::addPiFlexFormValue(
+    '*',
+    'FILE:EXT:blog_example/Configuration/FlexForms/PluginSettings.xml',
+    $pluginKey,
+);

Documentation/Ctrl/_Properties/_PreviewRenderer.rst.txt

@@ -11,7 +11,7 @@
     Have also a look at :ref:`t3coreapi:ConfigureCE-Preview` for more details.
 
     Use :confval:`property previewRenderer of section types <types-previewRenderer>`
-    to configure the preview for a certain type or subtype only.
+    to configure the preview for a certain type only.
 
     ..  rubric:: Example: Use for any record in a table
 

Documentation/Types/SubtypeMigration.rst

@@ -0,0 +1,79 @@
+:navigation-title: Subtype migration
+
+..  include:: /Includes.rst.txt
+
+..  _types-example-subtypes:
+..  _types-example-subtypes-remove:
+..  _types-example-subtypes-remove-types:
+..  _migration-subtype:
+
+================================
+Migration from subtypes to types
+================================
+
+..  contents:: Table of contents
+
+..  _migration-subtype-flexform:
+
+Migrate plugins with FlexForms added via `subtypes_addlist`
+===========================================================
+
+If you used plugins with the now deprecated subtypes, you probably used
+:confval:`types-subtypes-addlist` to display a
+:ref:`FlexForm <t3coreapi:flexforms>` for configuration purposes.
+
+Migrate by adding the field :sql:`pi_flexform` with the utility method
+:php-short:`\TYPO3\CMS\Core\Utility\ExtensionManagementUtility`
+`addToAllTCAtypes()` instead. You also have to change the parameters used for
+method `addPiFlexFormValue()`:
+
+..  literalinclude:: _CodeSnippets/_subtype_plugin_migration.diff
+    :caption: EXT:my_extension/Configuration/Overrides/tt_content.php
+
+The fields :sql:`pages` and :sql:`recursive` used to be added
+automatically to plugins when using the now outdated subtype "list_type".
+Therefore they have to be added manually when doing the migration.
+
+..  _migration-subtype-subtypes-excludelist:
+
+Migrate plugins with fields removed via `subtypes_excludelist`
+==============================================================
+
+Many extension author used the now deprecated option
+:confval:`types-subtypes-excludelist` to hide these automatically added fields.
+
+The same effect can now be used by simply not adding the fields in the first
+place:
+
+..  literalinclude:: _CodeSnippets/_subtype_plugin_exclude_migration.diff
+    :caption: EXT:my_extension/Configuration/Overrides/tt_content.php
+
+If any other fields have been removed with this method you can only remove
+them by overriding
+:confval:`$GLOBALS['TCA']['tt_content']['types'][$pluginSignature]['showitem'] <types-showitem>`
+or via page TSconfig.
+
+..  _migration-subtype-custom:
+
+Migrate custom tables using subtypes
+====================================
+
+Replace any :confval:`types-subtype-value-field` configuration with dedicated record
+types. Please also consider migrating corresponding :confval:`types-subtypes-addlist`
+and :confval:`types-subtypes-excludelist` definitions accordingly.
+
+..  literalinclude:: _CodeSnippets/_subtype_plugin_exclude_migration.diff
+    :caption: EXT:my_extension/Configuration/TCA/tx_myextension_mytable.php
+
+..  _types-example-previewRenderer-for-subtype:
+..  _migration-subtype-previewrenderer:
+
+Migration: PreviewRenderer for subtypes
+=======================================
+
+When migrating a plugin with a PreviewRenderer from `list_type` registration to
+its own `CType` change the PreviewRenderer configuration to the record type as
+well:
+
+..  literalinclude:: _CodeSnippets/_subtype_migration_preview.diff
+    :caption: EXT:my_extension/Configuration/Overrides/tt_content.php

Documentation/Types/_CodeSnippets/_subtype_migration.diff

@@ -0,0 +1,48 @@
+ 'ctrl' => [
+         'type' => 'type',
+ ],
+ 'columns' => [
+     'type' => [
+         'config' => [
+             'type' => 'select',
+             'renderType' => 'selectSingle',
+             'items' => [
+                 [
+                     'label' => 'A record type',
+                     'value' => 'a_record_type'
+                 ],
++                [
++                    'label' => 'A sub type',
++                    'value' => 'a_sub_type'
++                ],
+             ]
+         ]
+     ],
+-    'subtype' => [
+-        'config' => [
+-            'type' => 'select',
+-            'renderType' => 'selectSingle',
+-            'items' => [
+-                [
+-                    'label' => 'A sub type',
+-                    'value' => 'a_sub_type'
+-                ]
+-            ]
+-        ]
+-    ],
+ ],
+ 'types' => [
+     'a_record_type' => [
+         'showitem' => 'aField,bField',
+-        'subtype_value_field' => 'subtype',
+-        'subtypes_addlist' => [
+-            'a_sub_type' => 'pi_flexform'
+-        ],
+-        'subtypes_excludelist' => [
+-            'a_sub_type' => 'bField'
+-         ],
+     ],
++    'a_sub_type' => [
++        'showitem' => 'aField,pi_flexform'
++    ]
+ ]

Documentation/Types/_CodeSnippets/_subtype_migration_preview.diff

@@ -0,0 +1,9 @@
+ $pluginSignature = ExtensionUtility::registerPlugin(
+     'blog_example',
+     'Pi1',
+     'A Blog Example',
+ );
+-$GLOBALS['TCA']['tt_content']['types']['list_type']['previewRenderer'][$pluginSignature]
+-        = \MyVendor\MyExtension\Preview\PreviewRenderer::class;
++$GLOBALS['TCA']['tt_content']['types'][$pluginSignature]['previewRenderer']
++        = \MyVendor\MyExtension\Preview\PreviewRenderer::class;

Documentation/Types/_CodeSnippets/_subtype_plugin_exclude_migration.diff

@@ -0,0 +1,7 @@
+ $pluginSignature = ExtensionUtility::registerPlugin(
+     'blog_example',
+     'Pi1',
+     'A Blog Example',
+ );
+-$GLOBALS['TCA']['tt_content']['types']['list']['subtypes_excludelist'][$pluginSignature]
+-    = 'pages,recursive';

Documentation/Types/_CodeSnippets/_subtype_plugin_migration.diff

@@ -0,0 +1,20 @@
+ $pluginSignature = ExtensionUtility::registerPlugin(
+     'blog_example',
+     'Pi1',
+     'A Blog Example',
+ );
+-$GLOBALS['TCA']['tt_content']['types']['list']['subtypes_addlist'][$pluginSignature]
+-    = 'pi_flexform';
+
++ExtensionManagementUtility::addToAllTCAtypes(
++    'tt_content',
++    '--div--;Configuration,pi_flexform,pages,recursive,',
++    $pluginSignature,
++    'after:subheader',
++);
+ ExtensionManagementUtility::addPiFlexFormValue(
+-    $pluginSignature,
++    '*',
+     'FILE:EXT:blog_example/Configuration/FlexForms/PluginSettings.xml',
++    $pluginSignature,
+ );

Documentation/Types/_Examples/_60_PreviewRenderer.rst.txt

@@ -1,12 +1,16 @@
 ..  _types-example-previewRenderer:
+..  _types-example-previewRenderer-for-type:
 
 PreviewRenderer examples
 ------------------------
 
-..  _types-example-previewRenderer-for-type:
+..  deprecated:: 13.4
+    Registration of subtypes has been deprecated.  Registration of custom
+    types should therefore always be done by using
+    :confval:`record types <ctrl-type>`.
 
-Table has a `type` field/attribute
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    If you used PreviewRenderer with a subtype see section
+    :ref:`migration-subtype-previewrenderer`.
 
 Demonstrates property: :confval:`types-previewRenderer`.
 
@@ -15,29 +19,5 @@ determined by the :ref:`type field <types>` of your table.
 
 ..  code-block:: php
 
-    $GLOBALS['TCA']['tx_myextension_domain_model_mytable']['types'][$type]['previewRenderer']
+    $GLOBALS['TCA']['tt_content']['types'][$type]['previewRenderer']
         = \MyVendor\MyExtension\Preview\PreviewRenderer::class;
-
-..  _types-example-previewRenderer-for-subtype:
-
-Table has a `subtype_value_field` setting
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Demonstrates property: :confval:`types-previewRenderer`.
-
-If your table and field have a
-:ref:`subtype_value_field <types-properties-subtype-value-field>` TCA setting
-(like :sql:`tt_content.list_type`) and you want to register a preview renderer
-that applies only when that value is selected (for example, when a certain
-plugin type is selected and you can not match it with the type of the record
-alone):
-
-
-..  code-block:: php
-
-    $GLOBALS['TCA'][tx_myextension_domain_model_mytable]['types'][$type]['previewRenderer'][$subType]
-        = \MyVendor\MyExtension\Preview\PreviewRenderer::class;
-
-Where :php:`$type` is for example :php:`list` (indicating a plugin) and
-:php:`$subType` is the value of the :php:`list_type` field when the
-type of plugin you want to target is selected as plugin type.

Documentation/Types/_Properties/_PreviewRenderer.rst.txt

@@ -6,6 +6,13 @@
     :Scope: Display
     :Examples: `types-example-previewRenderer`
 
+    ..  deprecated:: 13.4
+        Registration of subtypes has been deprecated.  Registration of custom
+        types should therefore always be done by using
+        :confval:`record types <ctrl-type>`.
+
+        See also :ref:`migration-subtype-previewrenderer`.
+
     To configure a preview renderer for the whole table see
     :confval:`ctrl-previewRenderer`.
 

Documentation/Types/_Properties/_SubtypeValueField.rst.txt

@@ -4,7 +4,13 @@
     :name: types-subtype-value-field
     :Path: $GLOBALS['TCA'][$table]['types'][$type]
     :type: string (field name)
-    :Example: :ref:`types-example-subtypes-remove-types`
+
+    ..  deprecated:: 13.4
+        Registration of subtypes has been deprecated.  Registration of custom
+        types should therefore always be done by using
+        :confval:`record types <ctrl-type>`. See also :ref:`migration-subtype`.
+
+        See also :ref:`migration-subtype`.
 
     Field name, which holds a value being a key in the
     :confval:`types-subtypes-excludelist` array.