[FEATURE] Introduce Site Settings Editor

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

Documentation/ApiOverview/SiteHandling/Index.rst

@@ -27,6 +27,7 @@ through the features of the module and goes into API and programming details.
     SiteSets
     SiteSettings
     SiteSettingDefinitions
+    SiteSettingsEditor
     CliTools
     AccessingSiteConfiguration
     ExtendingSiteConfig

Documentation/ApiOverview/SiteHandling/SiteSettingDefinitions.rst

@@ -8,88 +8,179 @@ Site settings definitions
 =========================
 
 ..  versionadded:: 13.1
+    Site-scoped setting definitions where introduced. They will most likely be
+    the place to configure site-wide configuration, which was previously only
+    possible to modify via Constant Editor, modifying TypoScript constants.
 
-The big problem with TypoScript and TSConfig is that each specified value can
-only ever be a string. It is up to the developer alone to read these values
-and convert them into the desired data type such as integer.
+Site settings definitions allow to define settings with a type and a guaranteed
+default value. They can be defined in :ref:`site-sets`, in a file called
+:file:`_blog_settins.definitions.yaml`.
 
-TYPO3 wants to remedy this with settings definitions and now provides an API
-with which you can add additional descriptive definitions for each individual
-site setting.
+It is recommended to use site-sets and their UI configuration in favor of
+TypoScript Constants.
 
-..  literalinclude:: _Settings/_settings.definitions.yaml
-    :caption: EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml
+All available settings are displayed in the :ref:`site-settings-editor`.
+
+The site settings provided by an extension can be automatically documented in the
+extensions manual, see
+:ref:`site settings documentation <h2document:reference-site-settings>`.
+
+..  contents:: Table of contents
+
+..  _site-settings-definition-example:
+
+Site setting definition example
+===============================
+
+..  literalinclude:: _Settings/_blog_settings.definitions.yaml
+    :caption: EXT:blog_example/Configuration/Sets/BlogExample/settings.definitions.yaml (Excerpt)
+
+See the complete example at
+`settings.definitions.yaml (GitHub) <https://github.com/TYPO3-Documentation/blog_example/blob/main/Configuration/Sets/BlogExample/settings.definitions.yaml>`__.
+
+..  figure:: /Images/ManualScreenshots/SiteHandling/SiteSettingsDefinition.png
+    :alt: Screenshot demonstration the position of the categories, labels etc
+
+    The parts marked by a number can be configured, see list bellow
+
+
+..  _site-settings-definition-properties:
+
+Site setting definition properties
+==================================
+
+..  confval-menu::
+    :display: table
+    :name: site-setting-definition
+    :type:
+    :required:
+
+    ..  confval:: categories
+        :type: array
+        :name: site-settings-definition-categories
+
+        ..  confval:: label
+            :type: string
+            :name: site-settings-definition-categories-label
+
+        ..  confval:: parent
+            :type: :confval:`site-settings-definition-categories` key
+            :name: site-settings-definition-categories-parent
+
+    ..  confval:: settings
+        :type: array
+        :name: site-settings-definition-settings
+
+        ..  confval:: label
+            :type: string
+            :name: site-settings-definition-settings-label
+
+        ..  confval:: description
+            :type: string
+            :name: site-settings-definition-settings-description
+
+        ..  confval:: category
+            :type: :confval:`site-settings-definition-categories` key
+            :name: site-settings-definition-settings-category
+
+        ..  confval:: type
+            :type: a :ref:`definition type <definition-types>`
+            :name: site-settings-definition-settings-type
+            :required:
+
+        ..  confval:: default
+            :type: mixed
+            :name: site-settings-definition-settings-default
+            :required:
+
+            The default value must have the same type like defined in
+            :confval:`site-settings-definition-settings-type`.
 
 ..  _definition-types:
 
 Definition types
 ================
 
-..  confval:: int
-    :name: site-setting-type-int
-    :type: string
-    :Path: settings.[my_val].type = int
+..  confval-menu::
+    :display: table
+    :name: site-setting-type
+    :type:
+    :required:
+
+    ..  confval:: int
+        :name: site-setting-type-int
+        :type: string
+        :Path: settings.[my_val].type = int
+
+        Checks whether the value is already an integer or can be interpreted as an
+        integer. If yes, the string is converted into an integer.
+
+    ..  confval:: number
+        :name: site-setting-type-number
+        :type: string
+        :Path: settings.[my_val].type = number
+
+        Checks whether the value is already an integer or float or whether the
+        string can be interpreted as an integer or float. If yes, the string is
+        converted to an integer or float.
+
+    ..  confval:: bool
+        :name: site-setting-type-bool
+        :type: string
+        :Path: settings.[my_val].type = bool
 
