linkhandler para TYPO3

linkhandler evita los enlaces rotos cuando cambian las URLs

En TYPO3 una indicación Typolink se refiere directamente a una página, un archivo o una URL, no a un registro. En cuanto una redacción quiere enlazar desde el texto corrido a eventos, artículos de noticias, productos o direcciones, debe o bien meter la URL de forma hardcoded o bien intercalar una extensión que genere una URL estable a partir de un ID de registro. Esa es exactamente la tarea de linkhandler. La extensión de Cobwebsters registra nuevos tipos de enlace en el RTE de TYPO3 y en el Link Browser y los conecta con cualquier tabla de base de datos. En un proyecto de redacción con más de cien referencias cruzadas internas, esa es la diferencia entre una arquitectura de contenido que funciona y una página cementerio llena de enlaces 404.

Escenarios típicos: cualquier redacción con más de un dominio de contenido

En cuanto coexisten en el mismo proyecto noticias, eventos y productos, los redactores necesitan un sistema de enlaces limpio. Una universidad enlaza desde un artículo de revista al evento en sf_event_mgt, desde el texto del evento al autor participante de md_news_author y, desde el perfil del autor, de vuelta a todas sus contribuciones en GeorgRinger/news. Tres extensiones, tres tipos de registro, y sin linkhandler cada una de esas referencias cruzadas sería una URL hardcoded que se rompe en el siguiente refactoring de slugs. En el día a día, eso significa que un único refactoring de URLs puede generar decenas o cientos de broken links que solo aparecen semanas después en el informe de Google Search Console.

Un segundo escenario son los textos de comercio electrónico: descripciones de producto que remiten a accesorios o artículos de blog que enlazan a productos de aimeos. linkhandler genera las URLs automáticamente a partir de la configuración de routing del producto, y en un refactoring de categorías todos los enlaces viajan con él.

En tercer lugar la necesidad aparece en los listados de ubicaciones. Quien mantiene una estructura de sucursales o un directorio de contactos con tt_address o un modelo propio quiere enlazar desde los artículos a la página de detalle correspondiente. El enlace linkhandler permanece estable incluso si la ubicación se renombra.

Arquitectura técnica: registro de tipos de enlace con YAML y clase handler

linkhandler utiliza el mecanismo LinkHandler del núcleo de TYPO3 disponible desde v8. Cada tipo de enlace se registra mediante un archivo YAML en el directorio Config. El YAML define el identificador del handler, la tabla, el modelo Extbase y la configuración de routing. En el RTE y en el Link Browser el tipo de enlace aparece como nueva pestaña: “Noticia”, “Evento”, “Producto”, “Dirección”. Cada pestaña muestra una lista de los registros disponibles con función de búsqueda y filtro, de modo que los redactores encuentran la entrada deseada incluso con miles de entradas de noticias.

El resolver propiamente dicho es una clase PHP que hereda de AbstractLinkHandler e implementa los métodos modifyLinkField y generateRelativeUrl. Los métodos generan a partir del ID de registro una URL semántica a través de la Site Config y del router de la extensión correspondiente. En el frontend el Typolink se llama con el parámetro t3://record y el Page Rendering lo resuelve a la URL final. Eso significa: aunque diez mil artículos enlacen al mismo registro de noticia, ante un cambio de slug solo hay que actualizar el propio registro del artículo; todos los enlaces se resuelven automáticamente a la nueva URL.

La configuración toca en profundidad el sistema de enlaces de TYPO3, pero se mantiene declarativa: tras el registro YAML y el clear de caché, el nuevo tipo de enlace queda disponible en todo el proyecto, incluidas plantillas Fluid y componentes de menú. Quien no usa linkhandler explícitamente obtiene el mecanismo también a través del LinkHandler del núcleo, pero sin la capa de abstracción YAML ni la cómoda UI de picker backend de la extensión.

Problemas frecuentes: caché, variantes de idioma y file handler

El tema de soporte más habitual son las inconsistencias de caché tras actualizar un registro. Cuando se adapta el slug de un artículo de noticia, el caché de página del artículo fuente en el que está el enlace linkhandler también debe vaciarse; si no, la URL antigua se mantiene en la salida. La solución es una cache tag que se establece con el renderizado del Typolink. Muchas instalaciones no la activan y luchan después con enlaces supuestamente rotos.

El segundo problema son las variantes de idioma. Un artículo de noticia en ES remite mediante linkhandler a un evento. La traducción al inglés del artículo debe remitir al mismo ID de evento, pero generar la URL en el idioma inglés. linkhandler ofrece esa resolución mediante el Language Aspect, pero la configuración YAML debe apuntar explícitamente a las variantes de routing de las páginas de destino. Quien usa idiomas fallback debe comprobar adicionalmente cómo se comporta el handler con traducciones ausentes: debería resolver en el idioma fallback, no retroceder al idioma principal.

En tercer lugar, el file handler es un caso especial. Quien junto a enlaces a registros quiere enlazar también a archivos FAL de TYPO3 debe configurar por separado el file handler de linkhandler o recurrir al file linker nativo de TYPO3. La combinación es posible, pero el orden de los handlers en el YAML decide qué pestaña aparece primero.

TYPO3 v12 y v13 utilizan el LinkHandler del núcleo, la migración merece la pena

A partir de TYPO3 v11 el LinkHandler del núcleo es apto para producción y puede asumir por sí mismo muchas de las tareas de linkhandler. Aun así la extensión de Cobwebsters se sigue manteniendo porque aporta funciones de comodidad adicionales como el editor YAML, el picker de registro mejorado y la salida compatible con Schema. Para TYPO3 v12 y v13 existe una versión actual en TER y en Packagist.

En la revisión de migración Gosign comprueba cuántas llamadas a linkhandler hay en los contenidos RTE. Con menos de 50 ocurrencias a menudo merece la pena pasarse al LinkHandler del núcleo; con más de 100 ocurrencias o handlers muy personalizados, linkhandler sigue siendo la opción más pragmática. La migración a una nueva versión mayor suele transcurrir sin cambios de contenido, porque la sintaxis t3://record en el contenido se mantiene estable. Para el análisis usamos un escaneo sobre los campos tt_content que desglosa todos los tipos de enlace y genera una recomendación por instalación.