maps2 para TYPO3

Por que maps2 se tornou a solução padrão para mapas no TYPO3

Todo segundo site corporativo precisa de uma exibição de mapa - para localidades, filiais, locais de eventos ou áreas de entrega. No TYPO3, maps2 se estabeleceu como a extensão de mapas mais difundida por suportar três provedores de mapa simultaneamente: Google Maps, OpenStreetMap e Mapbox. Isso significa liberdade de escolha real para empresas. Quem quer evitar Google Maps por motivos de proteção de dados muda para OpenStreetMap sem precisar trocar a extensão.

maps2 vai muito além de uma simples incorporação de mapa. A extensão gera marcadores diretamente a partir de registros TYPO3, suporta clustering para grandes quantidades de marcadores e oferece funções de roteamento. Para editores, criar novas localidades é tão simples quanto criar um elemento de conteúdo TYPO3 normal.

Cenários típicos de uso

Localizador de filiais para empresas com 10 a 500 localidades. Uma empresa de varejo quer oferecer um localizador interativo de filiais. Cada filial é armazenada como registro tt_address ou registro próprio no TYPO3. maps2 lê os endereços, os geocodifica (em combinação com a extensão geocoordinates) e os exibe como marcadores no mapa. Ao clicar no marcador, um popup se abre com endereço, horário de funcionamento e dados de contato. Com mais de 50 marcadores, maps2 ativa clustering automático.

Sites imobiliários com mapas de objetos. Sites de corretores em TYPO3 usam maps2 junto com a extensão OpenImmo. Cada objeto imobiliário importado é exibido automaticamente no mapa.

Páginas de eventos e locais. Instituições culturais, feiras ou municipalidades mostram locais de eventos em um mapa. maps2 pode ser vinculado a qualquer extensão Extbase que contenha dados de endereço.

Arquitetura técnica

maps2 é construído como extensão Extbase e usa o sistema de plugin TYPO3 para a saída no frontend. A decisão arquitetural central é a abstração de provedor: a extensão define uma interface unificada para renderização de mapa, implementada por três provedores.

• Google Maps Provider: Usa a Google Maps JavaScript API v3. Requer API Key. Custos: aprox. 7 USD por 1.000 carregamentos de mapa após a cota gratuita (28.000/mês).
• OpenStreetMap Provider: Usa Leaflet.js como biblioteca de renderização com tiles OSM. Sem custos de API, sem registro necessário. Em conformidade com LGPD (PT: RGPD), pois dados permanecem na Europa.
• Mapbox Provider: Opção premium com estilos de mapa próprios. 50.000 carregamentos gratuitos por mês.

A extensão armazena configurações de mapa em tabelas de banco de dados próprias. Marcadores são criados via relação com registros TYPO3 arbitrários - maps2 não é restrito a um tipo de registro específico.

Problemas frequentes e soluções

Mapa não é exibido, apenas área cinza. Com Google Maps, em 90% dos casos o problema é a API Key. Ou está faltando, a cobrança não está ativada, ou os domínios permitidos na API Key não correspondem ao site. Solução: verificar no Google Cloud Console se Maps JavaScript API está ativada e a chave está liberada para o domínio correto.

Marcadores aparecem na posição errada. Causa frequente é geocoding incorreto ou ausente. Se endereços não têm coordenadas, maps2 tenta resolvê-los via serviço de geocoding configurado. Com endereços imprecisos, marcadores acabam no centro da cidade. Solução: corrigir coordenadas via lote de geocoding único e armazená-las como valores fixos.

Problemas de performance com mais de 200 marcadores. A biblioteca JavaScript renderiza cada marcador individualmente no DOM. A partir de 200 marcadores, fica perceptivelmente lento em dispositivos móveis. Solução: ativar clustering de marcadores e implementar filtragem server-side.

Migração e compatibilidade de versões

maps2 é ativamente mantido por Stefan Froemken e está disponível para TYPO3 v11 e v12 LTS. A extensão tem uma API estável e praticamente nenhuma breaking change entre versões major.

Na troca de Google Maps para OpenStreetMap (frequentemente por motivos de LGPD), apenas a configuração de provedor no maps2 precisa ser alterada. Templates e dados de marcadores permanecem idênticos. A Gosign realizou essa troca em vários clientes em menos de um dia. A motivação de proteção de dados: Google Maps transfere dados pessoais (endereço IP, browser fingerprint) para servidores Google nos EUA. Com OpenStreetMap, os dados permanecem na Europa, e um banner de consentimento para serviços de mapa se torna desnecessário.