[TASK] Overhaul palettes (#986)

* Correct indentation, * add names for confvals * transfer code-blocks to new syntax releases: main, 12.4, 11.5
TYPO3-Documentation · Mar 26, 2024 · 15db97d · 15db97d
1 parent 53ae429
commit 15db97d
Show file tree

Hide file tree

Showing 7 changed files with 127 additions and 110 deletions.
diff --git a/Documentation/Palettes/Examples.rst b/Documentation/Palettes/Examples.rst
@@ -1,23 +1,23 @@
-.. include:: /Includes.rst.txt
-.. _palettes-examples:
+..  include:: /Includes.rst.txt
+..  _palettes-examples:
 
 ========
 Examples
 ========
 
 The TCA of the styleguide extension provides palettes with different properties.
 
-.. include:: /Images/Rst/Palette.rst.txt
+..  include:: /Images/Rst/Palette.rst.txt
 
 Palettes get defined in the section :php:`palettes` of the tables TCA array.
 
 The following TCA section specifies the different palettes.
 
-.. include:: /CodeSnippets/Palettes.rst.txt
+..  include:: /CodeSnippets/Palettes.rst.txt
 
 The palettes then get referenced in the :php:`types` section:
 
-.. include:: /CodeSnippets/PalettesTypes.rst.txt
+..  include:: /CodeSnippets/PalettesTypes.rst.txt
 
 
 
@@ -29,7 +29,11 @@ specific label in the 'types' array for a palette overrides the default label
 that was defined within the 'palettes' array. There is no way to unset a label
 that is set within the 'palettes' array. It will always be displayed.
 
-Example::
+Example:
+
+
+..  code-block:: php
+    :caption: EXT:my_extension/Configuration/TCA/tx_myextension_table.php (Excerpt)
 
    'types' => [
       'myType' => [

diff --git a/Documentation/Palettes/Index.rst b/Documentation/Palettes/Index.rst
@@ -1,6 +1,6 @@
-.. include:: /Includes.rst.txt
+..  include:: /Includes.rst.txt
 
-.. _palettes:
+..  _palettes:
 
 ==========================
 Grouping fields (palettes)
@@ -14,12 +14,12 @@ group multiple related fields in one combined section.
 Each palette has a name and can be referenced by name from within the
 :ref:`['types'] section <types>`.
 
-To modify existing palettes you can use the utility functions 
-:php:`\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addFieldsToPalette` and 
+To modify existing palettes you can use the utility functions
+:php:`\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addFieldsToPalette` and
 :php:`ExtensionManagementUtility::addFieldsToAllPalettesOfField`.
 
 
-.. toctree::
+..  toctree::
 
-   Examples
-   Properties/Index
+    Examples
+    Properties/Index
diff --git a/Documentation/Palettes/Properties/Description.rst b/Documentation/Palettes/Properties/Description.rst
@@ -1,33 +1,33 @@
-.. include:: /Includes.rst.txt
-.. _palettes-properties-description:
+..  include:: /Includes.rst.txt
+..  _palettes-properties-description:
 
 ===========
 description
 ===========
 
-.. versionadded:: 11.3
-   The palettes description property has been added with TYPO3 v11.3.
+..  versionadded:: 11.3
+    The palettes description property has been added with TYPO3 v11.3.
 
-.. confval:: description (palettes)
+..  confval:: description
+    :name: palettes-description
+    :Path: $GLOBALS['TCA'][$table]['palettes']
+    :type: string
 
-   :Path: $GLOBALS['TCA'][$table]['palettes']
-   :type: string
+    Allows to display a localized description text into the palette declaration.
+    It will be displayed below the
+    :ref:`palette label<palettes-properties-label>`.
 
-   Allows to display a localized description text into the palette declaration.
-   It will be displayed below the
-   :ref:`palette label<palettes-properties-label>`.
+    This additional help text can be used to clarify some field usages directly
+    in the UI.
 
-   This additional help text can be used to clarify some field usages directly
-   in the UI.
+    ..  note::
 
-   .. note::
-
-      In contrast to the palette label, the description property can not
-      be overwritten on a record type basis.
+        In contrast to the palette label, the description property can not
+        be overwritten on a record type basis.
 
 Example
 =======
 
-.. include:: /Images/Rst/PaletteDescription.rst.txt
+..  include:: /Images/Rst/PaletteDescription.rst.txt
 
-.. include:: /CodeSnippets/PaletteDescription.rst.txt
+..  include:: /CodeSnippets/PaletteDescription.rst.txt
diff --git a/Documentation/Palettes/Properties/Index.rst b/Documentation/Palettes/Properties/Index.rst
@@ -1,14 +1,14 @@
-.. include:: /Includes.rst.txt
-.. _palettes-properties:
+..  include:: /Includes.rst.txt
+..  _palettes-properties:
 
 ==========
 Properties
 ==========
 
 
-.. toctree::
+..  toctree::
 
-   IsHiddenPalette
-   Label
-   Description
-   Showitem
+    IsHiddenPalette
+    Label
+    Description
+    Showitem
diff --git a/Documentation/Palettes/Properties/IsHiddenPalette.rst b/Documentation/Palettes/Properties/IsHiddenPalette.rst
@@ -1,27 +1,27 @@
-.. include:: /Includes.rst.txt
+..  include:: /Includes.rst.txt
 
 ===============
 isHiddenPalette
 ===============
 
-.. confval:: isHiddenPalette
+..  confval:: isHiddenPalette
+    :name: palettes-isHiddenPalette
+    :Path: $GLOBALS['TCA'][$table]['palettes']
+    :type: boolean
 
-   :Path: $GLOBALS['TCA'][$table]['palettes']
-   :type: boolean
+    If set to true, this palette will never be shown, but the fields of the palette are technically
+    rendered as hidden elements in FormEngine.
 
-   If set to true, this palette will never be shown, but the fields of the palette are technically
-   rendered as hidden elements in FormEngine.
+    This is sometimes useful when you want to set a field's value by JavaScript from another user-defined field.
+    You can also use it along with the IRRE (TCA columns type :ref:`inline <columns-inline>`)
+    :ref:`foreign_selector <columns-inline-properties-foreign-selector>` feature if you don't want the relation
+    field to be displayed (it must be technically present and rendered though, that's why you should put it to
+    a hidden palette in that case).
 
-   This is sometimes useful when you want to set a field's value by JavaScript from another user-defined field.
-   You can also use it along with the IRRE (TCA columns type :ref:`inline <columns-inline>`)
-   :ref:`foreign_selector <columns-inline-properties-foreign-selector>` feature if you don't want the relation
-   field to be displayed (it must be technically present and rendered though, that's why you should put it to
-   a hidden palette in that case).
-
-   .. note::
-      The "isHiddenPalette" concept is more a hack than a solution in current FormEngine code. It has been
-      introduced for the "FAL" file resource handling to have virtual fields which can be handled in JavaScript
-      but are not displayed to the editor. It comes with the price of a bunch of HTML that is disabled
-      via CSS if editing those records in the backend. The core will sooner or later reconsider this solution
-      and substitute it with something more appropriate. Extension authors should stay away from this property
-      if possible to not run into upgrade troubles if that happens.
+    ..  note::
+        The "isHiddenPalette" concept is more a hack than a solution in current FormEngine code. It has been
+        introduced for the "FAL" file resource handling to have virtual fields which can be handled in JavaScript
+        but are not displayed to the editor. It comes with the price of a bunch of HTML that is disabled
+        via CSS if editing those records in the backend. The core will sooner or later reconsider this solution
+        and substitute it with something more appropriate. Extension authors should stay away from this property
+        if possible to not run into upgrade troubles if that happens.
diff --git a/Documentation/Palettes/Properties/Label.rst b/Documentation/Palettes/Properties/Label.rst
@@ -1,43 +1,49 @@
-.. include:: /Includes.rst.txt
-.. _palettes-properties-label:
+..  include:: /Includes.rst.txt
+..  _palettes-properties-label:
 
 =====
 label
 =====
 
-.. confval:: label (palettes)
+..  confval:: label
+    :name: palettes-label
+    :Path: $GLOBALS['TCA'][$table]['palettes']
+    :type: string
 
-   :Path: $GLOBALS['TCA'][$table]['palettes']
-   :type: string
+    Allows to display a localized label text as a dedicated entry into the palette declaration, instead as a part of
+    the types configuration.
+    By using the explicit label entry, code duplication upon reusing existing palettes can be reduced. The label is
+    always shown with the palette, no matter where it is referenced.
 
-   Allows to display a localized label text as a dedicated entry into the palette declaration, instead as a part of
-   the types configuration.
-   By using the explicit label entry, code duplication upon reusing existing palettes can be reduced. The label is
-   always shown with the palette, no matter where it is referenced.
+    Before:
 
-   Before::
+    ..  code-block:: php
+        :caption: EXT:my_extension/Configuration/TCA/tx_myextension_table.php (Excerpt)
 
-         'types' => [
+        'types' => [
             'myType' => [
-               'showitem' => 'aField, --palette--;LLL:EXT:myExt/Resources/Private/Language/locallang.xlf:aPaletteDescription;aPalette, someOtherField',
+                'showitem' => 'aField, --palette--;LLL:EXT:myExt/Resources/Private/Language/locallang.xlf:aPaletteDescription;aPalette, someOtherField',
             ],
-         ],
-         'palettes' => [
+        ],
+        'palettes' => [
             'aPalette' => [
-               'showitem' => 'aFieldInAPalette, anotherFieldInPalette',
+                'showitem' => 'aFieldInAPalette, anotherFieldInPalette',
             ],
-         ],
+        ],
 
-   After::
+    After:
 
-         'types' => [
+    ..  code-block:: php
+        :caption: EXT:my_extension/Configuration/TCA/tx_myextension_table.php (Excerpt)
+
+        'types' => [
             'myType' => [
-               'showitem' => 'aField, --palette--;;aPalette, someOtherField',
+                'showitem' => 'aField, --palette--;;aPalette, someOtherField',
             ],
-         ],
-         'palettes' => [
+        ],
+        'palettes' => [
             'aPalette' => [
-               'label' => 'LLL:EXT:myExt/Resources/Private/Language/locallang.xlf:aPaletteDescription',
-               'showitem' => 'aFieldInAPalette, anotherFieldInPalette',
+                'label' => 'LLL:EXT:myExt/Resources/Private/Language/locallang.xlf:aPaletteDescription',
+                'showitem' => 'aFieldInAPalette, anotherFieldInPalette',
             ],
-         ],
+        ],
diff --git a/Documentation/Palettes/Properties/Showitem.rst b/Documentation/Palettes/Properties/Showitem.rst
@@ -1,34 +1,41 @@
-.. include:: /Includes.rst.txt
-.. _palettes-properties-showitem:
-.. _palettes-linebreaks:
-.. _palettes-linebreaks-examples:
+..  include:: /Includes.rst.txt
+..  _palettes-properties-showitem:
+..  _palettes-linebreaks:
+..  _palettes-linebreaks-examples:
 
 ========
 showitem
 ========
 
-.. confval:: showitem (palettes)
-
-   :Path: $GLOBALS['TCA'][$table]['palettes']
-   :Required: true
-   :type: string (list of field names)
-
-   Specifies which fields are displayed in which order in the palette,
-   examples::
-
-      'showitem' => 'aFieldName, anotherFieldName',
-      'showitem' => 'aFieldName;labelOverride, anotherFieldName',
-      'showitem' => 'aFieldName, anotherFieldName, --linebreak--, yetAnotherFieldName',
-
-   This string is a comma separated list of field names from :ref:`['columns'] section <columns>`, each field can
-   optionally have a second, semicolon separated field to override the default :ref:`label <columns-properties-label>`
-   property of the field.
-
-   Instead of a field name, the special keyword `--linebreak--` can be used to place groups of fields on
-   single lines. Note this line grouping only works well if the browser window size allows multiple fields
-   next to each other, if the width is not sufficient the fields will wrap below each other anyways.
-
-   .. caution::
-      A field name must only appear once in the entire record. Do not reference a single field within
-      the showitem list of a types section and again in a palette used in the same type. Don't use
-      a field in multiple palettes referenced in a type, or multiple times in one palette.
+..  confval:: showitem
+    :name: palettes-showitem
+    :Path: $GLOBALS['TCA'][$table]['palettes']
+    :Required: true
+    :type: string (list of field names)
+
+    Specifies which fields are displayed in which order in the palette,
+    examples:
+
+    ..  code-block:: php
+        :caption: EXT:my_extension/Configuration/TCA/tx_myextension_table.php (Excerpt)
+
+        [
+            'showitem' => 'aFieldName, anotherFieldName',
+            'showitem' => 'aFieldName;labelOverride, anotherFieldName',
+            'showitem' => 'aFieldName, anotherFieldName, --linebreak--, yetAnotherFieldName',
+        ]
+
+    This string is a comma separated list of field names from :ref:`['columns'] section <columns>`, each field can
+    optionally have a second, semicolon separated field to override the default :ref:`label <columns-properties-label>`
+    property of the field.
+
+    Instead of a field name, the special keyword `--linebreak--` can be used to place groups of fields on
+    single lines. Note this line grouping only works well if the browser window size allows multiple fields
+    next to each other, if the width is not sufficient the fields will wrap below each other anyways.
+
+    ..  caution::
+        A field name must only appear once in the entire record. Do not reference
+        a single field within the :ref:`showitem <types-properties-showitem>`
+        list of a types section and again in a palette used in the same type.
+        Do not use a field in multiple palettes referenced in a type, or
+        multiple times in one palette.