New in version 12.0

All Fluid templates rendered by backend controllers can be overridden with own templates on a per-file basis. The feature is available for basically all core backend modules, as well as the backend main frame templates. Exceptions are email templates and templates of the install tool.

Basic syntax

The various combinations are best explained by example:

The linkvalidator extension (its composer name is typo3/cms-linkvalidator) comes with a backend module in the Web main section. The page tree is displayed for this module and linkvalidator has two main views and templates:

Resources/Private/Templates/Backend/Report.html for the Report view and another for the Check link view. To override the Backend/Report.html file with a custom template, this definition can be added to the Configuration/page.tsconfig file of an extension:

# Left pattern (before equal sign): templates."composer-name"."something-unique"
# Right pattern (after equal sign): "overriding-extension-composer-name":"entry-path"
templates.typo3/cms-linkvalidator {
    1643293191 = my-vendor/my-extension:Resources/Private/TemplateOverrides

If the target extension, identified by its composer name my-vendor/my-extension, provides the Resources/Private/TemplateOverrides/Templates/Backend/Report.html file, this file is used instead of the default template file from the linkvalidator extension.

All core extensions follow the general structure for templates, layouts and partials file. If an extension needs to override a partial that is located in Resources/Private/Partials/SomeName/SomePartial.html, and an override has been specified like above to my-vendor/my-extension:Resources/Private/TemplateOverrides, the system looks for the Resources/Private/TemplateOverrides/Partials/SomeName/SomePartial.html file. Similar is the case for layouts.

Template overriding is based on the existence of files: Two files are never merged. An override definition either takes effect because it actually provides a file at the correct position with the correct file name, or it does not and the default is used. This can become impractical for large template files. In such cases it might be an option to request a split of a large template file into smaller partial files so an extension can override a specific partial only.

Combinations of overrides

Due to the nature of TSconfig and its two types page TSconfig and user TSconfig, various combinations are possible:

  • Define "global" overrides with page TSconfig in Configuration/page.tsconfig of an extension. This works for all modules, regardless of whether the module renders a page tree or not.
  • Define page level overrides via the TSconfig field of page records. As always with page TSconfig, subpages and subtrees inherit these settings from their parent pages.
  • Define overrides on user or (better) group level. As always, user TSconfig can override page TSconfig by prefixing any setting available as page TSconfig with page. in user TSconfig. A user TSconfig template override starts with page.templates. instead of templates..

Usage in own modules

Extensions with backend modules that use the simplified backend module template API automatically enable the general backend template override feature. Extension authors do not need to further prepare their extensions to enable template overrides by other extensions.