[FEATURE] #101843 - Allow configuration of color palettes in FormEngi…

…ne (#383)

Related: TYPO3-Documentation/Changelog-To-Doc#650
Releases: main

Documentation/PageTsconfig/ColorPalettes.rst

@@ -0,0 +1,69 @@
+..  include:: /Includes.rst.txt
+
+..  index::
+    Page TSconfig; colorPalettes
+    colorPalettes
+..  _pagecolorpalettes:
+
+
+=============
+colorPalettes
+=============
+
+..  versionadded:: 13.0
+
+TYPO3 provides a :ref:`color picker component <t3tca:columns-color>` that
+supports color palettes, or swatches. The colors can be configured and assigned
+to palettes. This way, for example, colors defined in a corporate design can
+be made accessible in an easy way. Multiple color palettes can be configured.
+
+..  figure:: /Images/ManualScreenshots/ColorPalettes/ColorPalette.png
+    :alt: Example of a color palette
+    :class: with-shadow
+
+    Example of a color palette
+
+Basic syntax
+============
+
+First, define the colors by name and RGB value:
+
+..  code-block:: typoscript
+    :caption: EXT:my_sitepackage/Configuration/page.tsconfig
+
+    colorPalettes {
+      colors {
+        typo3 {
+          value = #ff8700
+        }
+        blue {
+          value = #0080c9
+        }
+        darkgrey {
+          value = #515151
+        }
+        valid {
+          value = #5abc55
+        }
+        error {
+          value = #dd123d
+        }
+      }
+    }
+
+Then assign the colors to your palettes:
+
+..  code-block:: typoscript
+    :caption: EXT:my_sitepackage/Configuration/page.tsconfig
+
+    colorPalettes {
+      palettes {
+        main = typo3
+        key_colors = typo3, blue, darkgrey
+        messages = valid, error
+      }
+    }
+
+Now you can assign a color palette to one field, to all fields of a table or
+as a global configuration, see
+:ref:`TCEFORM.colorPalette <pageTsConfigTceFormColorPalette>`.

Documentation/PageTsconfig/Index.rst

@@ -1,7 +1,7 @@
-.. include:: /Includes.rst.txt
-.. index:: ! Page TSconfig
-.. _pagetsconfig:
-.. _pagetoplevelobjects:
+..  include:: /Includes.rst.txt
+..  index:: ! Page TSconfig
+..  _pagetsconfig:
+..  _pagetoplevelobjects:
 
 =======================
 Page TSconfig Reference
@@ -16,18 +16,19 @@ overridden further out).
 
 Note that the page TSconfig can be overridden on a user and group basis by
 user TSconfig again, for details, see section
-:ref:`Overriding Page TSconfig in User TSconfig <userrelationshiptovaluessetinpagetsconfig>`.
+:ref:`Overriding page TSconfig in user TSconfig <userrelationshiptovaluessetinpagetsconfig>`.
 
 
-.. toctree::
-   :maxdepth: 5
-   :titlesonly:
+..  toctree::
+    :maxdepth: 5
+    :titlesonly:
 
-   Mod
-   Options
-   Rte
-   TcaDefaults
-   TceForm
-   TceMain
-   Templates
-   Tx
+    ColorPalettes
+    Mod
+    Options
+    Rte
+    TcaDefaults
+    TceForm
+    TceMain
+    Templates
+    Tx

Documentation/PageTsconfig/TceForm.rst

@@ -259,6 +259,38 @@ PAGE_TSCONFIG_STR
    be substituted by the given value.
 
 
+..  index::
+    Records; field configuration
+..  _pageTsConfigTceFormColorPalette:
+
+colorPalette
+------------
+
+..  versionadded:: 13.0
+
+:aspect:`Datatype`
+    string
+
+:aspect:`Description`
+    Assign a :ref:`color palette <pagecolorpalettes>` to a specific field of a
+    table, for all fields within a table or a global configuration affecting all
+    color pickers within :ref:`FormEngine <t3coreapi:FormEngine>`. If no palette
+    is defined, FormEngine falls back to all configured colors.
+
+:aspect:`Example`
+    ..  code-block:: typoscript
+        :caption: EXT:my_sitepackage/Configuration/page.tsconfig
+
+        # Assign a palette to a specific field
+        TCEFORM.tx_myext_table.myfield.colorPalette = messages
+
+        # Assign a palette to all color pickers used in a table
+        TCEFORM.tx_myext_table.colorPalette = key_colors
+
+        # Assign global palette
+        TCEFORM.colorPalette = main
+
+
 ..  index::
     Records; field configuration
 ..  _pageTsConfigTceFormConfig: