diff --git a/Documentation/ApiOverview/SiteHandling/Index.rst b/Documentation/ApiOverview/SiteHandling/Index.rst index c3650cd84..4c47968fe 100644 --- a/Documentation/ApiOverview/SiteHandling/Index.rst +++ b/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 diff --git a/Documentation/ApiOverview/SiteHandling/SiteSettingDefinitions.rst b/Documentation/ApiOverview/SiteHandling/SiteSettingDefinitions.rst index 64bba8017..70009b4c7 100644 --- a/Documentation/ApiOverview/SiteHandling/SiteSettingDefinitions.rst +++ b/Documentation/ApiOverview/SiteHandling/SiteSettingDefinitions.rst @@ -8,88 +8,187 @@ 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 modifying TypoScript constants, for example in the + Constant Editor. -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:`settings.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 `. + +.. 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) `__. + +.. 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 ` + :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`. + + .. confval:: readonly + :type: bool + :name: site-settings-definition-settings-readonly + + If a site setting is marked as readonly, it can be overridden only + by editing the :file:`config/sites/my-site/settings.yaml` directly, + but not from within the editor. .. _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 key starts at 0 and increases by 1 per element. This sequence is + checked using the internal PHP method array_is_list in order to prevent named array keys from the outset. + This also means that comma-separated lists cannot 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 diff --git a/Documentation/ApiOverview/SiteHandling/SiteSettings.rst b/Documentation/ApiOverview/SiteHandling/SiteSettings.rst index a1de0ce98..741e38dde 100644 --- a/Documentation/ApiOverview/SiteHandling/SiteSettings.rst +++ b/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 `. It is + recommended to always define a site setting before using it, 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 diff --git a/Documentation/ApiOverview/SiteHandling/SiteSettingsEditor.rst b/Documentation/ApiOverview/SiteHandling/SiteSettingsEditor.rst new file mode 100644 index 000000000..e2b0b4869 --- /dev/null +++ b/Documentation/ApiOverview/SiteHandling/SiteSettingsEditor.rst @@ -0,0 +1,92 @@ +.. 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:`Site Management > Settings`. + +In module :guilabel:`Site Management > 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 :ref:`setting 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) + :linenos: + +See the complete example at +`settings.definitions.yaml (GitHub) `__. + +.. 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 diff --git a/Documentation/ApiOverview/SiteHandling/_Settings/_blog_settings.definitions.yaml b/Documentation/ApiOverview/SiteHandling/_Settings/_blog_settings.definitions.yaml new file mode 100644 index 000000000..ad2f2ef79 --- /dev/null +++ b/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/' diff --git a/Documentation/Images/ManualScreenshots/SiteHandling/SiteSettings.png b/Documentation/Images/ManualScreenshots/SiteHandling/SiteSettings.png new file mode 100644 index 000000000..58fe2f0f3 Binary files /dev/null and b/Documentation/Images/ManualScreenshots/SiteHandling/SiteSettings.png differ diff --git a/Documentation/Images/ManualScreenshots/SiteHandling/SiteSettingsDefinition.png b/Documentation/Images/ManualScreenshots/SiteHandling/SiteSettingsDefinition.png new file mode 100644 index 000000000..25f62ddb7 Binary files /dev/null and b/Documentation/Images/ManualScreenshots/SiteHandling/SiteSettingsDefinition.png differ diff --git a/Documentation/Images/ManualScreenshots/SiteHandling/SiteSettingsOverview.png b/Documentation/Images/ManualScreenshots/SiteHandling/SiteSettingsOverview.png new file mode 100644 index 000000000..7b5a4257d Binary files /dev/null and b/Documentation/Images/ManualScreenshots/SiteHandling/SiteSettingsOverview.png differ diff --git a/Documentation/Images/ManualScreenshots/SiteHandling/SiteSettingsReset.png b/Documentation/Images/ManualScreenshots/SiteHandling/SiteSettingsReset.png new file mode 100644 index 000000000..4322464f7 Binary files /dev/null and b/Documentation/Images/ManualScreenshots/SiteHandling/SiteSettingsReset.png differ diff --git a/Documentation/Images/ManualScreenshots/SiteHandling/SiteSettingsTypes1.png b/Documentation/Images/ManualScreenshots/SiteHandling/SiteSettingsTypes1.png new file mode 100644 index 000000000..f22424074 Binary files /dev/null and b/Documentation/Images/ManualScreenshots/SiteHandling/SiteSettingsTypes1.png differ diff --git a/Documentation/Images/ManualScreenshots/SiteHandling/SiteSettingsTypes2.png b/Documentation/Images/ManualScreenshots/SiteHandling/SiteSettingsTypes2.png new file mode 100644 index 000000000..a7bb0d19b Binary files /dev/null and b/Documentation/Images/ManualScreenshots/SiteHandling/SiteSettingsTypes2.png differ