From 15db97d28a509c4f05fcd2c078941365fd7b8ec9 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Tue, 26 Mar 2024 17:18:30 +0100 Subject: [PATCH] [TASK] Overhaul palettes (#986) * Correct indentation, * add names for confvals * transfer code-blocks to new syntax releases: main, 12.4, 11.5 --- Documentation/Palettes/Examples.rst | 16 +++-- Documentation/Palettes/Index.rst | 14 ++-- .../Palettes/Properties/Description.rst | 36 +++++----- Documentation/Palettes/Properties/Index.rst | 14 ++-- .../Palettes/Properties/IsHiddenPalette.rst | 38 +++++------ Documentation/Palettes/Properties/Label.rst | 54 ++++++++------- .../Palettes/Properties/Showitem.rst | 65 ++++++++++--------- 7 files changed, 127 insertions(+), 110 deletions(-) diff --git a/Documentation/Palettes/Examples.rst b/Documentation/Palettes/Examples.rst index 6ae6e5a3..43324220 100644 --- a/Documentation/Palettes/Examples.rst +++ b/Documentation/Palettes/Examples.rst @@ -1,5 +1,5 @@ -.. include:: /Includes.rst.txt -.. _palettes-examples: +.. include:: /Includes.rst.txt +.. _palettes-examples: ======== Examples @@ -7,17 +7,17 @@ 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 index 5f123958..881c596a 100644 --- 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 `. -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 index 87cb9a21..ab1cb9f4 100644 --- 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`. - Allows to display a localized description text into the palette declaration. - It will be displayed below the - :ref:`palette 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 index 8461080e..ff7ec10b 100644 --- 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 index 88e96590..f08d2a82 100644 --- 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 `) + :ref:`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 `) - :ref:`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 index 312e538b..5b7c7153 100644 --- 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 index dbbc01a5..626f703b 100644 --- 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 `, each field can - optionally have a second, semicolon separated field to override the default :ref:`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 `, each field can + optionally have a second, semicolon separated field to override the default :ref:`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 ` + 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.