126 lines
5.9 KiB
ReStructuredText
126 lines
5.9 KiB
ReStructuredText
.. include:: /Includes.rst.txt
|
|
|
|
.. _feature-96895:
|
|
|
|
==============================================
|
|
Feature: #96895 - Introduce Module data object
|
|
==============================================
|
|
|
|
See :issue:`96895`
|
|
|
|
Description
|
|
===========
|
|
|
|
To further improve the handling of TYPO3 backend modules, the module
|
|
registration API, introduced in :issue:`96733`, is extended by the new
|
|
:php:`TYPO3\CMS\Backend\Module\ModuleData` object.
|
|
|
|
The :php:`ModuleData` object contains the user specific module settings,
|
|
e.g. whether the clipboard is shown, for the requested module. Those settings
|
|
are fetched from the users' session. A PSR-15 middleware does automatically
|
|
create the object from the stored user data and attach 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 just
|
|
read the final module data and does no longer have to fiddle around with
|
|
overwriting and persisting the data manually.
|
|
|
|
Previously, reading, overwriting and persisting of module data (settings)
|
|
was done in the controller:
|
|
|
|
.. code-block:: php
|
|
|
|
// Classes/Controller/MyController.php
|
|
|
|
$MOD_MENU = [
|
|
'allowedProperty' => '',
|
|
'anotherAllowedProperty' => true
|
|
];
|
|
|
|
$MOD_SETTINGS = BackendUtility::getModuleData(
|
|
$MOD_MENU,
|
|
$request->getParsedBody()['SET'] ?? $request->getQueryParams()['SET'] ?? [],
|
|
'my_module'
|
|
);
|
|
|
|
This is now automatically done by a new PSR-15 middleware. The "allowed"
|
|
properties are defined with their default value in the module registration:
|
|
|
|
.. code-block:: php
|
|
|
|
// Configuration/Backend/Modules.php
|
|
|
|
'moduleData' => [
|
|
'allowedProperty' => '',
|
|
'anotherAllowedProperty' => true,
|
|
],
|
|
|
|
// 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 defined in the given |
|
|
| | :php:`$useKeys` | list of allowed data. 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's still 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 e.g. in a controller:
|
|
|
|
.. code-block:: 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.
|
|
|
|
Impact
|
|
======
|
|
|
|
The new :php:`ModuleData` object is available as new 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`).
|
|
|
|
.. index:: Backend, PHP-API, ext:backend
|