linkhandler für TYPO3

linkhandler verhindert tote Links, wenn sich URLs ändern

In TYPO3 bezieht sich eine Typolink-Angabe direkt auf eine Seite, eine Datei oder eine URL - nicht auf einen Datensatz. Sobald eine Redaktion im Fließtext auf Events, News-Artikel, Produkte oder Adressen verlinken will, muss sie entweder die URL hart eintragen oder einen Record-Link-Handler einrichten, der aus einer Record-ID eine stabile URL erzeugt. Genau das ist die Aufgabe von linkhandler, seit TYPO3 8.6 kann es auch der Core. Die Extension, ursprünglich von AOE und zuletzt von Cobweb gepflegt, registriert neue Link-Typen im TYPO3-RTE und im Link-Browser und verbindet sie mit beliebigen Datenbank-Tabellen. Bei einem Redaktionsprojekt mit mehr als hundert internen Querverweisen ist das der Unterschied zwischen einer funktionierenden Content-Architektur und einer Friedhof-Seite voller 404-Links.

Typische Einsatzszenarien treten bei jeder Redaktion mit mehr als einer Content-Domain auf

Sobald News, Events und Produkte im selben Projekt existieren, brauchen Redakteure ein sauberes Linking-System. Eine Hochschule verlinkt im Magazin-Artikel auf das Event in sf_event_mgt, im Event-Text auf den beteiligten Autor aus md_news_author und im Autor-Profil zurück auf alle seine Beiträge in GeorgRinger/news. Drei Extensions, drei Record-Typen, und ohne linkhandler wäre jede dieser Querverweise eine harte URL, die beim nächsten Slug-Refactoring bricht. Im Alltag heißt das: Ein einziges URL-Refactoring kann dann dutzende oder hunderte Broken Links erzeugen, die erst Wochen später im Google-Search-Console-Report auftauchen.

Ein zweites Szenario sind E-Commerce-Texte: Produktbeschreibungen, die auf Zubehör verweisen, oder Blog-Artikel, die auf Produkte aus aimeos verlinken. linkhandler erzeugt die URLs automatisch aus der Produkt-Routing-Konfiguration, und bei einem Kategorie-Refactoring wandern sämtliche Links mit.

Drittens tritt der Bedarf bei Standort-Listings auf. Wer eine Filialstruktur oder Ansprechpartner-Verzeichnisse mit tt_address oder einem eigenen Model pflegt, will aus Artikeln heraus auf die jeweilige Detailseite verlinken. Der linkhandler-Link bleibt stabil, selbst wenn der Standort umbenannt wird.

Technische Architektur registriert Linktypen per TSconfig und Handler-Klasse

linkhandler nutzt die LinkBrowser-API des Core, die es seit TYPO3 7.6 gibt; seit 8.6 bringt der Core auch den Record-Link-Handler selbst mit. Jeder Linktyp wird in der Page-TSconfig unter TCEMAIN.linkHandler registriert, mit Handler-Klasse, Tabelle und Beschriftung des Tabs; wie der Link im Frontend entsteht, legt TypoScript fest. Im RTE und im Link-Browser erscheint der Linktyp als neuer Tab: “News”, “Event”, “Produkt”, “Adresse”. Jeder Tab zeigt eine Liste der verfügbaren Datensätze mit Such- und Filterfunktion, sodass Redakteure auch bei tausenden News-Einträgen gezielt den gewünschten Beitrag finden.

Den Tab im Link-Browser stellt eine PHP-Klasse bereit, die von AbstractLinkHandler erbt; im Frontend baut ein Typolink-Handler den Link. Er erzeugt aus der Record-ID über die typolink-Konfiguration in TypoScript den Link zur Detailseite, die sprechende URL liefert das Routing. Im Frontend wird der Typolink mit dem Parameter t3://record aufgerufen und vom Page-Rendering in die finale URL aufgelöst. Das bedeutet: Selbst wenn zehntausende Artikel auf denselben News-Datensatz verlinken, muss bei einer Slug-Änderung nur der Artikel-Datensatz selbst aktualisiert werden - alle Links lösen sich automatisch auf die neue URL auf.

Die Konfiguration greift tief in das TYPO3-Linking-System ein, bleibt aber deklarativ: Nach der Registrierung in TSconfig und TypoScript und dem Cache-Clear steht der neue Linktyp im gesamten Projekt zur Verfügung, einschließlich Fluid-Templates und Menü-Komponenten. Wer linkhandler nicht explizit nutzt, bekommt den Mechanismus seit TYPO3 8.6 über das Core-Linking ebenfalls, samt eigenem Tab im Link-Browser.

Häufige Probleme betreffen Cache, Sprachvarianten und Datei-Handler

Das häufigste Supportthema sind Cache-Inkonsistenzen nach dem Update eines Records. Wenn der Slug eines News-Artikels angepasst wird, muss der Page-Cache des Quell-Artikels, in dem der linkhandler-Link steht, ebenfalls geleert werden - sonst bleibt die alte URL in der Ausgabe stehen. Die Lösung ist, beim Speichern des Datensatzes auch den Cache der verlinkenden Seiten zu leeren, etwa per TCEMAIN.clearCacheCmd in der Page-TSconfig. Viele Installationen richten das nicht ein und kämpfen dann mit vermeintlich defekten Links.

Das zweite Problem sind Sprachvarianten. Ein News-Artikel in DE verweist über linkhandler auf ein Event. Die englische Übersetzung des Artikels soll auf dieselbe Event-ID verweisen, aber die URL in der englischen Sprache erzeugen. Die Auflösung übernimmt das Typolink-Rendering, aber die TypoScript-Konfiguration muss explizit auf die Routing-Varianten der Zielseiten zeigen. Wer Fallback-Sprachen verwendet, muss zusätzlich prüfen, wie sich der Handler bei fehlenden Übersetzungen verhält - er sollte in der Fallback-Sprache auflösen, nicht auf die Hauptsprache zurückfallen.

Drittens ist der Datei-Handler ein Sonderfall. Wer neben Record-Links auch auf TYPO3-FAL-Dateien verlinken will, nutzt dafür den Datei-Handler des Core, linkhandler selbst bringt keinen mit. Die Kombination ist möglich; welcher Tab zuerst erscheint, legen displayBefore und displayAfter in der Page-TSconfig fest.

TYPO3 v12 und v13 nutzen den Core-LinkHandler, Migration lohnt sich

Seit TYPO3 8.6 steckt die Funktion von linkhandler im Core-LinkHandler. Die Extension selbst wird nicht mehr gepflegt: Die letzte Fassung von Cobweb, 3.1.3 von 2016, läuft nur unter TYPO3 7.6. Für TYPO3 v12 und v13 gibt es keine Version; im TER steht nur noch die veraltete AOE-Fassung 0.3.1.

Beim Migrations-Review prüft Gosign, wie viele linkhandler-Aufrufe in den RTE-Inhalten stecken. Bei weniger als 50 Vorkommen lohnt sich oft der Umstieg auf den Core-LinkHandler, bei mehr als 100 Vorkommen oder stark individualisierten Handlern hilft ein Skript, das die Links in das Core-Format t3://record umschreibt. Die Migration auf eine neue Major-Version läuft in der Regel ohne Inhalts-Änderungen, weil die t3://record-Syntax im Content stabil bleibt. Für die Analyse nutzen wir einen Scan über tt_content-Felder, der alle Links-Typen aufschlüsselt und eine Empfehlung pro Installation generiert.