linkhandler dla TYPO3

linkhandler zapobiega martwym linkom, gdy URL-e się zmieniają

W TYPO3 typolink odnosi się bezpośrednio do strony, pliku lub URL, a nie do rekordu. Gdy redakcja chce w tekście głównym linkować do wydarzeń, artykułów news, produktów lub adresów, musi albo wpisać URL na sztywno, albo skonfigurować record link handler, który z ID rekordu generuje stabilny URL. Dokładnie to jest zadaniem linkhandler, a od TYPO3 8.6 potrafi to również core. Rozszerzenie, pierwotnie od AOE, a ostatnio utrzymywane przez Cobweb, rejestruje nowe typy linków w TYPO3-RTE i w Link-Browser i łączy je z dowolnymi tabelami bazy danych. Przy projekcie redakcyjnym z ponad setką wewnętrznych odsyłaczy to różnica między działającą architekturą contentu a cmentarzem pełnym linków 404.

Typowe scenariusze zastosowania występują w każdej redakcji z więcej niż jedną domeną treści

Gdy news, wydarzenia i produkty istnieją w tym samym projekcie, redaktorzy potrzebują porządnego systemu linkowania. Uczelnia w artykule magazynowym linkuje do wydarzenia w sf_event_mgt, w tekście wydarzenia do zaangażowanego autora z md_news_author, a w profilu autora z powrotem do wszystkich jego wpisów w GeorgRinger/news. Trzy rozszerzenia, trzy typy rekordów, i bez linkhandler każdy z tych odsyłaczy byłby twardym URL-em, który łamie się przy następnym refactoringu slugów. W codzienności oznacza to: jedno refactoring URL może wtedy wygenerować dziesiątki lub setki zepsutych linków, które dopiero kilka tygodni później pojawiają się w raporcie Google Search Console.

Drugim scenariuszem są teksty e-commerce: opisy produktów, które odnoszą się do akcesoriów, lub artykuły bloga, które linkują do produktów z aimeos. linkhandler automatycznie generuje URL-e z konfiguracji routingu produktów, a przy refactoringu kategorii wszystkie linki wędrują razem.

Po trzecie, potrzeba pojawia się przy listach lokalizacji. Kto pielęgnuje strukturę oddziałów lub katalogi osób kontaktowych z tt_address lub własnym modelem, chce z artykułów linkować do danej strony detalu. Link linkhandler pozostaje stabilny, nawet gdy lokalizacja zostanie przemianowana.

Architektura techniczna rejestruje typy linków przez TSconfig i klasę handlera

linkhandler wykorzystuje LinkBrowser-API z core, dostępne od TYPO3 7.6; od 8.6 core zawiera także sam record link handler. Każdy typ linku jest rejestrowany w Page TSconfig pod TCEMAIN.linkHandler, z klasą handlera, tabelą i etykietą zakładki; sposób budowania linku we frontendzie określa TypoScript. W RTE i w Link-Browser typ linku pojawia się jako nowa zakładka: “News”, “Event”, “Produkt”, “Adres”. Każda zakładka pokazuje listę dostępnych rekordów z funkcją wyszukiwania i filtrowania, dzięki czemu redaktorzy nawet przy tysiącach wpisów news mogą celowo znaleźć pożądany wpis.

Zakładkę w Link-Browser dostarcza klasa PHP dziedzicząca po AbstractLinkHandler; we frontendzie link buduje handler typolinku. Tworzy on z ID rekordu link do strony detalu przez konfigurację typolink w TypoScript, a znaczący URL zapewnia routing. We frontend typolink jest wywoływany z parametrem t3://record i rozwiązywany przez renderowanie strony do finalnego URL. Oznacza to: nawet jeśli dziesiątki tysięcy artykułów linkują do tego samego rekordu news, przy zmianie slugu musi być zaktualizowany tylko sam rekord artykułu, a wszystkie linki automatycznie rozwiążą się na nowy URL.

Konfiguracja sięga głęboko w system linkowania TYPO3, ale pozostaje deklaratywna: po rejestracji w TSconfig i TypoScript oraz wyczyszczeniu cache nowy typ linku jest dostępny w całym projekcie, włącznie z szablonami Fluid i komponentami menu. Kto nie używa linkhandler wyraźnie, otrzymuje mechanizm od TYPO3 8.6 również przez Core-Linking, razem z własną zakładką w Link-Browser.

Częste problemy dotyczą cache, wariantów językowych i handlera plików

Najczęstszym tematem wsparcia są niespójności cache po aktualizacji rekordu. Gdy slug artykułu news zostaje dostosowany, musi zostać wyczyszczony również page-cache artykułu źródłowego, w którym znajduje się link linkhandler, inaczej stary URL pozostaje w wyjściu. Rozwiązaniem jest czyszczenie przy zapisie rekordu także cache stron linkujących, np. przez TCEMAIN.clearCacheCmd w Page TSconfig. Wiele instalacji tego nie konfiguruje i walczy potem z pozornie uszkodzonymi linkami.

Drugim problemem są warianty językowe. Artykuł news w PL odwołuje się przez linkhandler do wydarzenia. Angielskie tłumaczenie artykułu ma odwoływać się do tego samego ID wydarzenia, ale generować URL w języku angielskim. To rozwiązywanie przejmuje renderowanie typolinku, ale konfiguracja TypoScript musi wyraźnie wskazywać na warianty routingu stron docelowych. Kto używa języków zapasowych, musi dodatkowo sprawdzić, jak handler zachowuje się przy brakujących tłumaczeniach, powinien rozwiązywać w języku zapasowym, nie wracać do języka głównego.

Po trzecie, handler plików jest przypadkiem szczególnym. Kto obok linków rekordów chce również linkować do plików TYPO3-FAL, korzysta z handlera plików z core, linkhandler nie ma własnego. Kombinacja jest możliwa; o tym, która zakładka pojawi się jako pierwsza, decydują displayBefore i displayAfter w Page TSconfig.

TYPO3 v12 i v13 używają core LinkHandler, migracja się opłaca

Od TYPO3 8.6 funkcja linkhandler jest częścią core LinkHandler. Samo rozszerzenie nie jest już utrzymywane: ostatnia wersja od Cobweb, 3.1.3 z 2016 roku, działa tylko pod TYPO3 7.6. Dla TYPO3 v12 i v13 nie ma żadnej wersji; w TER widnieje tylko przestarzała wersja 0.3.1 od AOE.

Przy przeglądzie migracji Gosign sprawdza, ile wywołań linkhandler znajduje się w treściach RTE. Przy mniej niż 50 wystąpieniach opłaca się często przejście na core-LinkHandler, przy więcej niż 100 wystąpieniach lub silnie zindywidualizowanych handlerach pomaga skrypt, który przepisuje linki na format core t3://record. Migracja na nową wersję major przebiega z reguły bez zmian treści, bo składnia t3://record w contencie pozostaje stabilna. Do analizy używamy skanu przez pola tt_content, który rozkłada wszystkie typy linków i generuje rekomendację per instalację.