From 0134be841ae7ff48cede5bba72bc89bbbce5234f Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Wed, 8 Jun 2022 21:27:11 +0200 Subject: [PATCH] Feature: #97135 - New Registration for module functions resolves https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/19 Feature: #96895 - Introduce Module data object #14 resolves https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/14 refs https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/18 --- .../Configuration/Backend/Index.rst | 9 ++ .../HowTo/BackendModule/Index.rst | 2 + .../BackendModule/ModuleConfiguration.rst | 36 +++++-- .../HowTo/BackendModule/ModuleDataObject.rst | 96 +++++++++++++++++++ .../HowTo/BackendModule/ModuleTypoScript.rst | 27 +----- .../HowTo/BackendModule/ThirdlevelModules.rst | 55 +++++++++++ 6 files changed, 195 insertions(+), 30 deletions(-) create mode 100644 Documentation/ExtensionArchitecture/HowTo/BackendModule/ModuleDataObject.rst create mode 100644 Documentation/ExtensionArchitecture/HowTo/BackendModule/ThirdlevelModules.rst diff --git a/Documentation/ExtensionArchitecture/FileStructure/Configuration/Backend/Index.rst b/Documentation/ExtensionArchitecture/FileStructure/Configuration/Backend/Index.rst index 66f5bc61d4..f083ae3038 100644 --- a/Documentation/ExtensionArchitecture/FileStructure/Configuration/Backend/Index.rst +++ b/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 `__ Read more about :ref:`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 `. See that +chapter for details. diff --git a/Documentation/ExtensionArchitecture/HowTo/BackendModule/Index.rst b/Documentation/ExtensionArchitecture/HowTo/BackendModule/Index.rst index fa279c4060..764ac73917 100644 --- a/Documentation/ExtensionArchitecture/HowTo/BackendModule/Index.rst +++ b/Documentation/ExtensionArchitecture/HowTo/BackendModule/Index.rst @@ -119,5 +119,7 @@ backend. They are described in this chapter. CreateModule CreateModuleWithExtbase ModuleTypoScript + ModuleDataObject ToplevelModules + ThirdlevelModules ModuleProviderAPI diff --git a/Documentation/ExtensionArchitecture/HowTo/BackendModule/ModuleConfiguration.rst b/Documentation/ExtensionArchitecture/HowTo/BackendModule/ModuleConfiguration.rst index f0eff89bc7..c71b3ec927 100644 --- a/Documentation/ExtensionArchitecture/HowTo/BackendModule/ModuleConfiguration.rst +++ b/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 ` + 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. diff --git a/Documentation/ExtensionArchitecture/HowTo/BackendModule/ModuleDataObject.rst b/Documentation/ExtensionArchitecture/HowTo/BackendModule/ModuleDataObject.rst new file mode 100644 index 0000000000..289acd1ea2 --- /dev/null +++ b/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. diff --git a/Documentation/ExtensionArchitecture/HowTo/BackendModule/ModuleTypoScript.rst b/Documentation/ExtensionArchitecture/HowTo/BackendModule/ModuleTypoScript.rst index 64bed8d3c0..98bf1ef851 100644 --- a/Documentation/ExtensionArchitecture/HowTo/BackendModule/ModuleTypoScript.rst +++ b/Documentation/ExtensionArchitecture/HowTo/BackendModule/ModuleTypoScript.rst @@ -9,7 +9,7 @@ TypoScript configuration of modules The backend module of an extension can be configured via TypoScript. The configuration is done in :typoscript:`module.tx__`. -:typoscript:`_` can be ommited then the setting is used +:typoscript:`_` 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 @@ -17,27 +17,6 @@ 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 `. - -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" ` in the +TypoScript reference for the available options. diff --git a/Documentation/ExtensionArchitecture/HowTo/BackendModule/ThirdlevelModules.rst b/Documentation/ExtensionArchitecture/HowTo/BackendModule/ThirdlevelModules.rst new file mode 100644 index 0000000000..5822302eb9 --- /dev/null +++ b/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 ` +and common :ref:`modules `. + +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, + ], + ],