[TASK] Deprecate plugin content element and plugin subtypes (list_type)

Depends on TYPO3-Documentation/TYPO3CMS-Reference-TCA#1183

Resolves: TYPO3-Documentation/Changelog-To-Doc#1071

Releases: main

Documentation/ApiOverview/ContentElements/ContentElementsWizard.rst

@@ -64,7 +64,7 @@ the available groups.
 Plain content elements or plugins
 =================================
 
-You can add a content element or plain plugin (non-extbase) using method
+You can add a content element or plain plugin (non-Extbase) using method
 `ExtensionManagementUtility::addPlugin() <https://api.typo3.org/main/classes/TYPO3-CMS-Core-Utility-ExtensionManagementUtility.html#method_addPlugin>`__:
 of class :php:`\TYPO3\CMS\Core\Utility\ExtensionManagementUtility`.
 
@@ -74,11 +74,12 @@ of class :php:`\TYPO3\CMS\Core\Utility\ExtensionManagementUtility`.
 The key `value` in the parameter `$itemArray` is used as key of the newly added
 content element representing the plugin.
 
-When you are using `CType` (recommended) for parameter `$type` the content
+When you are using `CType` for parameter `$type` the content
 element is added to the select item list of column `CType` in table `tt_content`.
 
-If you are using the default `list_type` for the parameter it is added as
-subtype.
+..  deprecated:: 13.4
+    Using the default `list_type` for the parameter is deprecated. All content
+    elements and plugins should be added as sing `CType` for parameter `$type`.
 
 This method supplies some default values:
 

Documentation/ApiOverview/ContentElements/CustomBackendPreview.rst

@@ -118,23 +118,12 @@ approaches:
     This specifies the preview renderer only for records of type :php:`$type` as
     determined by the :ref:`type field <t3tca:types>` of your table.
 
-#.  Table and field have a :php:`subtype_value_field` TCA setting
+..  deprecated:: 13.4
+    Registration of subtypes has been deprecated.  Registration of custom
+    types should therefore always be done by using
+    :confval:`record types <t3tca:ctrl-type>`.
 
-    If your table and field have a
-    :ref:`subtype_value_field <t3tca:types-properties-subtype-value-field>` TCA
-    setting (like :php:`tt_content.list_type` for example) and you want to
-    register a preview renderer that applies only when that value is selected
-    (assume, when a certain plugin type is selected and you can't match it with
-    the "type" of the record alone):
-
-    ..  code-block:: php
-
-        $GLOBALS['TCA'][$table]['types'][$type]['previewRenderer'][$subType]
-            = MyVendor\MyExtension\Preview\MyPreviewRenderer::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.
+    See also :ref:`t3tca:migration-subtype-previewrenderer`.
 
 ..  note::
     The :ref:`recommended location <extension-configuration-tca>` is in the

Documentation/ApiOverview/ContentElements/Index.rst

@@ -19,6 +19,7 @@ created, how existing content elements or plugins can be customized etc.
     CustomBackendPreview
     ContentElementsWizard
     BestPractices
+    MigrationListType
 
 ..  _cePluginsIntroduction:
 
@@ -143,8 +144,9 @@ An Extbase plugin is configured for the frontend with
 ..  literalinclude:: _Plugins/_ext_localconf_extbase_plugin.php
     :caption: EXT:my_extension/ext_localconf.php
 
-By using `ExtensionUtility::PLUGIN_TYPE_PLUGIN` as fifth parameter is is also
-possible to add the plugin as a list type. See :ref:`plugins-list_type`.
+..  deprecated:: 13.4
+    Setting the fifth parameter to any value but `ExtensionUtility::PLUGIN_TYPE_PLUGIN`
+    is deprecated. See :ref:`plugins-list_type-migration`.
 
 Method :php:`ExtensionUtility::configurePlugin()` also takes care of registering
 the plugin for frontend output in TypoScript using an object of type
@@ -183,12 +185,9 @@ To register such a plugin as content element you can use function
 ..  literalinclude:: _Plugins/_tt_content_plugin.php
     :caption: EXT:my_extension/Configuration/TCA/Overrides/tt_content.php
 
