Galeria para TYPO3

Por que sf_filecollection_gallery resolve galerias de imagens no TYPO3 corretamente

Galerias de imagens estão entre as demandas mais frequentes em sites corporativos - fotos de produtos, imagens da equipe, documentação de eventos, projetos de referência. O TYPO3 por si só não traz um elemento nativo de galeria. O elemento de conteúdo padrão “Imagens” exibe imagens empilhadas ou em colunas, mas sem lightbox, sem filtragem e sem opções flexíveis de layout. sf_filecollection_gallery fecha essa lacuna utilizando TYPO3 File Collections como fonte de dados para galerias e fornecendo integração lightbox, diversos layouts e lazy loading.

A vantagem decisiva sobre outras extensões de galeria: editores trabalham com o sistema FAL que já conhecem. Imagens são organizadas em File Collections, e a galeria exibe automaticamente todas as imagens da Collection atribuída. Adicionar novas imagens significa: arrastar imagem para a Collection, pronto.

Cenários típicos de uso

Projetos de referência e portfólios. Uma agência de arquitetura exibe em cada página de projeto 15 a 40 imagens em uma galeria. O editor mantém uma File Collection por projeto. sf_filecollection_gallery renderiza a galeria como grid com lightbox. Ao clicar em uma imagem, abre-se a visualização completa com navegação para a próxima e anterior. Descrições de imagem dos metadados FAL são exibidas automaticamente como legendas.

Documentação de eventos e fotografia de imprensa. Um organizador de feiras documenta cada evento com 50 a 200 fotos. As imagens são carregadas em lote em uma File Collection. sf_filecollection_gallery gera automaticamente miniaturas, otimiza o tempo de carregamento via lazy loading e exibe a galeria em layout masonry.

Catálogos de produtos com apresentação visual. Um fabricante de móveis exibe por categoria de produto uma galeria com fotos de ambiente. Através de múltiplas File Collections e um plugin frontend com filtro de categoria, visitantes podem alternar entre galerias sem recarregar a página.

Arquitetura técnica

sf_filecollection_gallery é uma extensão Extbase incorporada como plugin TYPO3 em elementos de conteúdo. A fonte de dados são TYPO3 File Collections do File Abstraction Layer (FAL).

A arquitetura se divide em três camadas: fonte de dados (a extensão lê File Collections via TYPO3 FAL API), motor de renderização (templates Fluid controlam a saída com layouts para grid, masonry e listas simples) e integração lightbox (suporta Fancybox, PhotoSwipe e Lightcase). A Gosign recomenda PhotoSwipe pelo melhor suporte touch e ausência de dependência jQuery.

Lazy loading é integrado nativamente: imagens abaixo da área visível são carregadas apenas quando o usuário rola. Uma vantagem da arquitetura File Collection: imagens podem aparecer em múltiplas galerias simultaneamente sem serem duplicadas.

Problemas frequentes e soluções

Galeria não mostra imagens, embora a File Collection esteja preenchida. Causa frequente é configuração errada de storage. A File Collection referencia um storage ao qual o frontend não tem acesso. Solução: verificar no backend TYPO3 se as imagens estão no storage correto e se o storage está configurado como “public”.

Lightbox não funciona, imagens abrem como nova página. A biblioteca JavaScript do lightbox não está sendo carregada. Frequentemente um include TypoScript está faltando ou há conflito com outra biblioteca JavaScript na página. Solução: verificar no dev-tool do navegador se o arquivo JS do lightbox está sendo carregado.

Tempo de carregamento muito alto em galerias grandes. Uma galeria com mais de 100 imagens em alta resolução pode carregar lentamente apesar do lazy loading, porque as miniaturas não estão suficientemente comprimidas. Solução: configurar TYPO3 Image Processing para gerar miniaturas em tamanho fixo e qualidade otimizada. Adicionalmente, ativar formato WebP.

Migração e compatibilidade de versões

sf_filecollection_gallery é mantida ativamente e está disponível para TYPO3 v11 e v12 LTS. A extensão tem API estável e praticamente nenhuma breaking change entre versões.

Na atualização de TYPO3 v10 para v12, a configuração do lightbox deve ser verificada. Fancybox 2 não é mais compatível com versões atuais do jQuery. A Gosign recomenda a troca para PhotoSwipe, que funciona sem jQuery e oferece melhor performance em dispositivos móveis. PhotoSwipe suporta gestos touch (pinch-to-zoom, swipe) que atendem à expectativa do usuário em telas de smartphone. A migração de Fancybox para PhotoSwipe requer tipicamente 4 a 8 horas.