Feature: #97135 - New Registration for module functions

resolves TYPO3-Documentation/Changelog-To-Doc#19

Feature: #96895 - Introduce Module data object #14
resolves TYPO3-Documentation/Changelog-To-Doc#14

refs TYPO3-Documentation/Changelog-To-Doc#18

Documentation/ExtensionArchitecture/FileStructure/Configuration/Backend/Index.rst

@@ -41,3 +41,12 @@ file, which you can use as example:
 `typo3/sysext/backend/Configuration/Backend/Routes.php <https://github.com/typo3/typo3/blob/main/typo3/sysext/backend/Configuration/Backend/Routes.php>`__
 
 Read more about :ref:`Backend routing <backend-routing>`.
+
+:file:`Modules.php`
+====================
+
+Complete path: :file:`EXT:my_extension/Configuration/Backend/Modules.php`.
+
+This file is used for the
+:ref:`Backend module configuration <backend-modules-configuration>`. See that
+chapter for details.

Documentation/ExtensionArchitecture/HowTo/BackendModule/Index.rst

@@ -119,5 +119,7 @@ backend. They are described in this chapter.
    CreateModule
    CreateModuleWithExtbase
    ModuleTypoScript
+   ModuleDataObject
    ToplevelModules
+   ThirdlevelModules
    ModuleProviderAPI

Documentation/ExtensionArchitecture/HowTo/BackendModule/ModuleConfiguration.rst

@@ -211,6 +211,27 @@ Module configuration options
    This option defaults to :php:`true` and can therefore be used to
    stop the inheritance for sub modules.
 
+
+.. confval:: moduleData
+
+   :Scope: Backend module configuration
+   :type: array
+
+   All properties of the :ref:`module data object <backend-Module-data-object>`
+   that may be overridden by :php:`GET` / :php:`POST` parameters of the request
+   get their default value defined here.
+
+   **Example**
+
+
+   .. code-block:: php
+      :caption: EXT:my_extension/Configuration/Backend/Modules.php
+
+      'moduleData' => [
+          'allowedProperty' => '',
+          'anotherAllowedProperty' => true,
+      ],
+
 Default module configuration options (without Extbase)
 ------------------------------------------------------
 
@@ -221,13 +242,16 @@ Default module configuration options (without Extbase)
 
    Define the routes to this module. Each route requires a `path` and
    the `target`, except the mandatory `_default` route, which uses
-   the `path` from the top-level configuration::
+   the `path` from the top-level configuration:
 
-       routes' => [
-           '_default' => [
-               'target' => MyController::class . '::handleRequest',
-           ],
-       ],
+   .. code-block:: php
+      :caption: EXT:my_extension/Configuration/Backend/Modules.php
+
+      routes' => [
+          '_default' => [
+              'target' => MyController::class . '::handleRequest',
+          ],
+      ],
 
    .. note::
       Using additional routes - next to `_default` is not yet implemented.

Documentation/ExtensionArchitecture/HowTo/BackendModule/ModuleDataObject.rst

@@ -0,0 +1,96 @@
+.. include:: /Includes.rst.txt
+.. index::
+   Backend modules; Module data object
+.. _backend-Module-data-object:
+
+==================
+Module data object
+==================
+
+.. versionadded:: 12.0
+
+The :php:`TYPO3\CMS\Backend\Module\ModuleData` object is available as
+attribute of the PSR-7 Request - in case a TYPO3 backend module is requested -
+and contains the stored module data, which might have been overwritten
+through the current request (with :php:`GET` / :php:`POST`).
+
+The :php:`TYPO3\CMS\Backend\Module\ModuleData` object contains the user
+specific module settings, for example whether the clipboard is shown,
+for the requested module. Those settings
+are fetched from the user's session. A PSR-15 middleware automatically
+creates the object from the stored user data and attaches it to the PSR-7 Request.
+
+Through the module registration one can define, which properties can
+be overwritten via :php:`GET` / :php:`POST` and their default value.
+
+The whole determination is done before the requested route target - usually
+a backend controller - is called. This means, the route target can
+read the final module data.
+
+The *allowed* properties are defined with their default value in the
+module registration:
+
+.. code-block:: php
+   :caption: EXT:my_extension/Configuration/Backend/Modules.php
+
+   'moduleData' => [
+       'allowedProperty' => '',
+       'anotherAllowedProperty' => true,
+   ],
+
+.. code-block:: php
+   :caption: Classes/Controller/MyController.php
+
+   $MOD_SETTINGS = $request->getAttribute('moduleData');
+
+The :php:`ModuleData` object provides the following methods:
+
++-------------------------+-----------------------+----------------------------------------------------+
+| Method                  | Parameters            | Description                                        |
++=========================+=======================+====================================================+
+| createFromModule()      | :php:`$module`        | Create a new object for the given module, while    |
+|                         | :php:`$data`          | overwriting the default values with :php:`$data`.  |
++-------------------------+-----------------------+----------------------------------------------------+
+| getModuleIdentifier()   |                       | Returns the related module identifier              |
++-------------------------+-----------------------+----------------------------------------------------+
+| get()                   | :php:`$propertyName`  | Returns the value for :php:`$propertyName`, or the |
+|                         | :php:`$default`       | :php:`$default`, if not set.                       |
++-------------------------+-----------------------+----------------------------------------------------+
+| set()                   | :php:`$propertyName`  | Updates :php:`$propertyName` with the given        |
+|                         | :php:`$value`         | :php:`$value`.                                     |
++-------------------------+-----------------------+----------------------------------------------------+
+| has()                   | :php:`$propertyName`  | Whether :php:`$propertyName` exists.               |
++-------------------------+-----------------------+----------------------------------------------------+
+| clean()                 | :php:`$propertyName`  | Cleans a single property by the given allowed      |
+|                         | :php:`$allowedValues` | list and falls back to either the default value    |
+|                         |                       | or the first allowed value.                        |
++-------------------------+-----------------------+----------------------------------------------------+
+| cleanUp()               | :php:`$allowedData`   | Cleans up all module data, which are defined in    |
+|                         | :php:`$useKeys`       | the given allowed data list. Usually called with   |
+|                         |                       | :php:`$MOD_MENU` in a controller with module menu. |
++-------------------------+-----------------------+----------------------------------------------------+
+| toArray()               |                       | Returns the module data as :php:`array`.           |
++-------------------------+-----------------------+----------------------------------------------------+
+
+In case a controller needs to store changed module data, this can still be done
+using :php:`$backendUser->pushModuleData('my_module', $this->moduleData->toArray());`.
+
+.. note::
+
+   It is possible to store and retrieve arbitrary module data. The
+   definition of :php:`moduleData` in the module registration only defines,
+   which properties can be overwritten in a request (with :php:`GET` / :php:`POST`).
+
+To restrict the values of module data properties, the given :php:`ModuleData`
+object can be cleaned for example in a controller:
+
+.. code-block:: php
+   :caption: Classes/Controller/MyController.php
+
+   $allowedValues = ['foo', 'bar'];
+   $this->moduleData->clean('property', $allowedValues);
+
+If :php:`ModuleData` contains :php:`property`, the value is checked
+against the :php:`$allowedValues` list. If the current value is valid,
+nothing happens. Otherwise the value is either changed to the default
+or if this value is also not allowed, to the first allowed value.