-By using `'list_type'` as second parameter is is also possible to add the plugin
-as a list type. See :ref:`plugins-list_type`.
-
-**Plugins** are a specific type of content elements. Plugins use the CType='list'.
-Each plugin has its own plugin type, which is used in the database field
-tt_content.list_type. The list_type could be understood as subtype of CType.
+..  deprecated:: 13.4
+    Setting the second parameter to any value but `CType`
+    is deprecated. See :ref:`plugins-list_type-migration`.
 
 ..  _plugins-characteristics:
 
@@ -215,32 +214,6 @@ has a plugin that allow frontend users, stored in table `fe_users` to log into
 the website. :composer:`typo3/cms-indexed-search` has a plugin that can be
 used to search in the index and display search results.
 
-..  _plugins-list_type:
-
-CType vs list_type plugins
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Historically it was common to add plugins as a list type to the content element
-types. In this case the column `CType` is set to `'list'` for all plugins while
-the field `list_type` contains the key of the actual plugin.
-
-As different plugins need different fields in the backend form this let to
-the creation of all type of complicated TCA constructs to influence the
-behaviour of backend forms for plugins.
-
-The existence of the `list_type` also made a separate layer of content element
-definitions in the TypoScript necessary.
-
-Therefore the `list_type` complicates registration and configuration of plugins
-while it poses no advantages. Therefore it is recommended to always use the
-CType for new plugin types while the `list_type` is retained for now for
-backward compatibility.
-
-If you are refactoring the plugins of your extension, for example while getting
-rid of switchable controller actions it is recommended to migrate your plugins
-to use the CType. You should then supply a
-:ref:`upgrade wizard <upgrade-wizard-examples-switchable-controller-actions>`
-for easy migration for your users.
 
 ..  _plugins-editing:
 

Documentation/ApiOverview/ContentElements/MigrationListType.rst

