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 włączyć między siebie rozszerzenie, które z ID rekordu generuje stabilny URL. Dokładnie to jest zadaniem linkhandler. Rozszerzenie od Cobwebsters 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 YAML i klasę handlera

linkhandler wykorzystuje mechanizm TYPO3-LinkHandler z core, który jest dostępny od v8. Każdy typ linku jest rejestrowany przez plik YAML w katalogu Config. YAML definiuje identyfikator handlera, tabelę, model Extbase i konfigurację routingu. 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.

Właściwy resolver to klasa PHP, która dziedziczy po AbstractLinkHandler i implementuje metody modifyLinkField i generateRelativeUrl. Metody tworzą z ID rekordu znaczący URL przez Site-Config i router danego rozszerzenia. 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 YAML i 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 również przez TYPO3-Core-Linking, ale bez warstwy abstrakcji YAML i komfortowego backendowego UI pickera z rozszerzenia.

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 cache-tag, który jest ustawiany przy renderowaniu typolinku. Wiele instalacji tego nie aktywuje 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. linkhandler oferuje to rozwiązywanie przez Language-Aspect, ale konfiguracja YAML 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, musi oddzielnie skonfigurować handler plików linkhandler lub sięgnąć do natywnego TYPO3-File-Linkera. Kombinacja jest możliwa, ale kolejność handlerów w YAML decyduje, która zakładka pojawi się jako pierwsza.

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

Od TYPO3 v11 core LinkHandler jest gotowy do produkcji i może przejmować wiele zadań linkhandler sam. Mimo to rozszerzenie Cobwebsters jest nadal utrzymywane, bo przynosi dodatkowe funkcje komfortu jak edytor YAML, ulepszony record-picker i przyjazne schema wyjście. Dla TYPO3 v12 i v13 istnieje aktualna wersja w TER i na Packagist.

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 linkhandler pozostaje bardziej pragmatycznym wyborem. 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ę.