-    Checks whether the value is already an integer or can be interpreted as an
-    integer. If yes, the string is converted into an integer.
+        If the value is already a boolean, it is returned directly 1 to 1.
 
-..  confval:: number
-    :name: site-setting-type-number
-    :type: string
-    :Path: settings.[my_val].type = number
+        If the value is an integer, then `false` is returned for 0 and `true` for 1.
 
-    Checks whether the value is already an integer or float or whether the
-    string can be interpreted as an integer or float. If yes, the string is
-    converted to an integer or float.
+        If the value is a string, the corresponding Boolean value is returned for
+        `true`, `false`, `yes`, `no`, `on`, `off`, `0` and `1`.
 
-..  confval:: bool
-    :name: site-setting-type-bool
-    :type: string
-    :Path: settings.[my_val].type = bool
+    ..  confval:: string
+        :name: site-setting-type-string
+        :type: string
+        :Path: settings.[my_val].type = string
 
-    If the value is already a boolean, it is returned directly 1 to 1.
+        Converts almost all data types into a string. If an object has been
+        specified, it must be `stringable`, otherwise no conversion takes place.
+        Boolean values are converted to `true` and `false`.
 
-    If the value is an integer, then `false` is returned for 0 and `true` for 1.
+    ..  confval:: text
+        :name: site-setting-type-text
+        :type: string
+        :Path: settings.[my_val].type = text
 
-    If the value is a string, the corresponding Boolean value is returned for
-    `true`, `false`, `yes`, `no`, `on`, `off`, `0` and `1`.
+        Exactly the same as the `string` type. Use it as an alias if someone doesn't
+        know what to do with `string`.
 
-..  confval:: string
-    :name: site-setting-type-string
-    :type: string
-    :Path: settings.[my_val].type = string
+    ..  confval:: stringlist
+        :name: site-setting-type-stringlist
+        :type: string
+        :Path: settings.[my_val].type = stringlist
 
-    Converts almost all data types into a string. If an object has been
-    specified, it must be `stringable`, otherwise no conversion takes place.
-    Boolean values are converted to `true` and `false`.
+        The value must be an array whose array keys start at 0 and increase by 1 per
+        element. The list in this type is derived from the internal PHP method
+        `array_is_list` and has nothing to do with the fact that comma-separated
+        lists can also be converted here.
 
-..  confval:: text
-    :name: site-setting-type-text
-    :type: string
-    :Path: settings.[my_val].type = text
+        The `string` type is executed for each array entry.
 
-    Exactly the same as the `string` type. Use it as an alias if someone doesn't
-    know what to do with `string`.
+    ..  confval:: color
+        :name: site-setting-type-color
+        :type: string
+        :Path: settings.[my_val].type = color
 
-..  confval:: stringlist
-    :name: site-setting-type-stringlist
-    :type: string
-    :Path: settings.[my_val].type = stringlist
+        Checks whether the specified string can be interpreted as a color code.
+        Entries starting with `rgb`, `rgba` and `#` are permitted here.
 
-    The value must be an array whose array keys start at 0 and increase by 1 per
-    element. The list in this type is derived from the internal PHP method
-    `array_is_list` and has nothing to do with the fact that comma-separated
-    lists can also be converted here.
+        For `#` color codes, for example, the system checks whether they
+        have 3, 6 or 8 digits.
 
-    The `string` type is executed for each array entry.
 
-..  confval:: color
-    :name: site-setting-type-color
-    :type: string
-    :Path: settings.[my_val].type = color
+    ..  figure:: /Images/ManualScreenshots/SiteHandling/SiteSettingsTypes1.png
+        :alt: Screenshot demonstration the input fields for different setting types (Part 1)
 
-    Checks whether the specified string can be interpreted as a color code.
-    Entries starting with `rgb`, `rgba` and `#` are permitted here.
+    ..  figure:: /Images/ManualScreenshots/SiteHandling/SiteSettingsTypes2.png
+        :alt: Screenshot demonstration the input fields for different setting types (Part 2)
 
-    For `#` color codes, for example, the system checks whether they
-    have 3, 6 or 8 digits.
+        A demonstration of the different setting types

Documentation/ApiOverview/SiteHandling/SiteSettings.rst

@@ -6,17 +6,11 @@
 Site settings
 =============
 
-..  versionchanged:: 12.1
-    Before TYPO3 v12.1 the site settings were stored in the :file:`config.yaml`
-    file under the :yaml:`settings` key. An upgrade wizard copies the settings
-    to the new :file:`settings.yaml` file.
-
-    Settings are not removed from the :file:`config.yaml` file for now, but will
-    not have any effect anymore as soon as a :file:`settings.yaml` file exists.
-
-    Please review your settings in the :file:`config.yaml` file and remove them
-    manually. Eventually, you need and/or want to adopt your deployment
-    workflow.
+..  versionadded:: 13.1
+    Site settings can receive a type, a default value and some documentation in
+    :ref:`site settings definitions <site-sets-settings-definition>`. It is
+    recommended to always define a site setting before using is as only this way
+    you can ensure proper types and default values.
 
 Site settings can be used to provide settings for a site. They can be accessed
 via

