Mask Twig para TYPO3

Por que desenvolvedores frontend preferem Twig ao Fluid e como Mask viabiliza isso

TYPO3 aposta com Fluid em uma engine de templates que é única no mundo PHP. Isso é simultaneamente sua força e seu maior problema: desenvolvedores frontend vindos do ecossistema Symfony, Laravel ou Node.js conhecem Twig ou Nunjucks. Fluid não conhecem. O mask_twig_nunjucks_connector fecha essa lacuna permitindo que Mask Content Elements sejam renderizados com templates Twig ou Nunjucks em vez de templates Fluid.

Para agências cuja equipe frontend trabalha com Twig e não tem interesse em aprender uma nova linguagem de templates para cada projeto TYPO3, o connector é a solução pragmática. Partials Twig existentes de projetos Symfony ou componentes Nunjucks de pattern libraries podem ser reutilizados diretamente.

Cenários típicos de uso

Agências com backend Symfony e frontend TYPO3. Uma agência desenvolve suas aplicações web em Symfony e usa TYPO3 apenas para gerenciamento de conteúdo. A equipe frontend construiu uma extensa biblioteca de componentes Twig. Em vez de reescrever todos os componentes em Fluid para TYPO3, o connector incorpora os templates Twig existentes diretamente em Mask Content Elements.

Integração de pattern library com Nunjucks. Uma equipe de design mantém uma pattern library (ex: baseada em Fractal ou Storybook) que usa Nunjucks como linguagem de templates. O connector permite usar os mesmos templates Nunjucks tanto na pattern library quanto no TYPO3.

Onboarding de desenvolvedores frontend em projetos TYPO3. Um novo desenvolvedor frontend começa em um projeto TYPO3. Em vez de primeiro aprender Fluid (sintaxe, namespaces, conceito de ViewHelper), ele escreve templates Twig que já domina. A curva de aprendizado para o projeto se reduz de 2 a 3 dias para poucas horas.

Arquitetura técnica

O mask_twig_nunjucks_connector funciona como ponte de renderização entre a extensão Mask e um motor de templates alternativo. Mask define Custom Content Elements com campos de backend. Por padrão, Mask renderiza esses elementos com templates Fluid. O connector substitui essa etapa de renderização.

A implementação técnica: a integração Twig usa a biblioteca PHP twig/twig (a mesma que o Symfony usa). Templates Twig são armazenados no sistema de arquivos. Os campos Mask ficam disponíveis como variáveis de template ({{ data.header }}, {{ data.bodytext }}). A integração Nunjucks pode renderizar templates server-side via bridge Node.js ou entregar como templates JavaScript client-side.

O mapeamento de variáveis ocorre automaticamente: campos simples (Text, Integer, Float) são passados diretamente. Referências FAL (imagens, arquivos) são passadas como objetos com URL, título e texto alternativo. Relações são resolvidas como arrays.

Dependências: TYPO3 Core, Extensão Mask, pacote Composer twig/twig (para Twig) ou Node.js (para Nunjucks server-side). Na prática, mais de 90% das instalações do connector usam Twig, não Nunjucks.

Problemas frequentes e soluções

Template Twig não tem acesso a dados específicos do TYPO3. Fluid ViewHelpers como f:uri.page, f:translate ou f:cObject não existem em Twig. Um template Twig não pode acessar diretamente a árvore de páginas TYPO3, traduções ou outros elementos de conteúdo. Solução: todos os dados necessários devem ser fornecidos via mapeamento de variáveis. O connector pode injetar dados adicionais no contexto do template via configuração.

Renderização Nunjucks é lenta. A bridge Node.js para renderização Nunjucks server-side inicia um processo Node para cada request. Com páginas com mais de 10 elementos Mask, os tempos de renderização se acumulam. Solução: usar um worker process Node.js persistente ou migrar para Twig, que renderiza nativamente em PHP.

Atualização Mask quebra nomes de variáveis de template. Quando Mask renomeia um campo ou muda um tipo de campo, as variáveis de template mudam. Templates Fluid mostram campos vazios, templates Twig lançam erros. Solução: operar Twig em strict mode e testar templates após cada atualização Mask.

Migração e compatibilidade de versões

O mask_twig_nunjucks_connector é um projeto comunitário com distribuição limitada. A compatibilidade depende da extensão Mask: Mask é ativamente mantido e suporta TYPO3 v11 e v12. O connector deve ser verificado quanto à compatibilidade a cada atualização Mask.

A Gosign recomenda o connector para projetos onde a equipe frontend trabalha exclusivamente com Twig e traz uma biblioteca de componentes existente. Para projetos TYPO3 puros sem requisitos externos de templates, Fluid permanece a melhor escolha, pois é suportado nativamente, não tem dependências adicionais e pode usar toda a biblioteca de ViewHelpers TYPO3. O ganho de produtividade pela reutilização de Twig deve superar o esforço de manutenção do connector - uma ponderação que deve ser quantificada concretamente a cada início de projeto.