Mask para TYPO3

Editores precisam de elementos de conteúdo próprios, não de mais gambiarras com campos de texto

Todo site TYPO3 chega ao ponto em que os elementos de conteúdo padrão não são mais suficientes. Um carrossel de equipe, uma tabela de preços com toggles, um teaser de produto com imagem, texto e botão CTA - essas demandas acabam no RTE como HTML desorganizado ou em um container Flexform sobrecarregado. Mask resolve esse problema de forma fundamental: editores recebem formulários de backend próprios com exatamente os campos que precisam. Sem classes PHP, sem TCA manual, sem ext_tables.sql.

Mask é há anos um dos frameworks mais utilizados para Custom Content Elements no TYPO3. Mais de 1,7 milhão de downloads no Packagist (dados: setembro de 2026) e a menção na documentação oficial do TYPO3 ao lado de Content Blocks e DCE confirmam sua difusão.

Cenários típicos de uso

Sites corporativos com estruturas de página complexas. Equipes de marketing precisam de 15 a 30 elementos de conteúdo diferentes: hero banners, depoimentos, acordeões, conteúdo em abas, downloads com miniatura, cartões de contato. Mask representa cada um como formulário de backend próprio. Editores veem apenas os campos relevantes para cada elemento, sem confusão com opções irrelevantes.

Projetos multilíngues com estrutura consistente. Elementos Mask suportam completamente os mecanismos de tradução do TYPO3. Campos podem ser configurados como l10n_mode exclude (não traduzível) ou prefixLangTitle (traduzível com indicação). Em sites com 5 ou mais idiomas, isso economiza tempo de edição, pois a estrutura permanece idêntica e apenas o conteúdo é traduzido.

Projetos de relançamento com dados existentes. Quem migra de um sistema antigo (WordPress, TYPO3 com Gridelements ou TemplaVoila) precisa de estruturas de conteúdo limpas. Elementos Mask podem ser exportados como extensão independente via mask_export. Assim, as definições de conteúdo tornam-se versionáveis e implantáveis via pipelines CI/CD.

Arquitetura técnica

Mask armazena a configuração de todos os elementos de conteúdo em um único arquivo JSON (mask.json, por padrão em Configuration/Mask/ do site package). Este arquivo descreve campos, tipos, paletas e a associação com templates Fluid. Ao ativar ou atualizar, o Mask gera automaticamente as configurações TCA e campos de banco de dados necessários.

Os tipos de campo cobrem os tipos mais usados do TYPO3: String, Integer, Float, RichText, Date, DateTime, File (FAL), Inline (IRRE para estruturas aninhadas), Select, Checkbox, Radio, Link, Slug, Color Picker, Tab, Palette. Desde o Mask 7.1, essa configuração também pode ser dividida em um arquivo JSON por elemento.

Templates Fluid ficam por padrão no site package, em Resources/Private/Mask/Frontend/Templates, ou em um caminho configurável. Cada elemento de conteúdo tem seu próprio template, opcionalmente com Partials e Layouts. Mask registra os elementos no New Content Element Wizard, incluindo ícone e descrição.

Dependências são mínimas: Mask precisa apenas do TYPO3 Core (v11, v12, v13 são ativamente suportados). Para v12 e v13 nenhuma outra extensão é necessária; para v11, o Mask 8.x traz fontawesome_provider como dependência. Para o workflow de exportação, mask_export é uma adição opcional.

Problemas frequentes e soluções

Alterações de campo em sistemas produtivos. Se um campo Mask é alterado no sistema de staging (tipo, nome do campo), mas o banco de dados em produção não é atualizado, surgem erros. Solução: usar mask_export para que alterações de configuração passem por Git e pipelines de deployment. Alternativa: Database Compare no Install Tool após cada deployment.

Performance com muitos elementos de conteúdo. Sites com mais de 40 elementos Mask diferentes geram uma configuração TCA grande. TYPO3 carrega esta configuração em cada chamada do backend. Solução: agrupar elementos de forma lógica, desativar os não utilizados, manter o cache do backend ativo. Desde o Mask 7.1, o Mask processa sua configuração como objetos em vez de arrays, o que é bem mais rápido.

Elementos aninhados (IRRE) e ordenação. Relações inline (por exemplo, slides dentro de um elemento slider) podem perder a ordenação ao copiar e colar. Solução: definir explicitamente um campo de ordenação e garantir o <f:for> com sortBy no template Fluid. Após cada atualização do Mask, vale um teste rápido desse comportamento.

Migração e compatibilidade de versões

Mask suporta ativamente TYPO3 v12 e v13. A versão estável atual (Mask 9.x) funciona em ambos os releases LTS. TYPO3 v11 é coberto pelo Mask 8.x, mas não recebe mais novos recursos.

Para projetos que ainda usam TemplaVoila ou DCE, o Mask oferece um caminho de migração claro. Elementos DCE podem ser convertidos manualmente para Mask: reconstruir campos na GUI do Mask, adaptar templates Fluid, migrar dados via script SQL. A Gosign realizou esse processo em projetos com mais de 20 elementos DCE e estimou o esforço entre 2 e 5 dias, dependendo da complexidade.

Para o TYPO3 v13 e v14 existe também a extensão Content Blocks (friendsoftypo3/content-blocks). Para projetos Mask existentes, isso não exige pressa: Mask e Content Blocks coexistem sem problemas. Novos projetos em TYPO3 v13 ou v14 podem avaliar se o Content Blocks é suficiente ou se o Mask oferece vantagens através da sua GUI e workflow de exportação. A Gosign aconselha de forma específica para cada projeto, identificando qual abordagem gera menor esforço de manutenção a longo prazo.

Um aspecto frequentemente subestimado é a documentação. Elementos Mask são autoexplicativos para desenvolvedores (campos, tipos, templates), mas editores precisam de orientação: quais campos são obrigatórios? Qual tamanho de imagem é ideal? O que acontece se o campo de descrição ficar vazio? Mask suporta desde a versão 7 textos descritivos por campo, que aparecem abaixo do rótulo do campo no backend. A Gosign cria adicionalmente um manual de edição interno por projeto, onde cada elemento Mask é documentado com screenshot, descrição de campo e boas práticas. O esforço é de meia hora por elemento, mas economiza consultas durante a operação.

Para a configuração inicial de um projeto Mask com 15 a 20 elementos de conteúdo, a Gosign calcula 3 a 5 dias de desenvolvimento, incluindo templates Fluid, preview de backend e configuração mask_export. Elementos individuais novos durante a operação são implementados em 1 a 4 horas, dependendo da complexidade do aninhamento e do design do template.