@@ -0,0 +1,120 @@
+..  include:: /Includes.rst.txt
+..  _plugins-list-type:
+..  _plugins-list-type-migration:
+
+=========================================
+Migration: `list_type` plugins to `CType`
+=========================================
+
+..  deprecated:: 13.4
+    The plugin content element (:php:`list`) and the plugin sub types
+    field (:php:`list_type`) have been marked as deprecated in TYPO3 v13.4 and
+    will be removed in TYPO3 v14.0.
+
+Several steps are important in the migration from `list_type` plugins to `CType`
+plugins:
+
+*   Register plugins using the `CType` record type
+*   Create update wizard which extends :php:`\TYPO3\CMS\Install\Updates\AbstractListTypeToCTypeUpdate`
+    and add :php:`list_type` to :php:`CType` mapping for each plugin to migrate.
+*   Migrate possible FlexForm registration and add dedicated :php:`showitem` TCA
+    configuration
+*   Migrate possible PreviewRenderer registration in TCA
+*   Adapt possible content element wizard items in Page TSConfig, where
+    :php:`list_type` is used
+*   Adapt possible content element restrictions in backend layouts or container
+    elements defined by third-party extensions like ext:content_defender
+
+..  contents:: Table of content
+
+..  _plugins-list-type-migration-extbase:
+
+Migration example: Extbase plugin
+=================================
+
+..  _plugins-list-type-migration-extbase-configuration:
+
+1. Adjust the Extbase plugin configuration
+------------------------------------------
+
+Extbase plugins are usually registered using the utility method
+:php:`\TYPO3\CMS\Extbase\Utility\ExtensionUtility::configurePlugin()` in file
+:file:`EXT:my_extension/ext_localconf.php`.
+
+Add value `ExtensionUtility::PLUGIN_TYPE_CONTENT_ELEMENT` as fifth parameter,
+`$pluginType`, to the method :php:`ExtensionUtility::configurePlugin()`:
+
+..  literalinclude:: _Migration/_ext_localconf.php.diff
+    :caption: EXT:examples/ext_localconf.php (difference)
+
+If the fourth parameter, `$nonCacheableControllerActions` was missing you can
+set it to an empty array, the default value.
+
+It is theoretically possible that the extension author did not use this utility
+method. In that case you have to change the TypoScript used to display your
+plugin manually. This step is similar to adjusting the TypoScript of a
+Core-based plugin.
+
+..  _plugins-list-type-migration-extbase-flexform:
+
+2. Adjust the registration of FlexForms and additional fields
+-------------------------------------------------------------
+
+..  literalinclude:: _Migration/_tca_registration.php.diff
+    :caption: EXT:examples/Configuration/TCA/Overrides/tt_content.php (difference)
+
+The `CType` based plugin does not inherit the standard fields provided by the
+TCA of the content-element "List". These where in many cases removed by
+using :confval:`subtypes_excludelist <t3tca:types-subtypes-excludelist>`.
+
+As these fields are not displayed automatically anymore you can remove this
+definition without replacement: Line 15 in the diff. If they have not been
+removed and still needed you need to add them manually to your plugins type.
+
+The :confval:`subtypes_addlist <t3tca:types-subtypes-addlist>` was used to
+display the field containing the FlexForm, an possibly other fields in the
+`list_type` plugin. We remove this definition (Line 17) and replace it
+by using the utility method
+:php:`\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addToAllTCAtypes()`
+(Line 25-30).
+
+The utility method :php:`ExtensionManagementUtility::addPiFlexFormValue()`
+needs to be changed from using the first parameter for the `$pluginSignature`
+to using the third parameter. The first parameter requires a certain `list_type`
+setting it to the wildcard `*` allows all list types. The third parameter limits
+it to the `CType`.
+
+..  _plugins-list-type-migration-extbase-upgrade-wizard:
+
+3. Provide an upgrade wizard
+----------------------------
+
+..  versionadded:: 13.4
+
+You can extend class :php-short:`TYPO3\CMS\Install\Updates\AbstractListTypeToCTypeUpdate`
+to provide a custom upgrade wizard that moves existing plugins from the
+`list_type` definition to the `CType` definition. The resulting upgrade wizard
+will even adjust backend user permissions for the defined plugins:
+
+..  include:: /CodeSnippets/Extbase/Upgrades/ExtbasePluginListTypeToCTypeUpdate.rst.txt
+
+..  _plugins-list-type-migration-extbase-replace:
+
+4. Search your code and replace any mentioning of `list_type`
+-------------------------------------------------------------
+
+Search your code. If you used the `list_type` of you plugin in any custom
+database statement or referred to the according
+
+Search your TCA definitions for any use of the now outdated configuration
+options
+
+..  _plugins-list-type-migration-core:
+
+Migration example: Core-based plugin
+====================================
+
+..  _plugins-list-type-migration-core-registration:
+
+1.  Adjust the plugin registration
+==================================

Documentation/ApiOverview/ContentElements/_Migration/_ext_localconf.php.diff

@@ -0,0 +1,13 @@
+ use T3docs\Examples\Controller\FalExampleController;
+ use TYPO3\CMS\Extbase\Utility\ExtensionUtility;
+
+ ExtensionUtility::configurePlugin(
+     'Examples',
+     'FalExamples',
+        'HtmlParser',
+        [
+            HtmlParserController::class => 'index',
+        ],
++       [],
++    ExtensionUtility::PLUGIN_TYPE_CONTENT_ELEMENT,
+ );

Documentation/ApiOverview/ContentElements/_Migration/_tca_registration.php.diff

