tt_address para TYPO3

Diretórios de colaboradores, localizadores de filiais e listas de contatos rodam no TYPO3 há 20 anos via tt_address

Toda empresa com múltiplas localidades, departamentos ou pessoas de contato precisa de uma apresentação estruturada no site. Quem é responsável por qual região? Onde fica a filial mais próxima? Quais são os dados de contato do departamento de RH? Manter essas informações manualmente como blocos de texto no CMS leva a inconsistências: formatos diferentes, atualizações esquecidas, sem possibilidade de filtragem.

tt_address é a extensão de gerenciamento de endereços mais antiga e difundida para TYPO3. Em uso desde TYPO3 v4 (2006), mais de 50.000 instalações ativas (TER, 2026), mantida ativamente pela comunidade TYPO3. A extensão armazena contatos, pessoas e localidades como registros estruturados e os exibe via templates Fluid como listas, mapas ou páginas de detalhe.

Cenários típicos de uso

Diretórios de colaboradores para sites corporativos. Uma empresa com 50 a 500 colaboradores quer mostrar no site quem é responsável por cada tema. tt_address armazena por pessoa: nome, título, departamento, foto, e-mail, telefone, localidade. A saída ocorre como lista filtrável (por departamento, localidade) ou como página de detalhe com download de vCard.

Localizadores de filiais e visões gerais de localidades. Empresas com 10 a 500 localidades usam tt_address como base de dados para um localizador. Cada localidade tem endereço, geocoordenadas, horários de funcionamento e dados de contato. A integração de mapa ocorre via extensão separada (maps2 ou Leaflet), que lê as geocoordenadas do tt_address. Usuários buscam por CEP ou cidade e recebem as localidades mais próximas.

Listas de contatos para órgãos públicos e associações. Municipalidades, câmaras e associações listam responsáveis por competência. tt_address modela a estrutura organizacional via categorias ou SysFolder. A saída pode ser filtrada por categoria e ordenada alfabeticamente ou por cargo.

Arquitetura técnica

tt_address armazena registros na tabela tt_address. Os campos incluem: tratamento, título, nome, sobrenome, empresa, departamento, endereço, CEP, cidade, país, telefone, fax, celular, e-mail, site, geocoordenadas (latitude, longitude), imagem (referência FAL), categorias e campo de descrição (RichText).

A saída ocorre via plugin Extbase com ações de lista e detalhe. Templates Fluid são completamente personalizáveis. tt_address se integra com outras extensões: maps2 e ext:leaflet para integração de mapa, direct_mail e mail para envio de newsletter (tt_address como lista de destinatários), ke_search e indexed_search para busca de texto completo sobre dados de endereço.

Categorias (sys_category) são o mecanismo primário de estruturação. Uma pessoa pode ser atribuída a múltiplas categorias (ex: “Vendas” e “Localidade SP”). A saída no frontend filtra por categoria, permitindo a exibição de listas por departamento, equipes por localidade ou grupos de contato temáticos.

Problemas frequentes e soluções

Imagens não são exibidas. Desde TYPO3 v10, tt_address usa FAL para imagens. Instalações antigas armazenavam imagens como nomes de arquivo em um campo (não como referência FAL). Solução: executar o script de upgrade do tt_address, que converte referências de imagem antigas em referências FAL.

Geocoordenadas faltam para o localizador. Endereços sem latitude/longitude não aparecem no mapa. Inserir manualmente para 200 localidades não é prático. Solução: automatizar geocoding via tarefa scheduler. A Gosign utiliza um cronjob que, via API Nominatim (OpenStreetMap, gratuito, em conformidade com a LGPD), completa coordenadas ausentes.

Importação de dados de sistemas externos. Departamentos de RH mantêm dados de colaboradores em sistemas de RH. Os dados devem aparecer automaticamente no site. Solução: construir um mecanismo de sincronização que importa CSV ou JSON do sistema de RH e cria ou atualiza registros tt_address.

Migração e compatibilidade de versões

tt_address suporta ativamente TYPO3 v11, v12 e v13. A extensão é co-mantida por Georg Ringer (o desenvolvedor da extensão News) e segue um ciclo de release claro. Atualizações para novas versões TYPO3 major aparecem geralmente dentro de poucas semanas após o release LTS.

A Gosign recomenda tt_address como ponto de partida para todos os cenários com menos de 5.000 registros. A extensão é estável, bem documentada, tem uma grande comunidade e se integra perfeitamente com outras extensões TYPO3. Para volumes maiores de dados ou requisitos de sincronização complexos, a Gosign constrói uma camada de sincronização personalizada que usa tt_address como saída frontend, mas mantém a autoridade dos dados no sistema fonte.

A configuração inicial de um projeto tt_address (instalação, adaptação de template, estrutura de categorias, configuração de geocoding) fica entre 2 e 4 dias de desenvolvimento. Um localizador de filiais com integração de mapa e busca por CEP chega a 5 a 8 dias, incluindo a integração Leaflet ou maps2.