Embed
Proporciona un framework para diferentes tipos de incrustaciones en editores de texto, incluyendo una API para crear plugins de tipos de incrustación y una interfaz de usuario para gestionar botones de incrustación.
embed
Install
composer require 'drupal/embed:8.x-1.10'
composer require 'drupal/embed:8.x-1.9'
Overview
El módulo Embed proporciona un framework base para incrustar varios tipos de contenido dentro de editores de texto WYSIWYG como CKEditor 4 y CKEditor 5. Sirve como una API base que otros módulos pueden extender para proporcionar funcionalidad de incrustación específica.
El módulo introduce el concepto de "Botones de Incrustación" que aparecen en la barra de herramientas del editor de texto y permiten a los editores de contenido insertar contenido incrustado. Cada botón está asociado con un plugin de "Tipo de Incrustación" que define qué tipo de contenido puede ser incrustado y cómo se configura.
Las capacidades principales incluyen:
- Un sistema de plugins para definir tipos de incrustación personalizados
- Entidad de configuración para gestionar botones de incrustación
- Integración completa con CKEditor 4 y CKEditor 5
- Sistema de vista previa protegido con CSRF para contenido incrustado
- Gestión de iconos con soporte SVG para compatibilidad con CKEditor 5
- Utilidades de manipulación DOM para implementaciones de filtros
Este módulo se utiliza típicamente en conjunto con módulos como Entity Embed o Media Embed que proporcionan implementaciones específicas de tipos de incrustación.
Features
- Arquitectura basada en plugins para definir tipos de incrustación personalizados que pueden incrustar diferentes tipos de contenido
- Sistema de entidades de configuración para crear y gestionar botones de incrustación con etiquetas e iconos personalizados
- Integración completa con los editores de texto CKEditor 4 y CKEditor 5 a través de bases de plugins dedicadas
- Endpoint de vista previa protegido con CSRF que renderiza contenido incrustado usando el formato de filtro apropiado
- Sistema de gestión de iconos que soporta iconos personalizados almacenados como datos codificados en base64, con requisito de SVG para compatibilidad con CKEditor 5
- Utilidades auxiliares de DOM (DomHelperTrait) para manipular elementos DOM en plugins de filtro
- Sistema de control de acceso que valida la disponibilidad del botón de incrustación en configuraciones del editor
- Sistema de comandos AJAX para insertar contenido incrustado en instancias del editor
- Derivación automática de plugins de CKEditor 5 desde configuraciones de botones de incrustación
Use Cases
Creando un botón de Entity Embed
Instale el módulo Entity Embed que proporciona el tipo de incrustación 'entity'. Navegue a Admin > Configuración > Autoría de contenido > Botones de incrustación. Haga clic en 'Añadir botón de incrustación', ingrese una etiqueta como 'Node', seleccione 'Entity' como tipo de incrustación, configure qué tipos de entidad y bundles pueden ser incrustados, suba un icono SVG y guarde. Luego edite su formato de texto para agregar el botón a la barra de herramientas de CKEditor 5 y habilite el filtro requerido.
Desarrollando un tipo de incrustación personalizado
Cree un tipo de incrustación personalizado implementando un plugin en el directorio src/Plugin/EmbedType de su módulo. Extienda EmbedTypeBase y agregue la anotación @EmbedType con id y label. Implemente getDefaultIconUrl() para proporcionar un icono de botón predeterminado. Opcionalmente sobrescriba buildConfigurationForm(), validateConfigurationForm() y submitConfigurationForm() para agregar configuraciones específicas del botón. Para integración con CKEditor 5, cree un plugin de CKEditor 5 que extienda EmbedCKEditor5PluginBase.
Previsualizando contenido incrustado
El módulo proporciona un endpoint de vista previa en /embed/preview/{filter_format} que renderiza contenido incrustado. Los plugins de CKEditor usan este endpoint con protección CSRF para mostrar vistas previas en vivo de elementos incrustados mientras se edita. La vista previa usa el mismo procesamiento de filtros que el contenido renderizado final.
Tips
- Siempre use iconos SVG para botones de incrustación para asegurar compatibilidad con CKEditor 5
- El módulo Embed es un framework - instale Entity Embed o módulos similares para funcionalidad de incrustación real
- Al desarrollar tipos de incrustación personalizados, extienda EmbedTypeBase para valores predeterminados sensatos
- Use los métodos de utilidad DomHelperTrait al implementar plugins de filtro que procesan contenido incrustado
- Los botones de incrustación son entidades de configuración y pueden exportarse/importarse con la gestión de configuración
- El módulo valida que los filtros requeridos estén habilitados cuando se agregan botones a las barras de herramientas del editor
Technical Details
Admin Pages 4
/admin/config/content/embed
Lista todos los botones de incrustación configurados mostrando su etiqueta, tipo de incrustación e icono. Proporciona operaciones para editar y eliminar cada botón. Esta es la interfaz principal de gestión para botones de incrustación.
/admin/config/content/embed/button/add
Formulario para crear un nuevo botón de incrustación. Permite establecer la etiqueta del botón, nombre de máquina, tipo de incrustación, configuraciones específicas del tipo e icono personalizado.
/admin/config/content/embed/button/manage/{embed_button}
Formulario para editar un botón de incrustación existente. El nombre de máquina y el tipo de incrustación no pueden cambiarse después de la creación.
/admin/config/content/embed/settings
Configuraciones globales para el módulo Embed, controlando dónde se almacenan los iconos de botones subidos.
Permissions 1
Hooks 1
hook_embed_type_plugins_alter
Permite a los módulos alterar las definiciones de plugins de tipos de incrustación después de que son descubiertos. Puede usarse para modificar etiquetas, agregar configuraciones o cambiar el comportamiento del plugin.
Troubleshooting 4
Asegúrese de que el botón use un icono SVG (requerido para CKEditor 5). Verifique la página de Informe de estado para advertencias de compatibilidad con CKEditor 5. Edite el botón y suba un archivo de icono SVG.
Instale un módulo que proporcione plugins de tipos de incrustación, como Entity Embed o Media Embed. El módulo Embed es un framework y requiere plugins de tipos de incrustación para funcionar.
Verifique que el token CSRF se esté enviando con las solicitudes de vista previa. Para usuarios autenticados, el encabezado X-Drupal-EmbedPreview-CSRF-Token debe contener un token válido. También verifique que el usuario tenga permiso para usar el formato de filtro.
Los iconos de botones se almacenan como datos codificados en base64 pero referencian una URI. Si el archivo no existe en la URI, se recreará automáticamente desde los datos codificados. Limpie cachés si los iconos no aparecen.
Security Notes 4
- El endpoint de vista previa usa protección CSRF para prevenir renderizado no autorizado de contenido. Para usuarios anónimos, la presencia del encabezado personalizado es suficiente; para usuarios autenticados, el valor del token es validado.
- El acceso a la administración de botones de incrustación requiere el permiso 'administer embed buttons'
- El acceso a la vista previa está controlado por permisos de uso de formato de filtro - los usuarios solo pueden previsualizar contenido usando formatos para los que tienen permiso de uso
- El módulo valida que los botones de incrustación en las barras de herramientas del editor tengan sus filtros requeridos habilitados para prevenir discrepancias de configuración