diff --git a/Documentation/ApiOverview/ContentElements/ContentElementsWizard.rst b/Documentation/ApiOverview/ContentElements/ContentElementsWizard.rst index 00113450bf..357fa56515 100644 --- a/Documentation/ApiOverview/ContentElements/ContentElementsWizard.rst +++ b/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() `__: 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: diff --git a/Documentation/ApiOverview/ContentElements/CustomBackendPreview.rst b/Documentation/ApiOverview/ContentElements/CustomBackendPreview.rst index 0904eb272b..fa4186a1a5 100644 --- a/Documentation/ApiOverview/ContentElements/CustomBackendPreview.rst +++ b/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 ` 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 `. - If your table and field have a - :ref:`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 ` is in the diff --git a/Documentation/ApiOverview/ContentElements/Index.rst b/Documentation/ApiOverview/ContentElements/Index.rst index a14888be06..9eee3aee3a 100644 --- a/Documentation/ApiOverview/ContentElements/Index.rst +++ b/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 ` -for easy migration for your users. .. _plugins-editing: diff --git a/Documentation/ApiOverview/ContentElements/MigrationListType.rst b/Documentation/ApiOverview/ContentElements/MigrationListType.rst new file mode 100644 index 0000000000..4ac13556cb --- /dev/null +++ b/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 `. + +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 ` 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 +================================== diff --git a/Documentation/ApiOverview/ContentElements/_Migration/_ext_localconf.php.diff b/Documentation/ApiOverview/ContentElements/_Migration/_ext_localconf.php.diff new file mode 100644 index 0000000000..30a641b355 --- /dev/null +++ b/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, + ); diff --git a/Documentation/ApiOverview/ContentElements/_Migration/_tca_registration.php.diff b/Documentation/ApiOverview/ContentElements/_Migration/_tca_registration.php.diff new file mode 100644 index 0000000000..e95861a870 --- /dev/null +++ b/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, ++); diff --git a/Documentation/CodeSnippets/Config/ExtensionDevelopment/Extbase.php b/Documentation/CodeSnippets/Config/ExtensionDevelopment/Extbase.php index 1c0768d81e..8cba6b13a9 100644 --- a/Documentation/CodeSnippets/Config/ExtensionDevelopment/Extbase.php +++ b/Documentation/CodeSnippets/Config/ExtensionDevelopment/Extbase.php @@ -1,5 +1,7 @@ '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', + ], ]; diff --git a/Documentation/CodeSnippets/Extbase/Upgrades/ExtbasePluginListTypeToCTypeUpdate.rst.txt b/Documentation/CodeSnippets/Extbase/Upgrades/ExtbasePluginListTypeToCTypeUpdate.rst.txt new file mode 100644 index 0000000000..ddfb1e793e --- /dev/null +++ b/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 + { + + } diff --git a/Documentation/CodeSnippets/FlexForms/Examples/PluginHaikuListRegistration.rst.txt b/Documentation/CodeSnippets/FlexForms/Examples/PluginHaikuListRegistration.rst.txt index be955ff5d7..a10b4c6cf4 100644 --- a/Documentation/CodeSnippets/FlexForms/Examples/PluginHaikuListRegistration.rst.txt +++ b/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, );