TMENU in TYPO3: Navigationen mit HMENU und TypoScript erstellen – mit Codebeispielen
Was ist TMENU? Grundprinzip und Aufgabe
TYPO3 baut Menüs aus zwei Objekten auf: HMENU und TMENU. Beide sind aufeinander angewiesen und werden fast immer zusammen verwendet.
- HMENU (Hierarchical Menu): Erzeugt die hierarchische Menüstruktur auf Basis des TYPO3-Seitenbaums. HMENU entscheidet, welche Seiten in das Menü aufgenommen werden, in welcher Reihenfolge und aus welchem Startpunkt.
- TMENU (Text Menu): Rendert eine einzelne Menüebene. TMENU definiert, wie die Seiten einer Ebene als HTML ausgegeben werden – welche Elemente, Klassen, Attribute und Zustände verwendet werden.
Das bedeutet: HMENU liefert die Daten, TMENU erzeugt das Markup. Für jede Menüebene kann eine eigene TMENU-Konfiguration hinterlegt werden – so lassen sich Hauptnavigation, Dropdown und Untermenü unterschiedlich darstellen.
HMENU und TMENU: Grundaufbau in TypoScript
Ein einfaches HMENU mit TMENU sieht in TypoScript so aus:
lib.navigation = HMENU lib.navigation { 1 = TMENU 1 { NO { allWrap = <li> | </li> ATagParams = class="nav-link" } ACT = 1 ACT { allWrap = <li class="active"> | </li> ATagParams = class="nav-link active" } } } |
In diesem Beispiel definiert das HMENU eine erste Ebene (1 = TMENU). Innerhalb von TMENU werden zwei Zustände konfiguriert: NO (Normal) für alle Standardseiten und ACT (Active) für die aktuell aktive Seite.
TMENU-Zustände: NO, ACT, CUR, IFSUB und mehr
TMENU kennt verschiedene Zustände, die bestimmen, wie ein Menüpunkt gerendert wird – je nach Position und Kontext im Seitenbaum. Das Verstehen dieser Zustände ist der Schlüssel zur sauberen TMENU-Konfiguration.
- NO (Normal): Standardzustand für alle Menüpunkte, die weder aktiv noch im aktiven Pfad sind.
- ACT (Active): Die aktuell aufgerufene Seite liegt im aktuellen Menüpfad, aber ist nicht die aktuelle Seite selbst.
- CUR (Current): Die exakt aktuelle Seite – die Seite, die gerade angezeigt wird.
- IFSUB (If Subpages): Menüpunkt hat Unterseiten – nützlich für Dropdown-Indikatoren.
- SPC (Spacer): Seiten, die als Trennelemente markiert sind.
- USERDEF1 / USERDEF2: Selbst definierbare Zustände für individuelle Anforderungen.
lib.navigation.1 { NO { allWrap = <li class="nav-item"> | </li> ATagParams = class="nav-link" } CUR = 1 CUR { allWrap = <li class="nav-item current"> | </li> ATagParams = class="nav-link current" aria-current="page" } ACT = 1 ACT { allWrap = <li class="nav-item active"> | </li> ATagParams = class="nav-link active" } IFSUB = 1 IFSUB { allWrap = <li class="nav-item has-children"> | </li> ATagParams = class="nav-link" aria-haspopup="true" } } |
Häufiger Fehler: CUR und ACT verwechseln CUR ist die exakt aktuelle Seite. ACT sind alle Seiten im aktiven Pfad – also Elternseiten der aktuellen Seite. Wenn eine Seite aktiv ist, ist CUR gesetzt, ihre Elternseiten haben ACT. Wer das verwechselt, bekommt falsche CSS-Klassen im Menü. |
Mehrstufige Navigation: Mehrere Ebenen mit TMENU
Für mehrstufige Navigationen werden mehrere TMENU-Ebenen innerhalb eines HMENU definiert. Jede Ebene kann eigene Zustände, Wrapper und Klassen haben:
lib.navigation = HMENU lib.navigation { # Ebene 1: Hauptnavigation 1 = TMENU 1 { wrap = <ul class="main-nav"> | </ul> NO { allWrap = <li> | </li> ATagParams = class="nav-link" } ACT = 1 ACT.allWrap = <li class="active"> | </li> } # Ebene 2: Dropdown 2 = TMENU 2 { wrap = <ul class="dropdown-menu"> | </ul> NO { allWrap = <li class="dropdown-item"> | </li> } } } |
expAll: Alle Unterseiten immer anzeigen
Standardmäßig zeigt TYPO3 Unterebenen nur entlang des aktiven Pfades an. Mit expAll = 1 werden alle Unterseiten immer ausgegeben – unabhängig vom aktiven Pfad. Das ist typisch fuer Dropdown-Menüs und Megamenüs.
lib.navigation.1 { expAll = 1 } |
Wichtig: expAll bezieht sich auf die jeweilige Ebene. Wenn alle Ebenen aufgeklappt sein sollen, muss expAll für jede TMENU-Ebene gesetzt werden.
Upgrade-Fallen: Was bei TYPO3-Updates zu beachten ist
TMENU-Konfigurationen in gewachsenen TYPO3-Projekten sind häufig eine Quelle von Problemen bei Major-Upgrades. Die wichtigsten Aenderungen im Überblick:
TYPO3 v9: Neue Empfehlung MenuProcessor + Fluid
Ab TYPO3 v9 wurde MenuProcessor als empfohlener Weg für neue Navigationen eingefuehrt. TMENU blieb funktionsfaehig, wird aber seitdem als Legacy-Ansatz betrachtet. Bestehende Projekte können weiter mit TMENU arbeiten, neue Projekte sollten MenuProcessor verwenden.
TYPO3 v12: collapse entfernt
Die TMENU-Eigenschaft collapse wurde in TYPO3 v12 entfernt. Wer Menüpunkte filtern oder dynamisch ein-/ausblenden wollte, muss auf PSR-14 Events umsteigen – konkret auf das FilterMenuItemsEvent.
# Statt collapse (deprecated/entfernt ab v12): # Moderne Alternative: PSR-14 Event in einer Extension # \Vendor\Extension\EventListener\MenuItemsFilter::__invoke() # registriert ueber Configuration/Services.yaml |
TYPO3 v13: Weitere Bereinigungen
In TYPO3 v13 wurden weitere veraltete TypoScript-Eigenschaften entfernt. Wer TMENU-Konfigurationen aus aelteren Projekten uebernimmt, sollte die TYPO3-Deprecation-Logs sorgfaeltig pruefen, bevor er ein Upgrade durchfuehrt.
Upgrade-Tipp Vor jedem TYPO3-Major-Upgrade TMENU-Konfigurationen gegen die aktuellen Changelog-Eintrage pruefen. Der TYPO3 Upgrade Wizard weist auf viele Deprecations hin, aber nicht auf alle TypoScript-Aenderungen. creationell prueft im Rahmen von Upgrade-Projekten alle bestehenden TypoScript-Konfigurationen systematisch. |
TMENU vs. MenuProcessor + Fluid: Wann was verwenden?
| Kriterium | HMENU / TMENU | MenuProcessor + Fluid |
|---|---|---|
| Ansatz | HMENU / TMENU (TypoScript) | MenuProcessor + Fluid |
| Verfuegbar ab | TYPO3 4.x und aelter | TYPO3 8 LTS (empfohlen ab v9) |
| Markup-Kontrolle | Direkt in TypoScript definiert | Im Fluid-Template, sauber getrennt |
| Wartbarkeit | Komplex bei groesseren Projekten | Hoch – Daten und Markup getrennt |
| Barrierefreiheit | Aufwendig umsetzbar | Einfacher durch sauberes HTML |
| Empfehlung | Bestandsprojekte / Legacy | Neue Projekte und Relaunches |
| TYPO3 v13 kompatibel | Ja, aber veraltet | Ja, empfohlen |
MenuProcessor + Fluid: So sieht die moderne Alternative aus
Für neue TYPO3-Projekte und Relaunches ist MenuProcessor + Fluid die klar empfohlene Methode. Der Unterschied: Die Menüdaten werden per DataProcessing aufbereitet und an ein Fluid-Template uebergeben – saubere Trennung von Logik und Markup.
TypoScript-Konfiguration mit MenuProcessor
lib.navigation = FLUIDTEMPLATE lib.navigation { file = EXT:my_sitepackage/Resources/Private/Templates/Navigation.html dataProcessing { 10 = TYPO3\CMS\Frontend\DataProcessing\MenuProcessor 10 { levels = 2 as = mainNavigation expandAll = 1 includeSpacer = 0 titleField = nav_title // title } } } |
Fluid-Template für die Navigation
<nav aria-label="Hauptnavigation"> <ul class="main-nav"> <f:for each="{mainNavigation}" as="item"> <li class="nav-item{f:if(condition: item.active, then: ' active')}"> <a href="{item.link}" class="nav-link{f:if(condition: item.current, then: ' current')}" {f:if(condition: item.current, then: 'aria-current="page"')}> {item.title} </a> <f:if condition="{item.children}"> <ul class="dropdown-menu"> <f:for each="{item.children}" as="child"> <li> <a href="{child.link}" class="dropdown-item"> {child.title} </a> </li> </f:for> </ul> </f:if> </li> </f:for> </ul> </nav> |
Der entscheidende Vorteil: Das Fluid-Template ist reines HTML mit eingebetteten Fluid-Variablen. Designer können das Markup direkt bearbeiten, ohne TypoScript zu kennen. Barrierefreiheitsanforderungen sind einfacher umzusetzen, da aria-Attribute direkt im Template stehen.
Best Practices für TMENU in Bestandsprojekten
- Sauber dokumentieren: Jede TMENU-Konfiguration mit Kommentaren versehen – wer hat das wann gebaut und warum?
- Zustände vollstaendig definieren: NO, ACT, CUR und IFSUB sollten immer explizit konfiguriert sein – kein implizites Fallback-Verhalten
- CSS-Klassen konsistent benennen: Eine Namenskonvention für alle Menü-Klassen definieren und durchhalten
- expAll bewusst einsetzen: Nur da verwenden, wo wirklich alle Unterseiten benoetigt werden – sonst Performance-Einbussen
- Upgrade-Logs lesen: Vor jedem TYPO3-Update die Release Notes auf TMENU-relevante Aenderungen pruefen
- Barrierefreiheit nachruesten: aria-current, aria-haspopup und aria-expanded soweit moeglich auch in TMENU integrieren
TMENU mit creationell: TYPO3-Expertise aus der Praxis
creationell betreut TYPO3-Installationen seit den fruehen Versionen – und kennt HMENU/TMENU-Konfigurationen aus hunderten realer Projekte. Ob Wartung bestehender Legacy-Navigation, Upgrade-Pruefung vor TYPO3-Versionswechsel oder Migration auf MenuProcessor + Fluid: Wir analysieren, dokumentieren und setzen um – praxisnah und mit Blick auf langfristige Wartbarkeit.
TYPO3 Navigation optimieren – creationell unterstützt Sie Ob TMENU-Wartung, TYPO3-Upgrade oder Migration auf MenuProcessor + Fluid: creationell entwickelt und pflegt TYPO3-Navigationen fuer Unternehmen im Mittelstand – inhouse, aus Augsburg, mit jahrelanger TYPO3-Projekterfahrung. Mehr zu TYPO3 bei creationell: creationell.de/digitale-medien/typo3-augsburg creationell GmbH & Co. KG | Provinostrasse 52 | 86153 Augsburg | Tel. 0821 50241-20 |
Erstellt: Mai 2026
TMENU ist ein TypoScript-Objekt, das in TYPO3 zur Ausgabe einer einzelnen Menüebene verwendet wird. Es wird meist zusammen mit HMENU eingesetzt, das die Menüstruktur aus dem Seitenbaum liefert, während TMENU das Rendering und die Zustände der Navigation steuert.
HMENU erzeugt die logische und hierarchische Struktur eines Menüs auf Basis des Seitenbaums. TMENU übernimmt anschließend die Darstellung einer bestimmten Menüebene und definiert unter anderem HTML-Struktur, CSS-Klassen und Zustände wie aktiv oder im Pfad.
TMENU ist vor allem in bestehenden und gewachsenen TYPO3-Projekten weiterhin relevant. Für neue Projekte oder umfassende Relaunches empfiehlt sich in vielen Fällen jedoch der modernere Ansatz mit MenuProcessor und Fluid, weil dieser wartungsfreundlicher und flexibler ist
Der Einsatz von MenuProcessor und Fluid lohnt sich besonders bei neuen TYPO3-Websites, bei komplexen Navigationen und überall dort, wo Barrierefreiheit, saubere Trennung von Logik und Markup sowie langfristige Wartbarkeit eine wichtige Rolle spielen.
Häufige Herausforderungen sind unübersichtliche TypoScript-Konfigurationen, die Vermischung verschiedener Menüzustände, fehlende Accessibility bei Dropdowns und Probleme nach TYPO3-Upgrades, wenn Properties verändert oder entfernt wurden.
Wichtig sind eine saubere Zustandslogik, klar definierte CSS-Klassen, schlankes Markup und die Prüfung von Breaking Changes bei TYPO3-Upgrades. Gerade in Legacy-Projekten lohnt es sich, die Navigation gut zu dokumentieren und ihre Zukunftsfähigkeit regelmäßig zu bewerten.