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 configurar un record link handler que genere una URL estable a partir de un ID de registro. Esa es exactamente la tarea de linkhandler, y desde TYPO3 8.6 también la puede hacer el núcleo. La extensión, creada por AOE y mantenida por último por Cobweb, 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 TSconfig y clase handler

linkhandler utiliza la API LinkBrowser del núcleo, que existe desde TYPO3 7.6; desde 8.6 el núcleo trae también el propio record link handler. Cada tipo de enlace se registra en el Page TSconfig bajo TCEMAIN.linkHandler, con clase handler, tabla y etiqueta de la pestaña; cómo se genera el enlace en el frontend lo define TypoScript. 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.

La pestaña del Link Browser la aporta una clase PHP que hereda de AbstractLinkHandler; en el frontend, un handler de Typolink construye el enlace. Este genera a partir del ID de registro el enlace a la página de detalle mediante la configuración typolink en TypoScript, y el routing aporta la URL semántica. 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 en TSconfig y TypoScript 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 desde TYPO3 8.6, con su propia pestaña en el Link Browser.

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 vaciar también la caché de las páginas que enlazan al guardar el registro, por ejemplo con TCEMAIN.clearCacheCmd en el Page TSconfig. Muchas instalaciones no lo configuran 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. Esa resolución la asume el renderizado del Typolink, pero la configuración TypoScript 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 usa para ello el file handler del núcleo; linkhandler no trae uno propio. La combinación es posible; qué pestaña aparece primero lo deciden displayBefore y displayAfter en el Page TSconfig.

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

Desde TYPO3 8.6, la funcionalidad de linkhandler forma parte del LinkHandler del núcleo. La extensión en sí ya no se mantiene: la última versión de Cobweb, la 3.1.3 de 2016, solo funciona con TYPO3 7.6. Para TYPO3 v12 y v13 no hay ninguna versión; en el TER solo figura la versión obsoleta 0.3.1 de AOE.

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, ayuda un script que reescriba los enlaces al formato del núcleo t3://record. 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.