Extend your TYPO3 admin using backend modules

on 4th July 2022

(Last updated 5th July 2023)

TYPO3 ships with many backend modules that enable you to manage various site components out of the box (e.g. pages, extensions, backend users, etc.). However, if you, like many of our clients, customise your setup and configure new features you can often feel limited by the default setup.

Being able to configure your own backend modules allows you to mould the TYPO3 backend to fit your business needs.

Below are some simple steps to setting up a basic ‘Hello World’ backend module.

Note: This blog assumes you have a TYPO3 v9.5-10.4.99 instance configured with Extbase already running and are familiar with TYPO3, PHP and command line. If you are unable to set this up yourself please get in touch to discuss how we could assist.

Directory structure

Step 1 - Base extension

Within your local extension directory (e.g. `typo3conf/ext/`) create your extension folder and `ext_emconf.php` file with the following contents filled in with your extension details:

$EM_CONF[$_EXTKEY] = [
	'title' => '',
	'description' => '',
	'category' => 'be',
	'author' => '',
	'author_company' => '',
	'author_email' => '',
	'state' => 'stable',
	'version' => '1.0.0',
	'constraints' => [
		'depends' => [
			'typo3' => '9.5.0-10.4.99',
		],
		'conflicts' => [
		],
		'suggests' => [
		],
	],
];

File path: ./ext_emconf.php

Step 2 - Controller class

Your controller class is what communicates data between your view and backend logic. Each view needs to have a matching action method within your controller. Below is a very simple example of how we pass a variable of `message` to our index view:

namespace Vendor\Extension\Controller;

use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;

class ExampleController extends ActionController
{
    /**
	 * Index Action
	 */
	public function indexAction(): void
	{
		$this->view->assignMultiple([
			'message' => 'Hello World'
		]);
	}
}

If you want to pass multiple variables to the view then you can add the key value pairs to the assignMultiple function.

File path: ./Classes/Controller/ ExampleController.php

Step 3 - Layouts and templates

Now that your controller action has been defined it’s time to set up your template and layout.

Layout

The layout file contains the high level HTML structure and renders partials in for head and body:

<!DOCTYPE html>
<html>
	<head>
		<f:render section="head" />
	</head>
	<body>
		<f:render section="body" />
	</body>
</html>

File path: ./Resources/Private/Layouts/Default.html

Template

The template file then loads the layout and passes in content for the head and body sections. Again, for our basic example, we’re going to pass in a title to the head section and a p tag with our message to the body.

<f:layout name="Default"/>
<f:section name="head">
    <title>
       Example Module
    </title>
</f:section>
<f:section name="body">
    <p>{message}</p>
</f:section>

File path: The location of the template file needs to marry up with your controller and action. For example, our controller class is named ExampleController and our action name is indexAction therefore our template file path is ./Resources/Private/Templates/ Example/Index.html

Step 4 - Language file

Setting up a language file allows you to define a title for your module that will be used in the lefthand-side TYPO3 menu.

<?xml version="1.0" encoding="UTF-8"?>
<xliff version="1.0" xmlns:t3="http://typo3.org/schemas/xliff">
	<file source-language="en" datatype="plaintext" original="messages" date="2011-10-18T18:20:51Z" product-name="vendor_extension">
		<header/>
		<body>
			<trans-unit id="mlang_tabs_tab" xml:space="preserve">
				<source>Example</source>
			</trans-unit>
		</body>
	</file>
</xliff>

File path: ./Resources/Private/Language/ locallang.xlf

Step 5 - Module registration

The final step is to register your module so that it appears in the lefthand-side TYPO3 backend menu.

\TYPO3\CMS\Extbase\Utility\ExtensionUtility::registerModule(
    'Vendor.Extension', // 1
    'web', // 2
    'tx_vendor_extension_example', //3
    'bottom', //4
    [
        Example::class => 'index',
    ], //5
    [
        'access' => 'user,group',
        'labels' => 'LLL:EXT:extension/Resources/Private/Language/locallang.xlf',
        'navigationComponentId' => '',
        'inheritNavigationComponentFromMainModule' => false,
    ] //6
);

File path: ./ext_tables.php

Parameter explanation:

  1. Vendor and extension name concatenated with a dot and typed in upper camel case
  2. The parent module that your module will sit within (e.g. the lefthand-side TYPO3 menu section —> main, system, etc.)
  3. Your module identifier (a combination of tx, vendor, extension and controller shown in snake case)
  4. Your module position within the parent. Options are:
    1. ```top```
    2. ```bottom```
    3. ```before:[sibling module key]```
    4. ```after:[sibling module key]```
  5. An array of allowed controller actions
  6. An array of module configuration. Options are:
    1. ```access```. Options are:
      1. ```user``` - access can be granted per user
      2. ```group``` - access can be granted per group
      3. ```admin``` - access is restricted to admins
      4. ```systemMaintainer``` - access is restricted to system maintainers
    2. ```labels``` - a language file containing the module title
    3. ```icon``` - the module icon used in the lefthand-side TYPO3 menu (defaults to the TYPO3 icon if not set)
    4. ```navigationComponentId``` - set this to a blank string if you want to remove the parent module menu
    5. ```inheritNavigationComponent``` ```FromMainModule``` - set this to false if you want to remove the parent module menu

Step 6 - Enable the extension

Once the above steps have been followed you’re ready to enable the extension. Log in to your TYPO3 admin and head to ADMIN TOOLS —> Extensions and enable ‘Example’ (or whatever title you set). Once this has loaded you should see your module in the TYPO3 menu. Clicking on this should load your ‘Hello World’ message on the right hand side.

Conclusion

Although this is a simple example of a backend module, it gives you the foundation to extend it further and integrate with your specific setup. For example, we recently integrated a backend module with the query builder to give a client a detailed overview of their fe_users and how they were interacting with other elements of the site.

If you think you could benefit from a backend module tailored to your set up then please feel free to get in contact as we would love to see how we could help you.

For a more in-depth explantion of TYPO3 backend modules you can visit the official TYPO3 documentation.

This article was posted in Development, TYPO3 CMS