Linked Checkbox para TYPO3

form_element_linked_checkbox torna consentimentos LGPD (PT: RGPD) realmente clicáveis

O Form Framework do core TYPO3 conhece uma checkbox, mas não uma checkbox com label vinculado. Quem trabalha com o elemento padrão não consegue colocar no label um link para a política de privacidade ou para os termos de uso, e isso é justamente uma exigência que aparece em todo formulário na prática. A extensão form_element_linked_checkbox fecha essa lacuna com um custom form element limpo que combina texto e link. Para qualquer instalação TYPO3 que use o Form Framework nativo, essa extensão é praticamente obrigatória. Sem ela, a única saída é o workaround de estender o texto do label com um bloco de texto ao lado, o que não só parece desleixado como também é problemático para leitores de tela e acessibilidade.

Cenários típicos estão no entorno de compliance de todo site corporativo

O primeiro e mais frequente cenário são consentimentos LGPD abaixo de formulários de contato, newsletter e candidatura. O texto “Li a política de privacidade e concordo com o tratamento dos meus dados” precisa conter um link clicável para /politica-de-privacidade sem que o visitante tenha que marcar a caixa para abrir. O form_element_linked_checkbox cobre esse caso exatamente.

Um segundo cenário são confirmações de termos em formulários de registro e compra. Universidades usam isso em inscrições em cursos, associações em pedidos de associação, projetos e-commerce com o Form Framework do TYPO3 em checkouts. Aqui frequentemente não se trata só de um link, mas de vários (termos, direito de arrependimento, política de privacidade) que precisam caber no mesmo label.

O terceiro cenário envolve newsletters com Double Opt-In. Antes da inscrição, o destinatário precisa confirmar explicitamente que assina a newsletter, com link para os avisos de privacidade específicos. O form_element_linked_checkbox permite usar várias checkboxes com links próprios no mesmo formulário, de modo que além do consentimento de privacidade também o consentimento explícito para newsletter seja pedido como elemento separado. Isso é importante porque a LGPD exige consentimentos separados e uma checkbox genérica de “concordo com tudo” não basta juridicamente.

Arquitetura técnica está no sistema de plugins do Form Framework

O Form Framework do TYPO3 foi projetado deliberadamente como extensível: qualquer extensão pode registrar form elements próprios, que aparecem no editor YAML e ficam disponíveis via drag and drop no backend. O form_element_linked_checkbox usa esse mecanismo e registra um novo elemento “LinkedCheckbox” via YAML de setup do Form Framework e na área de definição de form elements. Redatores arrastam o elemento para seu formulário, exatamente como fariam com uma checkbox padrão, e configuram label, texto do link e destino no painel de detalhes.

Internamente, a extensão estende a classe Checkbox e adiciona propriedades para linkTarget, linkText e wrapLabel. A renderização acontece via Fluid partial próprio, que fragmenta o label em “before”, “linkText” e “after” e estende a área clicável apenas sobre a parte do link. O clique no link abre a página de destino sem alternar o estado da checkbox. Para acessibilidade, isso é importante, porque leitores de tela leem o link como elemento separado e a checkbox pode ser operada independentemente.

A configuração é feita diretamente no editor YAML do Form Framework: após arrastar o elemento para um formulário, os campos “Label antes do link”, “Texto do link”, “Label depois do link” e “Destino do link” aparecem na coluna de detalhes à direita. O destino pode ser uma página interna, um link de arquivo ou um URL externo. A validação de obrigatoriedade é definida, como no elemento padrão, via a aba Validators.

Problemas frequentes envolvem multilinguismo, estilização e mensagens de validator

O primeiro tema de suporte é a tradução. O label é formado por três partes, e cada parte precisa ser mantida separadamente em cada idioma. Na prática, isso significa: para uma instalação bilíngue (BR/EN), o esforço de manutenção dobra. Quem trabalha com ext:l10nmgr deve referenciar chaves LLL explicitamente na definição do formulário, para que import/export funcione sem problemas. Um truque de projetos maiores: armazenar as três partes do label em uma única chave LLL com placeholders e montar no servidor na saída. Isso reduz perceptivelmente o número de strings a traduzir.

O segundo tema é estilização. Muitos design systems trabalham com checkboxes customizadas, reconstruídas via CSS a partir de um span ou label. O template default da extensão entrega um wrapper simples que colide com alguns CSS frameworks. Recomendamos sobrescrever o partial no overlay de site package e ajustar a estrutura ao styling do restante do formulário.

Em terceiro, mensagens de erro do validator são tropeço frequente. Se o usuário não clica na checkbox, deve aparecer “Por favor, aceite a política de privacidade”, não a mensagem default “Campo obrigatório”. A extensão suporta mensagens de erro customizadas via formElementsDefinition no YAML do formulário; a mensagem pode ser adaptada por elemento. Para acessibilidade isso é importante, porque leitores de tela leem a mensagem de erro diretamente e mensagens inespecíficas não ajudam. Recomendamos formular cada mensagem de erro de forma compreensível independentemente do contexto.

TYPO3 v12 e v13 são totalmente suportados, migração de v10 exige ajuste no YAML

O form_element_linked_checkbox está disponível para TYPO3 v11, v12 e v13. A estrutura YAML do Form Framework mudou em detalhes entre v10 e v12, principalmente no registro de custom elements. No upgrade de uma instalação v10, definições de formulário que usam o elemento precisam ser adaptadas à nova sintaxe YAML.

Em projetos Gosign, migramos a extensão como parte do refactoring do Form Framework, não separadamente. O esforço é quase sempre mínimo, porque o elemento em cada formulário é referenciado apenas pelo seu type identifier. Na migração, verificamos ainda se os textos de consentimento LGPD são renderizados corretamente em cada idioma após o upgrade do TYPO3, e atualizamos os links de privacidade caso tenham mudado de URL ou texto.