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 recorte, escala, alt text, copyright, destino de link e, sobretudo, saída srcset. 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, o cropping 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 cropping, zoom e height. Na renderização, um pre-processor substitui a tag de marcação por uma chamada completa do Image ViewHelper, que gera srcset, variantes webp e atributos de lazy loading. As larguras de imagem disponíveis são definidas via YAML na configuração RTE. Um setup típico de revista trabalha com três a cinco larguras (480, 768, 1024, 1440, 2048) e gera a partir delas, automaticamente, um srcset responsivo que em dispositivos móveis só carrega a variante menor.

O cropping usa a ferramenta de cropping do core TYPO3: no diálogo de imagem aparece o crop editor do backend, com os mesmos presets de variante usados no elemento de conteúdo de imagem regular. O cropping é salvo por instância de imagem, de forma que a mesma imagem FAL pode ter cortes diferentes em artigos distintos. Isso é especialmente importante quando uma imagem é usada tanto no teaser da revista (quadrada) quanto no texto corrido (landscape), 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 não gera srcset se o YAML do RTE não tem definição de larguras de imagem. Muitas instalações copiaram o YAML do core TYPO3 e deixaram de fora a seção “proc.entryHTMLparser_db.allowedAttribs” ou “config.additionalAttributes”. A solução é um YAML completo com larguras srcset explicitamente definidas.

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 10.x e 11.x de rte_ckeditor_image foram portadas para CKEditor 5 e funcionam out of the box no v12. 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 as versões da extensão 9.x (CKEditor 4) e 10.x/11.x (CKEditor 5). Quem leva uma instalação TYPO3 v10 ou v11 com extensão 9.x para TYPO3 v12 precisa simultaneamente mudar para a série 10.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 as funções nativas de imagem do CKEditor 5 bastam e se a extensão pode ser desativada a médio prazo. Para redações com necessidade de cropping e srcset, 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.