Lernseite · Backend-Entwicklung
Das TYPO3-Backend erweitern: Module, JavaScript und Meldungen
Das Backend ist der Arbeitsplatz von Redakteuren und Administratoren. Extensions erweitern es um Module, JavaScript, AJAX, Meldungen, Dashboard-Widgets und einen angepassten Rich-Text-Editor. Auf dieser Seite baust du Schritt für Schritt ein Modul für Konferenzanmeldungen.
Module im Backend
Ein Backend-Modul ist eine eigene Ansicht im Backend, die du über das Modulmenü links aufrufst. Auch Layout, Records, Media oder Users sind nichts anderes als registrierte Module. Ein Modul sehen nur angemeldete Backend-Benutzer. Ein Frontend-Plugin ist dagegen ein Inhaltselement für Besucher der Website.
Module sind in Hauptmodule und Untermodule gegliedert. TYPO3 14 hat sie umbenannt, damit die Namen den Zweck zeigen:
- Aus Web wurde Content mit dem Identifier
content. - Aus File wurde Media mit dem Identifier
media. - Aus Site Management wurde Sites, der Identifier
sitebleibt. - Aus Admin Tools wurde Administration mit dem Identifier
admin, für Module nur für Administratoren. - System enthält Werkzeuge für System-Maintainer.
Bei den Untermodulen heißt Page jetzt Layout, List heißt Records, View heißt Preview und Workspaces heißt Publish. Alte Identifier funktionieren über Aliase weiter. Ein Modul unter dem alten Eltern-Identifier web stellst du aber auf content um. Der Upgrade-Wizard „Migrate module permissions“ überträgt die Rechte geänderter Identifier.
Ein Modul anmelden
Unser Beispiel ist die Extension my_extension mit einem Modul „Konferenzen“. Jedes Modul wird in Configuration/Backend/Modules.php angemeldet. Die Datei gibt ein Array zurück, der Schlüssel ist der Modul-Identifier.
return [
'content_conferences' => [
'parent' => 'content',
'access' => 'user',
'workspaces' => 'live',
'labels' => 'my_extension.module',
'iconIdentifier' => 'my-extension-module',
'navigationComponent' => '@typo3/backend/tree/page-tree-element',
'routes' => [
'_default' => ['target' => ConferenceModuleController::class . '::listAction'],
],
],
];parentordnet das Modul unter einem Hauptmodul ein.accessregelt, wer es sieht.labelsnennt seit TYPO3 14 einfach eine Translation Domain. Die XLIFF-Datei dahinter enthält die Schlüssel title, description und short_description. Die Kurzbeschreibung erscheint als Tooltip.iconIdentifiernennt ein Icon, das du inConfiguration/Icons.phpmit Identifier, Provider und Quelldatei registrierst.navigationComponentzeigt links einen Baum, hier den Seitenbaum.workspaceskennt Stern für überall, live und offline für Entwurfs-Workspaces.
Neu in TYPO3 14: showSubmoduleOverview zeigt die erlaubten Untermodule als Karten. Die Option dependsOnSubmodules unter appearance blendet das Modul aus, wenn kein Untermodul verfügbar ist.
Prüfen, was registriert ist: Die System-Extension lowlevel bringt das Modul System, Configuration mit. Unter Backend Modules siehst du jedes Modul mit seiner Konfiguration. Zur Laufzeit ist sie unveränderlich, das alte Array TBE_MODULES gibt es nicht mehr. Außerdem zeigt das Modul TYPO3_CONF_VARS, das TCA, die Backend-Routen und die Reihenfolge der HTTP-Middlewares. Unter Event Listeners steht jeder PSR-14-Listener je Event in seiner Reihenfolge. Fehlt dein Listener dort, stimmt meist die Registrierung oder der Cache nicht. Zugangsdaten zur Datenbank sind maskiert. Seit TYPO3 14 zeigt das Modul auch die Persistenz-Konfiguration von Extbase. Auf der Konsole bietet lowlevel cleanup:missingrelations, cleanup:orphanrecords, cleanup:deletedrecords und configuration:show, seit TYPO3 14 auch configuration:set und configuration:remove.
Wer das Modul sehen darf
Die Option access kennt drei eingebaute Werte:
user: Redakteure sehen das Modul, wenn es in ihrer Backend-Benutzergruppe erlaubt ist.admin: nur Administratoren. Solche Module gehören unter Administration. Die Einordnung allein schützt aber nichts.systemMaintainer: nur System-Maintainer. Solche Module gehören unter System.
Access Gates: Seit TYPO3 14.2 ergänzt du eigene Regeln. Eine Klasse implementiert ModuleAccessGateInterface und antwortet mit Granted, Denied oder Abstain. Du meldest sie mit dem Attribut AsModuleAccessGate und einem Identifier wie conferenceManager an. Mit before und after ordnest du die Gates. Im Modul setzt du access dann auf conferenceManager.
Sudo-Modus: Für sensible Module verlangt TYPO3 vorher noch einmal das eigene Passwort oder das Install-Tool-Passwort. Dazu setzt du sudoMode unter routeOptions, mit Gruppe und Lebensdauer. Innerhalb der Gruppe gilt die Freigabe auch für andere Module.
'routeOptions' => [
'sudoMode' => ['group' => 'conferenceAdmin', 'lifetime' => AccessLifetime::veryShort],
],Rechte im Code: Einzelne Aktionen im Modul prüfst du selbst. Der angemeldete Benutzer ist ein Objekt der Klasse BackendUserAuthentication.
$backendUser = $GLOBALS['BE_USER'];
$isAdmin = $backendUser->isAdmin();
$isAdmin = $context->getPropertyFromAspect('backend.user', 'isAdmin');
$mayEdit = $backendUser->check('tables_modify', 'tx_myextension_registration');
$mayExport = $backendUser->getTSConfig()['options.']['myextension.']['enableExport'] ?? false;check() sucht in den zusammengefassten Gruppenrechten wie tables_modify oder modules und liefert für Administratoren immer true. Die Context API lässt sich in Tests leichter ersetzen. User TSconfig hängt an Benutzern und Gruppen und passt deshalb für Schalter wie „Export erlaubt“.
Der Modul-Controller
Ein Controller ohne Extbase ist eine Klasse mit dem Attribut AsController. Es setzt das Service-Tag backend.controller. Dadurch ist die Klasse im Container öffentlich, und TYPO3 erzeugt sie samt Abhängigkeiten. Ohne Attribut setzt du das Tag in der Services.yaml. Die Anmeldung in Modules.php bleibt trotzdem nötig.
Jede Action bekommt einen PSR-7-Request vom Typ ServerRequestInterface und gibt ein ResponseInterface zurück. Parameter liest du mit getQueryParams() oder getParsedBody(), nicht mit echo und Superglobals.
Das Aussehen der Core-Module liefert das ModuleTemplate: Layout und DocHeader, also die Kopfzeile mit Breadcrumb, Buttons und Menüs.
public function listAction(ServerRequestInterface $request): ResponseInterface
{
$view = $this->moduleTemplateFactory->create($request);
$view->assignMultiple(['registrations' => $this->registrationRepository->findAll()]);
return $view->renderResponse('Registration/List');
}Mit Extbase erweitert der Controller ActionController, und in Modules.php stehen extensionName und controllerActions statt routes. Auch dann nimmst du das ModuleTemplate, nicht die View des Controllers und nicht htmlResponse.
Unterrouten: Neben der Pflichtroute _default trägst du unter routes etwa edit ein. Sie heißt dann content_conferences.edit, also Modul-Identifier, Punkt, Unterroute.
Request-Attribute: module enthält das aufgerufene Modul als ModuleInterface. moduleData enthält die gemerkten Einstellungen des Benutzers für dieses Modul. Erlaubte Parameter und Standardwerte legt die gleichnamige Option in Modules.php fest.
Buttons: Seit TYPO3 14 erzeugt die injizierte ComponentFactory die Buttons im DocHeader. Die make-Methoden der ButtonBar sind veraltet und fallen mit TYPO3 15 weg.
$button = $this->componentFactory->createLinkButton()
->setHref($newUrl)
->setTitle('Neue Anmeldung')
->setIcon($this->iconFactory->getIcon('actions-add', IconSize::SMALL));
$view->getDocHeaderComponent()->getButtonBar()->addButton($button);Icons holst du über die IconFactory mit dem Enum IconSize. Es ersetzt die alten Größen-Konstanten. In Fluid macht das der ViewHelper core:icon.
Seiten, Datensätze und Links
Mit Seitenbaum ruft das Backend das Modul bei jedem Klick mit dem Parameter id auf. Diese Zahl kann jeder in der URL ändern. Also prüfst du, ob der Benutzer die Seite sehen darf.
$id = (int)($request->getQueryParams()['id'] ?? 0);
$page = BackendUtility::readPageAccess($id, $backendUser->getPagePermsClause(Permission::PAGE_SHOW));Weitere Helfer aus BackendUtility:
getRecord()lädt eine Zeile per UID ohne gelöschte Datensätze, prüft aber keine Rechte.getRecordTitle()bildet den Titel wie überall im Backend, nach label, label_alt und label_userFunc im ctrl-Bereich.getPagesTSconfig()liefert das Page TSconfig der Seite, Unterseiten können Werte überschreiben. Die DateiConfiguration/page.tsconfigeiner Extension lädt TYPO3 14 automatisch.
Links: Backend-URLs enthalten ein Sicherheits-Token, feste Links funktionieren nicht. Du baust sie mit dem Backend-UriBuilder und buildUriFromRoute(). Das Bearbeitungsformular ist die Route record_edit. Zum Bearbeiten übergibst du Tabelle, UID und edit, zum Anlegen Tabelle, Seiten-ID und new. Die returnUrl bestimmt, wohin Schließen führt.
$newUrl = $this->uriBuilder->buildUriFromRoute('record_edit', [
'edit' => ['tx_myextension_registration' => [12 => 'new']],
'returnUrl' => (string)$request->getUri(),
]);
$editUrl = $this->uriBuilder->buildUriFromRoute('content_conferences.edit');In Fluid nimmst du be:link.editRecord mit uid und table. Die Frontend-Vorschau einer Seite baut PreviewUriBuilder mit create und buildUri, samt Slug und Sprache.
JavaScript im Backend
JavaScript läuft im Browser und liegt deshalb unter Resources/Public. Nur dieser Ordner ist öffentlich. Resources/Private liest nur der Server, etwa Templates und Sprachdateien.
Das Backend nutzt native ES-Module mit import und export. RequireJS wurde in TYPO3 13 entfernt. In Configuration/JavaScriptModules.php meldest du deine Module an, daraus baut TYPO3 eine Import-Map. Ein Eintrag mit Schrägstrich am Ende ordnet ein Präfix einem Ordner zu. Ein Eintrag ohne ordnet einen Namen einer einzelnen Datei zu, etwa für chart.js. Unter dependencies stehen Extensions, deren Import-Map ebenfalls geladen sein muss. Den Ordner node_modules liefert der Webserver nicht aus.
return [
'dependencies' => ['core', 'backend'],
'imports' => [
'@my-vendor/my-extension/' => 'EXT:my_extension/Resources/Public/JavaScript/',
'chart.js' => 'EXT:my_extension/Resources/Public/JavaScript/Contrib/chart.js',
],
];Laden: In PHP mit loadJavaScriptModule() am PageRenderer, in Fluid mit f:be.pageRenderer und includeJavaScriptModules. Die Import-Map gibt TYPO3 nur aus, wenn wirklich ein Modul geladen wird.
import Modal from '@typo3/backend/modal.js';
import DocumentService from '@typo3/core/document-service.js';
import RegularEvent from '@typo3/core/event/regular-event.js';
import DebounceEvent from '@typo3/core/event/debounce-event.js';
import labels from '~labels/my_extension.module';
DocumentService.ready().then(() => {
new RegularEvent('click', (event, button) => {
const modal = Modal.confirm(labels.get('delete.title'), labels.get('delete.text'));
modal.addEventListener('confirm.button.ok', () => { /* löschen */ modal.hideModal(); });
}).delegateTo(document.querySelector('#registrations'), '.js-delete');
new DebounceEvent('input', search, 300).bindTo(document.querySelector('#search'));
});- DocumentService wartet auf das fertige DOM, auch wenn dein Modul später geladen wird.
- Modal zeigt Dialoge im Backend-Stil. confirm blockiert nicht, sondern gibt den Dialog zurück. Er löst confirm.button.ok oder confirm.button.cancel aus, hideModal schließt ihn.
- Labels importierst du seit TYPO3 14.2 als virtuelles Modul aus der Translation Domain. Sie sind je Version und Sprache cachebar.
- Jeder import braucht die Endung .js, nur in TypeScript fehlt sie.
Die Event API liegt über addEventListener. bindTo hängt den Listener an ein Element, an document oder window. delegateTo hängt ihn an ein umgebendes Element und prüft einen Selektor, so greift er auch für später eingefügte Zeilen. release entfernt ihn. Es gibt vier Strategien:
- RegularEvent ist der normale Listener.
- DebounceEvent löst erst nach einer Pause aus, gut für Suchfelder.
- ThrottleEvent löst höchstens in festen Abständen aus, gut für Scrollen.
- RequestAnimationFrameEvent läuft im Takt, in dem der Browser neu zeichnet.
AJAX im Backend
Eine Anmeldung soll per Klick bestätigt werden, ohne Neuladen. Dafür meldest du eine Route in Configuration/Backend/AjaxRoutes.php an, mit path und target. Ein eigenes PHP-Skript im öffentlichen Ordner wäre falsch. Die Route läuft im TYPO3-Kontext mit Backend-Anmeldung, Dependency Injection und Konfiguration.
return [
'myextension_registration_confirm' => [
'path' => '/my-extension/registration/confirm',
'target' => AjaxController::class . '::confirmAction',
'inheritAccessFromModule' => 'content_conferences',
],
];Der Controller gibt meist eine JsonResponse zurück. Sie kodiert ein Array als JSON und setzt den Content-Type. Nach Änderungen leerst du die Caches. Im JavaScript steht die URL dann unter TYPO3.settings.ajaxUrls mit dem Namen der Route.
import AjaxRequest from '@typo3/core/ajax/ajax-request.js';
const response = await new AjaxRequest(TYPO3.settings.ajaxUrls.myextension_registration_confirm)
.withQueryArguments({ registration: 17 })
.get();
const data = await response.resolve();AjaxRequest kennt get, post, put und delete und liefert jeweils ein Promise.
Meldungen an den Benutzer
Nach dem Speichern soll „Gespeichert“ erscheinen. Dafür gibt es Flash-Messages. Ihre Schwere wählst du mit dem Enum ContextualFeedbackSeverity und seinen fünf Fällen NOTICE, INFO, OK, WARNING und ERROR. Erfolg heißt OK, nicht SUCCESS. DEBUG und CRITICAL sind Log-Stufen nach PSR-3.
- In Extbase rufst du
addFlashMessage()am Controller auf. Die Meldung landet standardmäßig in der Session und übersteht einen Redirect. Die Queue heißt extbase.flashmessages plus Namensraum des Plugins. - Mit dem ModuleTemplate rufst du dessen
addFlashMessage()auf. Auch das speichert standardmäßig in der Session. - Von Hand erzeugst du eine
FlashMessage. DenFlashMessageServiceholst du per Dependency Injection. getMessageQueueByIdentifier ohne Argument liefert die Standard-Queuecore.template.flashMessages, enqueue reiht die Meldung ein.
Der ViewHelper f:flashMessages gibt alle wartenden Meldungen aus und leert die Queue. Er funktioniert in jedem Kontext, weil er einen passenden Renderer ermittelt. Andere Queues gibst du mit queueIdentifier aus.
Soll eine Meldung aus PHP als schwebende Notification erscheinen, legst du sie in die Queue FlashMessageQueue::NOTIFICATION_QUEUE.
Notifications in JavaScript meldet nach unserem AJAX-Aufruf „Teilnahme bestätigt“. Die API ist nur für das Backend gedacht.
import Notification from '@typo3/backend/notification.js';
Notification.success('Bestätigt', 'Die Teilnahme ist gespeichert.');Es gibt notice, info, success, warning und error. Die Dauer gibst du in Sekunden an, Standard sind 5. Fehler bleiben stehen, denn 0 schaltet den Timer ab. Aktions-Buttons in Notifications sind optional. Für eine echte Entscheidung nimmst du ein Modal.
Dashboard-Widgets
Das Dashboard ist meist das erste Modul im Backend, eine persönliche Startseite. Jeder Benutzer ordnet dort Widgets an, etwa Kennzahlen, Listen oder Diagramme. Welche Widgets Redakteure hinzufügen dürfen, steuern die Gruppenrechte.
Für „Anmeldungen heute“ brauchst du keine eigene Widget-Klasse. Du kombinierst ein Core-Widget mit einem eigenen Data Provider. Für eine Kennzahl implementiert er NumberWithIconDataProviderInterface, für eine Liste ListDataProviderInterface. Für ein Balkendiagramm implementiert er ChartDataProviderInterface und wird dem BarChartWidget übergeben.
Registriert wird das Widget als Service in der Services.yaml mit dem Tag dashboard.widget.
dashboard.widget.my_vendor.my_extension.registrationsToday:
class: 'TYPO3\CMS\Dashboard\Widgets\NumberWithIconWidget'
arguments:
$dataProvider: '@MyVendor\MyExtension\Dashboard\RegistrationsTodayDataProvider'
tags:
- name: dashboard.widget
identifier: 'myExtensionRegistrationsToday'
groupNames: 'conferences'
title: 'my_extension.dashboard:registrationsToday.title'
description: 'my_extension.dashboard:registrationsToday.description'
iconIdentifier: 'content-widget-number'
height: 'small'
width: 'small'Über groupNames gehört ein Widget zu einer oder mehreren Gruppen, die im Dialog zum Hinzufügen erscheinen. Eine eigene Gruppe legst du in der Datei DashboardWidgetGroups.php im Ordner Configuration, Backend an, mit Identifier und Titel.
Neu in TYPO3 14 ist das WidgetRendererInterface. Ein Widget definiert damit in getSettingsDefinitions() Einstellungen je Instanz, die Redakteure direkt im Dashboard ändern. So läuft das RSS-Widget mehrfach mit verschiedenen Feeds.
Vorlage für neue Benutzer: In DashboardPresets.php im selben Ordner beschreibst du ein Preset mit Titel, Icon und defaultWidgets. Zugewiesen wird es per User TSconfig.
options.dashboard.dashboardPresetsForNewUsers = conferencesDer Rich-Text-Editor
Für formatierten Text bringt TYPO3 seit Version 12 CKEditor 5 mit, über die System-Extension rte_ckeditor. Ein Feld bekommt den Editor, wenn es im TCA vom Typ text ist und enableRichtext auf true steht. Einen Typ richtext gibt es nicht.
Die Toolbar bestimmt ein Preset in YAML. Der Core bringt default, minimal und full mit, eigene Presets binden sie per imports ein.
$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['conference'] = 'EXT:my_extension/Configuration/RTE/Conference.yaml';
// Page TSconfig: RTE.default.preset = conference
// TCA des Feldes: 'richtextConfiguration' => 'conference'Das TypoScript lib.parseFunc_RTE gibt den Text später im Frontend aus und hat mit dem Editor nichts zu tun.
Per Code anpassen: Mit den PSR-14-Events BeforePrepareConfigurationForEditorEvent und AfterPrepareConfigurationForEditorEvent änderst du die Editor-Konfiguration, etwa die Toolbar je Benutzer. Für externe Plugins gibt es ein Before- und ein AfterGetExternalPluginsEvent.
Ein anderer Editor: rte_ckeditor meldet in der FormEngine einen nodeResolver für text-Felder mit enableRichtext an. Dein eigener nodeResolver mit höherer Priorität ersetzt ihn.
Das Wichtigste in Kürze
- Die Hauptmodule heißen seit TYPO3 14 Content, Media, Sites, Administration und System.
- Module stehen in
Modules.php. Nach Änderungen leerst du die Caches. - access kennt user, admin und systemMaintainer, seit TYPO3 14.2 auch eigene Access Gates.
- Modul-Controller nehmen einen PSR-7-Request und antworten über das ModuleTemplate.
- Backend-Links baut der UriBuilder, Buttons die ComponentFactory.
- JavaScript sind ES-Module, angemeldet über eine Import-Map.
- AJAX-Routen darf jeder angemeldete Backend-Benutzer aufrufen.
- Der FlashMessage-Konstruktor speichert nicht in der Session, Extbase und ModuleTemplate schon.
Begriffe
- Access Gate
- Klasse, die seit TYPO3 14.2 über den Zugriff auf ein Modul entscheidet.
- ComponentFactory
- Erzeugt seit TYPO3 14 Buttons und Menüs für den DocHeader.
- Data Provider
- Liefert einem fertigen Dashboard-Widget die Daten.
- DocHeader
- Kopfzeile eines Backend-Moduls mit Breadcrumb, Buttons und Menüs.
- Import-Map
- Ordnet Namen von JavaScript-Modulen echten Dateien zu.
- Notification
- Schwebende Benachrichtigung am Rand des Backends.
- Sudo-Modus
- Erneute Passwortabfrage vor einem sensiblen Modul.