[FEATURE] Auto-add system fields showitem for tt_content (#1165)

* [FEATURE] Auto-add system fields showitem for tt_content

Resolves: TYPO3-Documentation/Changelog-To-Doc#1013
Releases: main

* Apply suggestions from code review

Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com>

* [FEATURE] Auto-add system fields showitem for tt_content

Resolves: TYPO3-Documentation/Changelog-To-Doc#1013
Releases: main

---------

Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com>

Documentation/Types/Index.rst

@@ -20,6 +20,19 @@ programming.
 ..  contents:: Table of Contents
     :depth: 1
 
+..  toctree::
+    :caption: Subpages
+    :glob:
+    :titlesonly:
+
+    *
+
+..  versionchanged:: 13.3
+    Creating content elements has been simplified by removing the need to
+    define the system fields for each element again and again. This shrinks
+    down a content element's :confval:`types-showitem` to just the element
+    specific fields. See also :ref:`types-content`.
+
 ..  _types-introduction:
 
 Introduction

Documentation/Types/TtContent.rst

@@ -0,0 +1,116 @@
+:navigation-title: tt_content system fields
+
+..  include:: /Includes.rst.txt
+
+..  _types-content:
+
+=================================================================
+Automatically added system fields to content types (`tt_content`)
+=================================================================
+
+..  versionchanged:: 13.3
+    Creating content elements has been simplified by removing the need to
+    define the system fields for each element again and again. This shrinks
+    down a content element's :confval:`types-showitem` to just the element
+    specific fields. See also :ref:`Migration <types-content-migration>`.
+    Added with :ref:`changelog:feature-104814-1725444916`.
+
+The following tabs / palettes are added automatically to the :confval:`types-showitem`
+property of table `tt_content`:
+
+*   The :guilabel:`General` tab with the `general` palette at the very beginning
+*   The :guilabel:`Language` tab with the `language` palette after custom fields
+*   The :guilabel:`Access` tab with the `hidden` and `access` palettes
+*   The :guilabel:`Notes` tab with the `rowDescription` field
+
+..  figure:: /Images/ManualScreenshots/tt_content_automatic_tabs.png
+    :alt: The edit form of a slider with its tabs. The above mentioned ones are underlined.
+
+    The underlined tabs are added automatically.
+
+See :ref:`types-content-examples-extended` for an example.
+
+..  note::
+
+    The fields are added to the :confval:`types-showitem` through their corresponding
+    :ref:`palettes <palettes>`. In case such palette has been changed
+    by extensions, the required system fields are added individually to corresponding tabs.
+
+In case one of those palettes has been changed to no longer
+include the corresponding system fields, those fields are added individually
+depending on their definition in the :ref:`ctrl` section.
+
+By default, all custom fields - the ones still defined in :confval:`types-showitem` - are
+added after the `general` palette and are therefore added to the
+:guilabel:`General` tab, unless a custom tab (for example :guilabel:`Plugin`,
+or :guilabel:`Categories`) is defined in between. It's also possible to start
+with a custom tab by defining a `--div--` as the first item in the
+:confval:`types-showitem`. In this case, the :guilabel:`General` tab will be omitted.
+
+All those system fields, which are added based on the :php:`ctrl` section are
+also automatically removed from any custom palette and from the customized
+type's :confval:`types-showitem` definition.
+
+If the content element defines the :guilabel:`Extended` tab, it will be
+inserted at the end, including all fields added to the type via API methods,
+without specifying a position, via
+:php:`\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addToAllTcaTypes()`. See
+:ref:`types-content-examples-extended` for an example.
+
+..  _types-content-examples:
+
+Examples for the `showitems` TCA section in content elements
+============================================================
+
+..  _types-content-examples-basic:
+
+Basic custom content element with header and bodytext
+-----------------------------------------------------
+
+..  literalinclude:: _CodeSnippets/_basic_content_element.php
+    :caption: EXT:my_extension/Configuration/TCA/Overrides/tt_content.php
+
+The following tabs are shown, the header palette and bodytext field are shown
+in palette general:
+
+..  figure:: /Images/ManualScreenshots/tt_content_basic.png
+    :alt: Screenshot of the content element form created by the code
+
+    Screenshot of the content element form created by the code
+
+..  _types-content-examples-extended:
+
+Extended content element with custom fields
+-------------------------------------------
+
+..  literalinclude:: _CodeSnippets/_extended_content_element.php
+    :caption: EXT:my_extension/Configuration/TCA/Overrides/tt_content.php
+
+The following tabs are shown:
+
+..  figure:: /Images/ManualScreenshots/tt_content_extended.png
+    :alt: Screenshot of the content element form created by the code
+
+    Screenshot of the content element form created by the code
+
+Additional fields that are subsequently added to the end of the table using
+:php:`\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addToAllTcaTypes()`
+will appear in the tab :guilabel:`Extended`.
+
+..  _types-content-migration:
+
+Migration: Remove system fields from showitems on dropping TYPO3 v12.4 support
+==============================================================================
+
+It is sufficient to apply changes to the :confval:`types-showitem` section
+of content types once dropping TYPO3 v12.4 support in extensions.
+
+In site packages or extensions only supporting TYPO3 v13.3 or above you can
+migrate the :confval:`types-showitem` right away:
+
+..  literalinclude:: _CodeSnippets/tt_content_migration.diff
+    :caption: EXT:my_extension/Configuration/TCA/Overrides/tt_content.php (diff)
+
+So the tabs :guilabel:`General`, :guilabel:`Language`, :guilabel:`Access`
+and :guilabel:`Notes` are now added automatically together with the
+corresponding system fields.

Documentation/Types/_CodeSnippets/_basic_content_element.php

@@ -0,0 +1,17 @@
+<?php
+
+use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
+
+// Add the content element to the "Type" dropdown
+ExtensionManagementUtility::addTcaSelectItem(
+    'tt_content',
+    'CType',
+    [
+        'label' => 'My extension basic text element',
+        'value' => 'my_extension_basic_text',
+    ],
+);
+
+// Add the predefined fields to the "General" tab
+$GLOBALS['TCA']['tt_content']['types']['my_extension_basic_text']['showitem'] =
+    '--palette--;;headers,bodytext,';

Documentation/Types/_CodeSnippets/_extended_content_element.php

@@ -0,0 +1,58 @@
+<?php
+
+use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
+
+// Add the content element to the "Type" dropdown
+ExtensionManagementUtility::addTcaSelectItem(
+    'tt_content',
+    'CType',
+    [
+        'label' => 'My extension custom text element with links',
+        'value' => 'my_extension_extended-text',
+        'icon' => 'my-extension-content-text',
+        'group' => 'default',
+        'description' => 'Some descripton',
+    ],
+    'textmedia',
+    'after',
+);
+
+// Define some custom columns
+$additionalColumns = [
+    'my_extension_link' => [
+        'label' => 'My link',
+        'config' => [
+            'type' => 'link',
+        ],
+    ],
+    'my_extension_link_text' => [
+        'label' => 'My link text',
+        'config' => [
+            'type' => 'input',
+        ],
+    ],
+    'my_extension_extra_text' => [
+        'label' => 'My extra text',
+        'config' => [
+            'type' => 'input',
+        ],
+    ],
+];
+// Add the custom columns to the TCA of tt_content
+ExtensionManagementUtility::addTCAcolumns('tt_content', $additionalColumns);
+
+// Add predefined and custom fields to the "General tab" and introduce a tab called "Extended"
+$GLOBALS['TCA']['tt_content']['types']['my_extension_extended-text']['showitem'] = '
+    --palette--;;headers,
+    bodytext,
+    --div--;My tab,
+        my_extension_link,
+        my_extension_link_text,
+    --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:extended,';
+
+// This field will be added in tab "Extended"
+ExtensionManagementUtility::addToAllTCAtypes(
+    'tt_content',
+    'my_extension_extra_text',
+    'my_extension_extended-text'
+);

Documentation/Types/_CodeSnippets/tt_content_migration.diff

@@ -0,0 +1,22 @@
+ 'slider' => [
+     'showitem' => '
+-        --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:general,
+-            --palette--;;general,
+             --palette--;;headers,
+             slider_elements,
+             bodytext;LLL:EXT:awesome_slider/Resources/Private/Language/locallang_ttc.xlf:bodytext.ALT.slider_description,
+         --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:appearance,
+             --palette--;;frames,
+             --palette--;;appearanceLinks,
+-        --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:language,
+-            --palette--;;language,
+-        --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:access,
+-            --palette--;;hidden,
+-            --palette--;;access,
+         --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:categories,
+             categories,
+-        --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:notes,
+-            rowDescription,
+         --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:extended,
+     ',
+ ],