rte_ckeditor_image para TYPO3: Edição de imagens no Rich Text Editor

rte_ckeditor_image traz gerenciamento profissional de imagens ao Rich Text Editor

O CKEditor do TYPO3 só permite inserções simples de imagem via img tag, sem ligação ao File Abstraction Layer e sem variantes responsivas. Para redações que inserem imagens regularmente em artigos, news ou textos de revista, isso não basta: elas precisam de escala, alt text, legenda, destino de link e, sobretudo, saída nítida em telas de alta densidade. O rte_ckeditor_image da Netresearch complementa o CKEditor com exatamente essas funções e o integra de forma limpa ao FAL. Em todo projeto TYPO3 com imagens editorialmente mantidas em texto corrido, a extensão é há anos a ferramenta padrão e está entre os auxiliares editoriais mais instalados do ecossistema.

Cenários típicos estão em redações com alto volume de imagens

Revistas online e páginas de news corporativas são o público-alvo clássico. Uma revista brasileira com 200 artigos por ano insere por matéria de duas a cinco imagens no texto corrido, além de imagens de teaser e cabeçalho. Sem o rte_ckeditor_image, a redação teria que aceitar uma troca de elemento de conteúdo para cada imagem inline e interromper o fluxo de texto. Com a extensão, ela insere a imagem diretamente via botão na toolbar, escolhe a referência FAL, define alt text e legenda e volta a escrever sem troca de contexto. O ganho de eficiência pode ser medido na prática: em uma redação com 200 matérias por ano e média de quatro imagens por matéria, economizamos cerca de dois minutos de tempo de setup por artigo, o que dá quase 30 horas de trabalho por ano.

Um segundo cenário são catálogos de produto e documentação técnica. Quem mantém em um catálogo TYPO3 instruções passo a passo com screenshots inline precisa das imagens diretamente no texto. O rte_ckeditor_image permite isso com as mesmas referências FAL usadas no resto do projeto, atualizações de imagem acontecem em um lugar só e afetam todas as ocorrências.

Um terceiro cenário é a migração de instalações TYPO3 da era htmlArea. Quem usava antes o RTEhtmlArea tinha ali um gerenciamento de imagens semelhante. Na transição para CKEditor, o rte_ckeditor_image é a extensão de substituição direta, para que redatores continuem usando o workflow familiar. Sem a extensão, a redação perde no upgrade não só uma função, mas um passo inteiro de trabalho, substituível com dificuldade por content elements adicionais.

Arquitetura técnica estende a toolbar do CKEditor via plugin

A extensão consiste em um plugin CKEditor que registra o botão Image e o diálogo Image, além de uma renderização server-side que traduz o marker no HTML salvo em uma saída Fluid. O plugin se comunica com um endpoint AJAX que processa a referência FAL, as dimensões da imagem e os alt texts.

No conteúdo do banco, a imagem fica como marcação HTML com os data attributes data-htmlarea-file-uid e data-htmlarea-file-table, acompanhada por outros atributos de zoom, nível de qualidade, width e height. Na renderização, uma preUserFunc em lib.parseFunc_RTE processa a tag de marcação: redimensiona a imagem pelo processamento de imagens do TYPO3, define o atributo de lazy loading e gera figure, link e legenda por partials Fluid sobrescrevíveis. Os limites de largura e altura ficam no Page TSconfig (maxWidth, maxHeight). Um setup típico de revista trabalha com três a cinco larguras (480, 768, 1024, 1440, 2048) e precisa de uma preUserFunc própria para o srcset, como a que a documentação da extensão mostra como exemplo; a extensão sozinha não gera srcset.

O diálogo de imagem define largura, altura, alt text, título, nível de qualidade e a ampliação ao clicar. O cropping com variantes só é oferecido pelo elemento de conteúdo de imagem regular. Largura e altura são salvas por instância de imagem, de forma que a mesma imagem FAL pode aparecer em tamanhos diferentes em artigos distintos. Isso é especialmente importante quando uma imagem é usada em tamanhos diferentes tanto no teaser da revista quanto no texto corrido, sem que a redação precise manter dois arquivos separados.

Problemas frequentes envolvem saída responsiva, WebP e compatibilidade com CKEditor 5

O tema de suporte mais frequente é a saída srcset faltante. O caminho de rendering default nunca gera srcset, apenas uma versão redimensionada da imagem. Não há configuração de larguras srcset, nem no YAML do RTE nem na configuração da extensão. A solução é uma preUserFunc própria segundo o exemplo da documentação, que gera uma variante processada para cada largura.

O segundo problema é o WebP. Quem quer entregar formatos modernos de imagem precisa configurar o provedor ImageMagick do TYPO3 ou um setup GraphicsMagick com suporte a WebP. O próprio rte_ckeditor_image não gera conversão WebP, mas recorre ao image processor do core. Sem configuração correta do provedor, as imagens permanecem como JPEG na saída.

Em terceiro, o CKEditor 5 representa uma mudança de arquitetura. O TYPO3 v12 traz o CKEditor 5, que usa um modelo diferente de plugin. As versões 12.x para TYPO3 v12 e 13.x para v13 e v14 de rte_ckeditor_image foram portadas para CKEditor 5 e funcionam out of the box. Adaptações próprias baseadas no CKEditor 4 precisam ser ajustadas no upgrade. Quem construiu plugins custom ou botões próprios na toolbar deve planejar pelo menos um a dois dias de desenvolvedor para a migração.

Migração para TYPO3 v12 e v13 exige salto de versão da extensão

O rte_ckeditor_image é mantido ativamente pela Netresearch e está disponível para TYPO3 v11, v12 e v13. O salto maior está entre a série 11.x da extensão, com CKEditor 4, e as séries 12.x e 13.x, com CKEditor 5. Quem leva uma instalação TYPO3 v10 ou v11 com extensão 10.x ou 11.x para TYPO3 v12 precisa simultaneamente mudar para a série 12.x da extensão. A representação no banco de dados das imagens inline permanece compatível, de forma que artigos existentes funcionam sem migração de conteúdo.

Na Gosign, verificamos antes de cada upgrade TYPO3 se o YAML do RTE do projeto precisa ser ajustado à versão da extensão e se existem adaptações próprias de plugin ou ViewHelpers sobrescritos. Em muitos projetos com TYPO3 v12 dá ainda para verificar se imagens como elementos de conteúdo próprios bastam e se a extensão pode ser desativada a médio prazo. Para redações que precisam de imagens dentro do texto corrido, no entanto, o rte_ckeditor_image permanece a opção mais pragmática. A alternativa seria um botão de imagem próprio na toolbar com plugin CKEditor custom, o que é muito mais trabalhoso e coloca a manutenção permanentemente sob responsabilidade do projeto.