Documentation/ExtensionArchitecture/HowTo/BackendModule/ModuleTypoScript.rst

@@ -9,35 +9,14 @@ TypoScript configuration of modules
 The backend module of an extension can be configured via TypoScript.
 The configuration is done in
 :typoscript:`module.tx_<lowercaseextensionname>_<lowercasepluginname>`.
-:typoscript:`_<lowercasepluginname>` can be ommited then the setting is used
+:typoscript:`_<lowercasepluginname>` can be omitted then the setting is used
 for all backend modules of that extension.
 
 Even though we are in the backend context here we use TypoScript setup. The
 settings should be done globally and not changed on a per-page basis.
 Therefore they are usually done in the file
 :ref:`EXT:my_extension/ext_typoscript_setup.typoscript <ext_typoscript_setup_typoscript>`.
 
-
-Options for simple backend modules
-===================================
-
-In simple backend modules extension authors can decide how to use this
-namespace. By convention settings should go in the subsection
-:typoscript:`settings`.
-
-.. code-block:: typoscript
-   :caption: EXT:my_extension/ext_typoscript_setup.typoscript
-
-   module.tx_myextension_somemodule {
-       settings {
-           enablesomething = 1
-       }
-   }
-
-Options for Extbase backend modules
-===================================
-
-Most configuration options that can be done for Extbase frontend plugins
-can also be done for Extbase backend modules.
-
+See the :ref:`toplevel object "module" <t3tsref:tlo-module>` in the
+TypoScript reference for the available options.
 

Documentation/ExtensionArchitecture/HowTo/BackendModule/ThirdlevelModules.rst

@@ -0,0 +1,55 @@
+.. include:: /Includes.rst.txt
+.. index::
+   Backend modules; Thirdlevel
+   Backend modules; Module functions
+
+.. _backend-modules-third-level-module:
+
+======================================
+Third-level modules / module functions
+======================================
+
+.. versionchanged:: 12.0
+   Previously, module functions could be added to modules such as
+   :guilabel:`Web > Info` or :guilabel:`Web > Template` via the
+   now removed global :php:`TBE_MODULES_EXT` array.
+
+   These are now registered as Third-level modules with the
+   backend module configuration API.
+
+Third-level - modules are registered in the
+extension's :file:`Configuration/Backend/Modules.php` file, the
+same way as :ref:`top-level <backend-modules-toplevel-module>`
+and common :ref:`modules <backend-modules-configuration>`.
+
+This allows administrators to define access permissions via the module
+access logic for those modules individually. and also allows to influence the
+position of tof the third-level module.
+
+Example
+=======
+
+Registration of an additional - "third-level" - module for the
+:guilabel:`Web > Template` in the :file:`Configuration/Backend/Modules.php`
+file of an extension:
+
+.. code-block:: php
+   :caption: EXT:my_extension/Configuration/Backend/Modules.php
+
+   'web_ts_customts' => [
+       'parent' => 'web_ts',
+       'access' => 'user',
+       'path' => '/module/web/typoscript/custom-ts',
+       'iconIdentifier' => 'module-custom-ts',
+       'labels' => [
+           'title' => 'LLL:EXT:extkey/Resources/Private/Language/locallang.xlf:mod_title',
+       ],
+       'routes' => [
+           '_default' => [
+               'target' => CustomTsController::class . '::handleRequest',
+           ],
+       ],
+       'moduleData' => [
+           'someOption' => false,
+       ],
+   ],