in2template para TYPO3

Um esqueleto uniforme traz estrutura a site packages antes que eles virem inferno de manutenção

Quem monta em TYPO3 um site package para um site grande enfrenta sempre a mesma pergunta: como organizo templates, partials, layouts e content elements para que ainda sejam manuteníveis em dois anos? O in2template aparece em exemplos de código da in2code como nome de uma extensão própria do projeto; não foi publicado nem no TER nem no Packagist. Uma resposta estruturada é uma estrutura básica para site packages modernos: estrutura de diretórios clara, content elements predefinidos, configuração preparada para TypoScript, Fluid Styled Content e backend layouts. Para times TYPO3 que iniciam novos projetos com regularidade, um esqueleto assim substitui a prática antiga de copiar e colar do último projeto de cliente por um padrão documentado.

O público-alvo são agências com vários projetos TYPO3 paralelos e times internos que mantêm templates corporativos para sites de grupos empresariais ou universidades. Especialmente onde desenvolvedoras e redatoras compartilham o site package, uma convenção consistente de pasta e nomenclatura é de sobrevivência. Um esqueleto uniforme atende exatamente essa lacuna.

Cenários típicos de uso

Um primeiro cenário é o início limpo de projeto. Uma agência com oito desenvolvedoras e três projetos TYPO3 em curso adota um esqueleto próprio como padrão interno para site packages. Cada novo projeto começa com o mesmo esqueleto: estrutura de diretório idêntica, convenções de nome idênticas, base TypoScript idêntica. O resultado: um desenvolvedor pode trocar de projeto sem precisar se reorientar a cada vez.

Um segundo cenário é a modernização de um site package antigo. Um portal universitário com 800 páginas e uma pasta de templates que cresceu desde o TYPO3 v7 é reestruturado no âmbito de um upgrade de v11 para v12. Em vez de arrastar o mato antigo, o time reconstrói o site package baseado em um esqueleto assim e migra os conteúdos passo a passo.

Um terceiro cenário é o onboarding de novos redatores. Uma editora brasileira com 30 redatores explica, com base no esqueleto, para que serve cada content element. A consistência em nomenclatura e estrutura encurta o treinamento, a taxa de erros no backend cai.

Um quarto cenário é o template interno de refactoring. Uma empresa com cinco instalações TYPO3 de safras diferentes quer levar, a longo prazo, os site packages a uma estrutura uniforme. Um padrão uniforme serve como esqueleto de referência contra o qual cada projeto antigo é reconstruído gradualmente, sem que o time precise discutir uma nova estrutura-alvo a cada vez.

Arquitetura técnica

Um esqueleto assim não é um add-on clássico, mas um template para um site package próprio. Ele traz uma estrutura de diretórios: Resources/Private/Templates, Resources/Private/Partials, Resources/Private/Layouts, Configuration/TypoScript, Configuration/TsConfig, Configuration/TCA/Overrides. O esqueleto é complementado por content elements preparados (texto, texto com imagem, accordion, teaser grid) e uma configuração para backend layouts.

Não existe pacote Composer; um esqueleto assim é copiado para o repositório do próprio site package e renomeado. Na prática, times raramente usam um esqueleto assim como dependência direta, o comum é um clone inicial que depois cresce por projeto. Isso transforma o esqueleto em starter kit, não em framework que precise ser atualizado entre versões.

Para a integração com Fluid Styled Content existem mecanismos de override próprios que garantem a coexistência dos content elements fornecidos com os elementos do core. Paths TypoScript são consistentemente namespaced, para que vários site packages rodem em paralelo na mesma instalação.

Problemas frequentes e soluções

O primeiro problema é a confusão com um framework. Times que integram um esqueleto de site package como Bootstrap ou Tailwind e esperam updates têm decepção: um esqueleto é um template para copiar, não um stack upstream. A solução é encarar o esqueleto como modelo único e versionar claramente o site package que dele sai.

O segundo problema é o inchaço com content elements não usados. O starter kit traz mais elementos do que a maioria dos projetos precisa. Quem não usa carrega mesmo assim pela manutenção. A solução é um cleanup imediatamente após o import inicial: apagar content elements não usados, remover backend layouts não usados, cortar blocos TypoScript não usados.

O terceiro problema é a adaptação a design systems individuais. Esqueletos costumam trazer CSS próprio com classes utility próprias. Quem usa um design system existente com nomes de token próprios precisa traduzir os stylings entregues de forma consistente, senão surge duplicidade de estilo e cascata contraditória.

Um quarto problema são conflitos com outros starter kits. Quem adota parcialmente um esqueleto e integra em paralelo blocos de outro esqueleto ganha paths TypoScript contraditórios e namespaces Fluid sobrepostos. A solução é tomar, no início do projeto, uma decisão por exatamente um esqueleto e manter componentes adicionais inconsistentes em uma camada própria do projeto claramente nomeada.

Migração e compatibilidade de versões

O in2template não foi publicado; por isso não é possível verificar quais versões do TYPO3 ele suporta. Como um esqueleto em projetos é quase sempre clonado e adaptado, a questão de versão é menos uma questão de caminhos de update e mais uma questão de disciplina de código: times devem, no upgrade do próprio site package, lançar um olhar em modelos atuais como o Site Package Builder do TYPO3 para incorporar melhorias estruturais (novas convenções de backend layout, novos patterns Fluid).

Importante no upgrade de um site package baseado em in2template é olhar convenções TYPO3 alteradas: TCA overrides, definições de backend layout, registro de content element e renderização Fluid mudaram várias vezes entre v11 e v13. Quem não replica essas mudanças no próprio site package corre o risco de conteúdos no backend ficarem de repente vazios ou os wizards de content element não aparecerem mais.

A Gosign assume em projetos TYPO3 a análise de quais partes do site package existente podem ser arrumadas segundo um padrão semelhante ao in2template e quais migram melhor para um esqueleto próprio minimalista. O resultado é um site package que passa por code reviews sem murmúrios e que no próximo upgrade TYPO3 não produz surpresas.