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 é desde 2016 o framework mais utilizado para Custom Content Elements no TYPO3. Mais de 1.500 instalações ativas (dados: Packagist, abril 2026) e a inclusão na documentação oficial do TYPO3 como caminho recomendado para elementos de conteúdo individuais confirmam seu status como padrão de fato.

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 ou config/mask.json desde o Mask 8). 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 completamente o padrão 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 8, foram adicionados campos nativos JSON e uma API aprimorada.

Templates Fluid ficam por padrão em fileadmin/templates/mask/ 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). Nenhuma outra extensão é necessária. 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. A partir do Mask 8, a geração TCA é significativamente mais performática do que em versões anteriores.

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. No Mask 8.x, esse comportamento é mais estável que no 7.x.

Migração e compatibilidade de versões

Mask suporta ativamente TYPO3 v12 e v13. A versão estável atual (Mask 8.x) funciona em ambos os releases LTS. TYPO3 v11 é coberto pelo Mask 7.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.

A partir do TYPO3 v13, a API nativa Content Block também está disponível. Para projetos Mask existentes, isso não exige pressa: Mask e Content Blocks coexistem sem problemas. Novos projetos em TYPO3 v13 puro podem avaliar se a abordagem nativa é 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 como tooltip 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.