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.

EXT:my_extension/Configuration/Backend/Modules.php
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, or systemMaintainer.

workspaces
Scope

Backend module configuration

Type

string

Can be * (= always), live or offline

position
Scope

Backend module configuration

Type

array

The module position. Allowed values are top and bottom as well as the key value pairs before => <identifier> and after => <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.

navigationComponent
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.

navigationComponentId
Scope

Backend module configuration

Type

string

The module navigation component (Deprecated: Use navigationComponent)

inheritNavigationComponentFromMainModule
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)

routes
Scope

Backend module configuration

Type

array

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:

EXT:my_extension/Configuration/Backend/Modules.php
routes' => [
    '_default' => [
        'target' => MyController::class . '::handleRequest',
    ],
],

Note

Using additional routes - next to _default - is not yet implemented.

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 be MyExampleExtension.

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_examples' => [
        //...
        'controllerActions' => [
            ModuleController::class => [
                'flash','tree','clipboard','links','fileReference','fileReferenceCreate',
            ],
        ],
    ],
];

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.

../../../_images/BackendModulesConfiguration.png

Exploring registered Backend Modules in the Configuration module

The ModuleProvider API allows extension authors to work with the registered modules.