Embedded Content
Proporciona un sistema de plugins para CKEditor 5 que permite a los editores insertar componentes configurables y con estilos en contenido de texto enriquecido sin requerir permisos de HTML.
embedded_content
Instalar
composer require 'drupal/embedded_content:^2.0'
Overview
Embedded Content es un módulo potente que conecta a los editores de contenido con los desarrolladores proporcionando un sistema flexible para incrustar componentes personalizados dentro de CKEditor 5. Los editores pueden insertar componentes preconfigurados con estilos a través de botones intuitivos en la barra de herramientas, mientras que los desarrolladores tienen control total sobre qué componentes están disponibles y cómo se renderizan.
El módulo utiliza una arquitectura de plugins donde los desarrolladores crean plugins de EmbeddedContent que definen formularios de configuración y lógica de renderizado. Estos plugins se ponen a disposición a través de botones configurables en la barra de herramientas que pueden añadirse a cualquier formato de texto de CKEditor 5. Cuando se guarda el contenido, el módulo almacena los datos del componente como elementos HTML personalizados (<embedded-content>) que son procesados por un filtro de texto para generar la salida final.
Los beneficios clave incluyen: los editores no necesitan permisos de 'HTML Completo' para usar componentes con estilos, los desarrolladores pueden crear elementos interactivos complejos, y la integración con CKEditor 5 proporciona una vista previa visual inmediata del contenido incrustado durante la edición.
Features
- Integración con CKEditor 5 con botones personalizados en la barra de herramientas para incrustar componentes con estilos
- Sistema de plugins para que los desarrolladores creen tipos de contenido incrustado personalizados con formularios configurables y lógica de renderizado
- Filtro de texto que procesa las etiquetas <embedded-content> y <embedded-content-inline> convirtiéndolas en HTML renderizado
- Interfaz de administración para gestionar botones de contenido incrustado con iconos personalizados, etiquetas y configuración de diálogos
- Soporte tanto para contenido incrustado a nivel de bloque como en línea
- Configuración de diálogos/modales incluyendo ancho, alto y tipo de renderizador (modal o off-canvas)
- Personalización de iconos SVG para los botones de la barra de herramientas
- Filtrado de plugins usando patrones comodín y condiciones regex
- Generación dinámica de permisos para cada botón configurado
- Vista previa en vivo del contenido incrustado dentro del editor CKEditor 5
- Funcionalidad de edición para contenido incrustado existente a través de la barra de herramientas del widget
Use Cases
Cuadros de llamada y alertas
Crear un plugin de EmbeddedContent que permita a los editores insertar cuadros de llamada con estilos (información, advertencia, éxito, error) con texto personalizado. Los editores seleccionan el tipo e introducen el contenido, y el módulo renderiza un cuadro de alerta con estilo consistente sin necesitar permisos de clases CSS.
Incrustaciones de redes sociales
Crear plugins que permitan a los editores pegar una URL de redes sociales y que se renderice como una publicación incrustada. El formulario de configuración valida la URL, y el método build genera el código de incrustación apropiado con el estilo adecuado.
Widgets de visualización de datos
Crear plugins para gráficos, tablas u otras visualizaciones de datos. Los editores configuran los datos a través de un formulario, y el plugin renderiza gráficos interactivos usando una biblioteca JavaScript, todo sin acceso directo a HTML.
Referencias a productos o contenido
Crear plugins que permitan a los editores buscar e incrustar tarjetas de productos, avances de artículos u otras referencias a entidades con opciones de visualización personalizadas, proporcionando una experiencia más guiada que la incrustación de entidades en bruto.
Componentes interactivos
Desarrollar plugins para acordeones, pestañas u otros componentes de interfaz interactivos. Los editores configuran las secciones a través del formulario, y el módulo genera la estructura HTML apropiada con los comportamientos JavaScript asociados.
Fragmentos de código con resaltado de sintaxis
Crear un plugin que proporcione un editor de código en el formulario de configuración, permitiendo a los editores pegar código y seleccionar el lenguaje. El método build genera bloques de código con resaltado de sintaxis usando una biblioteca como Prism o Highlight.js.
Tips
- Crea botones separados para diferentes tipos de contenido o roles de usuario para controlar qué plugins están disponibles para diferentes editores
- Usa el renderizador de diálogo off-canvas para una experiencia de edición menos intrusiva, especialmente para plugins más simples
- Las condiciones de plugin soportan patrones regex para escenarios de coincidencia complejos más allá de los comodines simples
- Implementa el método isInline() en tu plugin para que devuelva true para elementos en línea que deban fluir dentro del texto
- Usa el método getAttachments() en los plugins para adjuntar bibliotecas CSS/JS necesarias para el renderizado en el frontend
- El método massageFormValues() te permite transformar los valores del formulario antes de almacenarse, útil para limpieza o normalización
- Considera las implicaciones de caché en el método build() de tu plugin, especialmente para plugins que renderizan contenido dinámico o específico del usuario
Technical Details
Admin Pages 5
/admin/config/content/embedded-content
Página principal de administración del módulo Embedded Content. Proporciona acceso a la configuración de botones.
/admin/config/content/embedded-content/button
Lista todos los botones de contenido incrustado configurados. Cada botón representa un elemento de la barra de herramientas que los editores pueden usar para insertar contenido incrustado. La lista muestra la etiqueta del botón, el nombre de máquina y el estado.
/admin/config/content/embedded-content/button/add
Formulario para crear un nuevo botón de contenido incrustado que aparecerá en la barra de herramientas de CKEditor 5. Configura la apariencia del botón, su comportamiento y qué plugins puede acceder.
/admin/config/content/embedded-content/button/{embedded_content_button}
Editar una configuración de botón de contenido incrustado existente. Mismos campos del formulario que el de añadir, con una sección adicional de vista previa del icono.
/admin/config/content/embedded-content/button/{embedded_content_button}/delete
Formulario de confirmación para eliminar un botón de contenido incrustado. Esto eliminará el botón de la barra de herramientas de todos los formatos de texto que lo usen.
Permisos 2
Hooks 1
hook_embedded_content_info_alter
Permite a los módulos alterar las definiciones de plugins de contenido incrustado descubiertas por el gestor de plugins.
Troubleshooting 5
Asegúrate de haber habilitado un módulo que proporcione plugins de EmbeddedContent. El módulo principal no incluye ningún plugin por defecto. Puedes habilitar el módulo embedded_content_test para ver ejemplos, o crear tus propios plugins en un módulo personalizado.
Asegúrate de que: 1) El botón de contenido incrustado está configurado en /admin/config/content/embedded-content/button, 2) El botón está arrastrado a la barra de herramientas en la configuración del formato de texto, 3) El filtro 'Embedded Content' está habilitado para ese formato de texto, 4) El usuario tiene permiso para usar ese botón específico.
Verifica el campo 'Condiciones de plugin' en la configuración del botón. Si hay patrones especificados, el ID de tu plugin debe coincidir con uno de ellos. Deja el campo vacío para mostrar todos los plugins disponibles.
El contenido incrustado puede estar referenciando un plugin que ya no existe o ha sido deshabilitado. Elimina el contenido incrustado y vuelve a insertarlo con un plugin válido.
Asegúrate de que el filtro de texto 'Embedded Content' está habilitado y ordenado correctamente en el formato de texto. Debe ejecutarse después de los filtros que puedan interferir con las etiquetas HTML personalizadas pero antes de los que sanean la salida.
Security Notes 3
- Los plugins de contenido incrustado deben validar y sanear todos los valores de configuración en el método build() para prevenir ataques XSS
- El módulo almacena la configuración del plugin como JSON en atributos data; los plugins nunca deben confiar en estos datos sin validación
- Solo los usuarios con el permiso específico del botón pueden usar ese botón de la barra de herramientas, proporcionando control de acceso granular