linkhandler para TYPO3

linkhandler evita links quebrados quando URLs mudam

No TYPO3, uma indicação Typolink se refere diretamente a uma página, um arquivo ou uma URL, não a um registro. Assim que uma redação quer linkar no texto corrido para eventos, artigos de news, produtos ou endereços, ou precisa inserir a URL fixa, ou configurar um record link handler que gera uma URL estável a partir de um ID de registro. Essa é exatamente a tarefa do linkhandler, e desde o TYPO3 8.6 o core também consegue fazê-lo. A extensão, criada pela AOE e mantida por último pela Cobweb, registra novos tipos de link no RTE do TYPO3 e no Link Browser e os conecta a quaisquer tabelas de banco. Em um projeto editorial com mais de cem referências internas, essa é a diferença entre uma arquitetura de conteúdo funcional e uma página cemitério cheia de links 404.

Cenários típicos ocorrem em toda redação com mais de um domínio de conteúdo

Assim que news, eventos e produtos coexistem em um mesmo projeto, os redatores precisam de um sistema de linking limpo. Uma universidade brasileira linka no artigo da revista para o evento em sf_event_mgt, no texto do evento para o autor envolvido de md_news_author e, no perfil do autor, de volta para todos os seus artigos em GeorgRinger/news. Três extensões, três tipos de registro, e sem linkhandler cada uma dessas referências seria uma URL fixa que quebraria no próximo refactoring de slug. No cotidiano, isso significa: um único refactoring de URL pode gerar dezenas ou centenas de broken links, que só aparecem semanas depois no relatório do Google Search Console.

Um segundo cenário são textos de e-commerce: descrições de produto que apontam para acessórios, ou artigos de blog que linkam para produtos do aimeos. O linkhandler gera os URLs automaticamente a partir da configuração de routing do produto, e em um refactoring de categoria todos os links migram junto.

Em terceiro, a necessidade aparece em listagens de localizações. Quem mantém uma estrutura de filiais ou diretórios de contatos com tt_address ou um model próprio quer, a partir de artigos, linkar para a página de detalhe correspondente. O link linkhandler permanece estável mesmo quando a localização é renomeada.

Arquitetura técnica registra link types via TSconfig e classe handler

O linkhandler usa a LinkBrowser API do core, disponível desde o TYPO3 7.6; desde a 8.6, o core traz também o próprio record link handler. Cada link type é registrado no Page TSconfig em TCEMAIN.linkHandler, com classe handler, tabela e rótulo da aba; como o link é gerado no frontend é definido pelo TypoScript. No RTE e no Link Browser, o link type aparece como nova aba: “News”, “Evento”, “Produto”, “Endereço”. Cada aba mostra uma lista dos registros disponíveis com função de busca e filtro, para que redatores, mesmo com milhares de entradas de news, encontrem o registro desejado de forma direcionada.

A aba no Link Browser vem de uma classe PHP que herda de AbstractLinkHandler; no frontend, um handler de Typolink monta o link. Ele gera a partir do ID do registro o link para a página de detalhe via configuração typolink no TypoScript, e o routing fornece a URL amigável. No frontend, o Typolink é chamado com o parâmetro t3://record e resolvido pelo page rendering para a URL final. Isso significa: mesmo que dezenas de milhares de artigos linkem para o mesmo registro de news, em uma mudança de slug basta atualizar o próprio registro do artigo, todos os links se resolvem automaticamente para a nova URL.

A configuração penetra fundo no sistema de linking do TYPO3, mas permanece declarativa: após o registro em TSconfig e TypoScript e o clear cache, o novo link type fica disponível no projeto inteiro, inclusive templates Fluid e componentes de menu. Quem não usa o linkhandler explicitamente também obtém o mecanismo via core linking do TYPO3 desde a 8.6, inclusive com aba própria no Link Browser.

Problemas frequentes envolvem cache, variantes de idioma e file handlers

O tema de suporte mais frequente são inconsistências de cache após o update de um registro. Quando o slug de um artigo news é ajustado, o page cache do artigo de origem, no qual está o link linkhandler, também precisa ser limpo, caso contrário a URL antiga permanece na saída. A solução é limpar também o cache das páginas que linkam ao salvar o registro, por exemplo via TCEMAIN.clearCacheCmd no Page TSconfig. Muitas instalações não configuram isso e depois lutam contra links supostamente quebrados.

O segundo problema são variantes de idioma. Um artigo news em BR aponta via linkhandler para um evento. A tradução em inglês do artigo precisa apontar para o mesmo ID de evento, mas gerar a URL no idioma inglês. Essa resolução fica a cargo do rendering do Typolink, mas a configuração TypoScript precisa apontar explicitamente para as variantes de routing das páginas-alvo. Quem usa fallback de idioma precisa verificar adicionalmente como o handler se comporta em traduções ausentes, ele deve resolver no idioma de fallback, não cair de volta no idioma principal.

Em terceiro, o file handler é um caso especial. Quem, além de links de registro, também quer linkar para arquivos FAL do TYPO3, usa para isso o file handler do core; o linkhandler não traz um próprio. A combinação é possível; displayBefore e displayAfter no Page TSconfig decidem qual aba aparece primeiro.

TYPO3 v12 e v13 usam o LinkHandler do core, migração vale a pena

Desde o TYPO3 8.6, a funcionalidade do linkhandler faz parte do LinkHandler do core. A extensão em si não é mais mantida: a última versão da Cobweb, a 3.1.3 de 2016, só roda no TYPO3 7.6. Para TYPO3 v12 e v13 não há versão; no TER consta apenas a versão desatualizada 0.3.1 da AOE.

Na revisão de migração, a Gosign verifica quantas chamadas linkhandler estão nos conteúdos do RTE. Com menos de 50 ocorrências, frequentemente vale a pena migrar para o LinkHandler do core; com mais de 100 ocorrências ou handlers muito customizados, ajuda um script que reescreve os links no formato do core t3://record. A migração para uma nova major version costuma rodar sem alterações de conteúdo, porque a sintaxe t3://record no conteúdo permanece estável. Para a análise, usamos um scan sobre os campos tt_content que discrimina todos os tipos de link e gera uma recomendação por instalação.