Backend module configuration¶
Changed in version 12.0: Registration of backend modules was changed with version 12. If you are using an older version of TYPO3 please use the version switcher on the top left of this document to go to the respective version.
The configuration of backend modules is placed in the
dedicated Configuration/Backend/Modules.php
configuration file.
Note
The Configuration/Backend/Modules.php
configuration files are
read and processed when building the container. This
means the state is fixed and cannot be changed at runtime.
Example: register two backend modules¶
You can find the following example in EXT:examples.
Two backend modules are being registered. The first module is based on Extbase while the second uses a plain controller.
use T3docs\Examples\Controller\ModuleController;
use T3docs\Examples\Controller\AdminModuleController;
/**
* Definitions for modules provided by EXT:examples
*/
return [
'web_examples' => [
'parent' => 'web',
'position' => ['after' => 'web_info'],
'access' => 'user',
'workspaces' => 'live',
'path' => '/module/page/example',
'labels' => 'LLL:EXT:examples/Resources/Private/Language/Module/locallang_mod.xlf',
'extensionName' => 'Examples',
'controllerActions' => [
ModuleController::class => [
'flash','tree','clipboard','links','fileReference','fileReferenceCreate',
],
],
],
'admin_examples' => [
'parent' => 'system',
'position' => ['top'],
'access' => 'user',
'workspaces' => 'live',
'path' => '/module/system/example',
'labels' => 'LLL:EXT:examples/Resources/Private/Language/AdminModule/locallang_mod.xlf',
'extensionName' => 'Examples',
'controllerActions' => [
AdminModuleController::class => [
'index',
],
],
],
];
Module configuration options¶
- parent¶
- Scope
Backend module configuration
- Type
string
If the module should be a submodule, the parent identifier, for example
web
has to be set here. Have a look into the list of available toplevel modules.Extensions can add additional parent modules, see Toplevel modules.
- path¶
- Scope
Backend module configuration
- Type
string
- Default
/module/<mainModule>/<subModule>
Define the path to the default endpoint. The path can be anything, but will fallback to the known
/module/<mainModule>/<subModule>
pattern, if not set.
- access¶
- Scope
Backend module configuration
- Type
string
Can be
user
(editor permissions),admin
, orsystemMaintainer
.
- workspaces¶
- Scope
Backend module configuration
- Type
string
Can be
*
(= always),live
oroffline
- position¶
- Scope
Backend module configuration
- Type
array
The module position. Allowed values are
top
andbottom
as well as the key value pairsbefore => <identifier>
andafter => <identifier>
.
- appearance¶
- Scope
Backend module configuration
- Type
array
Allows to define additional appearance options. Currently only
appearance.renderInModuleMenu
is available.
- appearance.renderInModuleMenu¶
- Scope
Backend module configuration
- Type
bool
If set to false the module is not displayed in the module menu.
- iconIdentifier¶
- Scope
Backend module configuration
- Type
string
The module icon identifier
- icon¶
- Scope
Backend module configuration
- Type
string
Path to a module icon (Deprecated: Use
iconIdentifier
instead)
- labels¶
- Scope
Backend module configuration
- Type
array or string
An
array
with the following keys:title
description
shortDescription
The value can either be a static string or a locallang label reference. |
It is also possible to define the path to a locallang file. The referenced file should contain the following label keys:
mlang_tabs_tab
(Used as module title)mlang_labels_tabdescr
(Used as module description)mlang_labels_tablabel
(Used as module short description)
- component¶
- Scope
Backend module configuration
- Type
string
- Default
TYPO3/CMS/Backend/Module/Iframe
The view component, responsible for rendering the module.
- Scope
Backend module configuration
- Type
string
The module navigation component. The following are provided by the Core:
TYPO3/CMS/Backend/PageTree/PageTreeElement
The page tree as used in the Web module.
TYPO3/CMS/Backend/Tree/FileStorageTreeContainer
The file tree as used in the Filelist module.
- Scope
Backend module configuration
- Type
string
The module navigation component (Deprecated: Use
navigationComponent
)
- Scope
Backend module configuration
- Type
bool
- Default
true
Whether the module should use the parents navigation component. This option defaults to
true
and can therefore be used to stop the inheritance for submodules.
- moduleData¶
- Scope
Backend module configuration
- Type
array
All properties of the module data object that may be overridden by
GET
/POST
parameters of the request get their default value defined here.Example
EXT:my_extension/Configuration/Backend/Modules.php¶'moduleData' => [ 'allowedProperty' => '', 'anotherAllowedProperty' => true, ],
- aliases¶
- Scope
Backend module configuration
- Type
array
List of identifiers that are aliases to this module. Those are added as route aliases, which allows to use them for building links, for example with the
UriBuilder
. Additionally, the aliases can also be used for references in other modules, for example to specify a modules'parent
.Examples
Example for a new module identifier:
EXT:my_extension/Configuration/Backend/Modules.php¶return [ 'workspaces_admin' => [ 'parent' => 'web', // ... // choose the previous name or an alternative name 'aliases' => ['web_WorkspacesWorkspaces'], ], ];
Example for a route alias identifier:
EXT:my_extension/Configuration/Backend/Modules.php¶return [ 'file_editcontent' => [ 'path' => '/file/editcontent', 'aliases' => ['file_edit'], ], ];
Default module configuration options (without Extbase)¶
Changed in version 12.2: Specific routes different from _default
can now be defined.
- routes¶
- Scope
Backend module configuration
- Type
array
Define the routes to this module. Each route requires at least the
target
. The_default
route is mandatory, except for modules which can fall back to a submodule. Thepath
of the_default
route is taken from the top-level configuration. For all other routes, the route identifier is taken aspath
, if not explicitly defined. Each route can define any controller/action pair and can restrict the allowed HTTP methods:EXT:my_extension/Configuration/Backend/Modules.php¶routes' => [ '_default' => [ 'target' => MyModuleController::class . '::overview', ], 'edit' => [ 'path' => '/edit-me', 'target' => MyModuleController::class . '::edit', ], 'manage' => [ 'target' => AnotherController::class . '::manage', 'methods' => ['POST'], ], ],
All subroutes are automatically registered in a
\TYPO3\CMS\Core\Routing\RouteCollection
. The full syntax for route identifiers is<module_identifier>.<sub_route>
, for example,my_module.edit
. Therefore, using the\TYPO3\CMS\Backend\Routing\UriBuilder
to create a link to such a subroute might look like this:\TYPO3\CMS\Backend\Routing\UriBuilder->buildUriFromRoute('my_module.edit')
Extbase module configuration options¶
- extensionName¶
- Scope
Backend module configuration
- Type
string
The extension name in UpperCamelCase for which the module is registered. If the extension key is
my_example_extension
the extension name would beMyExampleExtension
.
- controllerActions¶
- Scope
Backend module configuration
- Type
array
Define the controller action pair. The array keys are the controller class names and the values are the actions, which can either be defined as array or comma-separated list:
EXT:my_extension/Configuration/Backend/Modules.php¶return [ 'web_ExtkeyExample' => [ //... 'path' => '/module/web/ExtkeyExample', 'controllerActions' => [ ModuleController::class => [ 'list', 'detail', ], ], ], ];
Changed in version 12.2.
The modules define explicit routes for each controller/action combination, as long as the
enableNamespacedArgumentsForBackend
feature toggle is turned off (which is the default). This effectively means human-readable URLs, since the controller/action combinations are no longer defined via query parameters, but are now part of the path.This leads to the following URLs:
https://example.com/typo3/module/web/ExtkeyExample
https://example.com/typo3/module/web/ExtkeyExample/MyModuleController/list
https://example.com/typo3/module/web/ExtkeyExample/MyModuleController/detail
The route identifier of corresponding routes is registered with similar syntax as standard backend modules:
<module_identifier>.<controller>_<action>
. Above configuration will therefore register the following routes:web_ExtkeyExample
web_ExtkeyExample.MyModuleController_list
web_ExtkeyExample.MyModuleController_detail
View registered modules¶
All registered modules are stored as objects in a registry. They can be viewed in the backend in the System > Configuration > Backend Modules module.

Exploring registered Backend Modules in the Configuration module¶
The ModuleProvider API allows extension authors to work with the registered modules.