Documentation/ApiOverview/SiteHandling/SiteSettingsEditor.rst

@@ -0,0 +1,91 @@
+..  include:: /Includes.rst.txt
+..  index:: Site handling; Site settings editor
+..  _site-settings-editor:
+
+====================
+Site settings editor
+====================
+
+..  versionadded:: 13.3
+    The site setting editor has been introduced as backend module
+    :guilabel:`Sites > Settings`.
+
+In module :guilabel:`Sites > Settings` you get an overview of all sites in
+the current installation and can edit the :ref:`sitehandling-settings` for
+all pages that contain settings:
+
+..  figure:: /Images/ManualScreenshots/SiteHandling/SiteSettingsOverview.png
+    :alt: Screenshot of the Site Settings module in overview
+
+    Site "Home" has settings that can be edited. The others do not.
+
+The settings editor displays the settings of all site sets included in the
+current site, including their dependencies. The site sets can define categories
+and subcategories to order the settings.
+
+..  figure:: /Images/ManualScreenshots/SiteHandling/SiteSettings.png
+    :alt: Screenshot of the settings of an example site
+
+    The site in the examples includes the "My Sitepackage" and "Blog Example"
+    sets. "My Sitepackage" depends on "Fluid Styled Content"
+
+The settings to be displayed here have to be defined in an extension`s or
+site packages's set in a `setting definition <site-settings-definition>` file, for example
+:file:`EXT:my_sitepackage/Configuration/Sets/MySitepackage/settings.definitions.yaml`.
+
+Settings that have been made directly in the :file:`settings.yaml` file without a
+corresponding entry in a :file:`settings.definitions.yaml` are not displayed in
+the editor as they have neither a type nor a label. These values are, however,
+retained when the editor writes to the :file:`settings.yaml` file.
+
+..  _sitehandling-settings-editor-configuration:
+
+Configuring the site settings editor
+====================================
+
+..  figure:: /Images/ManualScreenshots/SiteHandling/SiteSettingsDefinition.png
+    :alt: Screenshot demonstration the position of the categories, labels etc
+
+    The parts marked by a number can be configured, see list bellow
+
+..  literalinclude:: _Settings/_blog_settings.definitions.yaml
+    :caption: EXT:blog_example/Configuration/Sets/BlogExample/settings.definitions.yaml (Excerpt)
+
+See the complete example at
+`settings.definitions.yaml (GitHub) <https://github.com/TYPO3-Documentation/blog_example/blob/main/Configuration/Sets/BlogExample/settings.definitions.yaml>`__.
+
+..  rst-class:: bignums-attention
+
+1.  Main category
+
+    The label of the category is defined in *line 3* of the example code snippet.
+    *Line 6 and 9* place two categories as subcategories into this category.
+
+2.  Sub category
+
+    The sub category is defined in *line 5 to 6*. *Line 14* locates the setting
+    in this subcategory.
+
+3.  Label
+
+    Can be defined directly in the settings definition (*line 13*) or in a
+    :file:`labels.xlf` file.
+
+4.  Description
+
+    Can be defined directly in the settings definition (*line 15*) or in a
+    :file:`labels.xlf` file.
+
+5.  Type
+
+    *line 16*, for possible types see :ref:`definition-types`.
+
+6.  Default value
+
+    *line 23* the default value is displayed if the value of the settings was
+    not overridden. If the value was overridden, it can be reset to the default.
+
+    ..  figure:: /Images/ManualScreenshots/SiteHandling/SiteSettingsReset.png
+        :alt: Screenshot showing the "Reset settings" button in the settings popup menu
+
+        Reset the setting to the default value

Documentation/ApiOverview/SiteHandling/_Settings/_blog_settings.definitions.yaml

@@ -0,0 +1,23 @@
+categories:
+  BlogExample:
+    label: 'Blog Example' # (1)
+  BlogExample.templates:
+    label: 'Templates' # (2)
+    parent: BlogExample
+  BlogExample.pages:
+    label: 'Pages'
+    parent: BlogExample
+
+settings:
+  blogExample.templateRootPath:  # (5)
+    label: 'Templates' # (3)
+    category: BlogExample.templates # (2)
+    description: 'Path to template root'  # (4)
+    type: string  # (6)
+    default: 'EXT:blog_example/Resources/Private/Templates/'  # (7) + (8)
+  blogExample.partialRootPath:
+    label: 'Partials'
+    category: BlogExample.templates
+    description: 'Path to partial root'
+    type: string
+    default: 'EXT:blog_example/Resources/Private/Partials/'