@@ -0,0 +1,36 @@
+ use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
+ use TYPO3\CMS\Extbase\Utility\ExtensionUtility;
+
+ $extensionKey = 'Examples';
+ $pluginName = 'HtmlParser';
+ $pluginTitle = 'LLL:EXT:examples/Resources/Private/Language/locallang.xlf:htmlparser_plugin_title';
+
+ // Register the HTML Parser plugin
+ $pluginSignature = ExtensionUtility::registerPlugin(
+     $extensionKey,
+     $pluginName,
+     $pluginTitle,
+ );
+
+-$GLOBALS['TCA']['tt_content']['types']['list']['subtypes_excludelist'][$pluginSignature]
+-    = 'layout,select_key,pages';
+-$GLOBALS['TCA']['tt_content']['types']['list']['subtypes_addlist'][$pluginSignature]
+-    = 'pi_flexform';
+-
+-ExtensionManagementUtility::addPiFlexFormValue(
+-    $pluginSignature,
+-    'FILE:EXT:examples/Configuration/Flexforms/HtmlParser.xml',
+-);
+
++ExtensionManagementUtility::addToAllTCAtypes(
++    'tt_content',
++    '--div--;Configuration,pi_flexform,',
++    $pluginSignature,
++    'after:subheader',
++);
++
++ExtensionManagementUtility::addPiFlexFormValue(
++    '*',
++    'FILE:EXT:examples/Configuration/Flexforms/HtmlParser.xml',
++    $pluginSignature,
++);

Documentation/CodeSnippets/Config/ExtensionDevelopment/Extbase.php

@@ -1,5 +1,7 @@
 <?php
 
+use T3docs\Examples\Upgrades\ExtbasePluginListTypeToCTypeUpdate;
+
 return [
     [
         'action' => 'createCodeSnippet',
@@ -341,4 +343,11 @@
         'targetFileName' => 'CodeSnippets/Extbase/UriBuilder.rst.txt',
         'withCode' => false,
     ],
+    [
+        'action' => 'createPhpClassCodeSnippet',
+        'class' => ExtbasePluginListTypeToCTypeUpdate::class,
+        'withComment' => true,
+        'withClassComment' => false,
+        'targetFileName' => 'CodeSnippets/Extbase/Upgrades/ExtbasePluginListTypeToCTypeUpdate.rst.txt',
+    ],
 ];

Documentation/CodeSnippets/Extbase/Upgrades/ExtbasePluginListTypeToCTypeUpdate.rst.txt

@@ -0,0 +1,10 @@
+..  Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets
+..  Extracted from T3docs\Examples\Upgrades\ExtbasePluginListTypeToCTypeUpdate
+
+..  code-block:: php
+    :caption: Class T3docs\\Examples\\Upgrades\\ExtbasePluginListTypeToCTypeUpdate
+
+    final class ExtbasePluginListTypeToCTypeUpdate extends AbstractListTypeToCTypeUpdate
+    {
+
+    }

Documentation/CodeSnippets/FlexForms/Examples/PluginHaikuListRegistration.rst.txt

@@ -11,6 +11,7 @@
      * This file is part of the TYPO3 CMS project. [...]
      */
 
+    use TYPO3\CMS\Core\Schema\Struct\SelectItem;
     use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
 
     /*
@@ -19,21 +20,30 @@
 
     defined('TYPO3') or die();
 
+    $pluginSignature = 'examples_haiku_list';
+
     ExtensionManagementUtility::addPlugin(
-        [
+        new SelectItem(
+            'select',
             'LLL:EXT:examples/Resources/Private/Language/PluginHaiku/locallang_db.xlf:list.title',
-            'examples_haiku_list',
+            $pluginSignature,
             'tx_examples-haiku',
-        ],
-        'list_type',
+            'plugins',
+            'LLL:EXT:examples/Resources/Private/Language/PluginHaiku/locallang_db.xlf:list.description',
+        ),
+        'CType',
         'examples',
     );
 
-    $GLOBALS['TCA']['tt_content']['types']['list']['subtypes_excludelist']['examples_haiku_list'] = 'pages,layout,select_key,recursive';
-
-    $GLOBALS['TCA']['tt_content']['types']['list']['subtypes_addlist']['examples_haiku_list'] = 'pi_flexform';
+    ExtensionManagementUtility::addToAllTCAtypes(
+        'tt_content',
+        '--div--;Configuration,pi_flexform,',
+        $pluginSignature,
+        'after:subheader',
+    );
 
     ExtensionManagementUtility::addPiFlexFormValue(
-        'examples_haiku_list',
+        '*',
         'FILE:EXT:examples/Configuration/Flexforms/PluginHaikuList.xml',
+        $pluginSignature,
     );