Entity Embed
Permite incrustar cualquier entidad dentro del contenido de texto utilizando CKEditor y opciones de visualización configurables.
entity_embed
Install
composer require 'drupal/entity_embed:8.x-1.7'
composer require 'drupal/entity_embed:8.x-1.6'
Overview
Entity Embed es un potente módulo de Drupal que permite a los editores de contenido incrustar cualquier entidad (nodos, medios, archivos, usuarios, términos de taxonomía, etc.) directamente en el contenido de texto utilizando el editor WYSIWYG CKEditor. El módulo extiende el sistema de filtros de texto de Drupal para reconocer y renderizar entidades incrustadas dentro de campos de texto formateado.
El módulo proporciona un sistema flexible de plugins para controlar cómo se muestran las entidades incrustadas, soportando varios formateadores de campo y modos de visualización. Se integra perfectamente con los sistemas Filter y Editor de Drupal, permitiendo a los administradores configurar qué entidades pueden ser incrustadas y cómo aparecen en el contenido.
Entity Embed soporta tanto CKEditor 4 (obsoleto) como CKEditor 5, proporciona integración con Entity Browser para una selección mejorada de entidades, e incluye APIs de hooks completas para personalización. El módulo maneja traducciones de entidades, opciones de alineación, leyendas y protección contra renderizado recursivo.
Features
- Incrustar cualquier entidad de Drupal (nodos, medios, archivos, usuarios, términos de taxonomía, etc.) dentro del contenido de texto enriquecido usando CKEditor
- Soporte para CKEditor 5 con botones de barra de herramientas dedicados para cada botón de incrustación configurado
- Sistema de múltiples plugins de visualización que permite renderizar entidades usando formateadores de campo o modos de visualización
- Integración con Entity Browser para selección visual de entidades en lugar de autocompletado
- Soporte de alineación (izquierda, centro, derecha) cuando se usa con el filtro filter_align de Drupal
- Soporte de leyendas para entidades incrustadas cuando se usa con el filtro filter_caption de Drupal
- Incrustación consciente de traducciones con seguimiento de código de idioma mediante el atributo data-langcode
- Restricciones de bundle configurables para limitar qué tipos de contenido pueden ser incrustados
- Restricciones de plugins de visualización por botón para controlar las opciones de visualización disponibles
- Capacidad de sobrescribir texto alt y título de imágenes de medios para accesibilidad
- Protección contra renderizado recursivo con límite de profundidad configurable (por defecto 20)
- Extensión Twig que proporciona la función entity_embed() para incrustación programática en plantillas
- API de hooks completa para alterar plugins de visualización, contexto y salida de construcción
- Migración automática del atributo legacy data-view-mode al nuevo formato de plugin de visualización
Use Cases
Incrustar medios en el contenido del cuerpo
Los editores de contenido pueden incrustar entidades de medios (imágenes, videos, documentos) directamente en el campo de cuerpo de los artículos. Hacer clic en el botón de incrustación de entidades en CKEditor, buscar y seleccionar un elemento de medios, elegir un formato de visualización (miniatura, completo, etc.), opcionalmente añadir alineación y leyenda, luego incrustar. El medio se renderiza en línea con el contenido de texto.
Referenciar contenido relacionado en línea
Incrustar referencias a otros nodos dentro del contenido del cuerpo para crear contenido rico e interconectado. Por ejemplo, incrustar un nodo de producto dentro de una publicación de blog con visualización de avance para mostrar detalles del producto en línea sin salir del artículo.
Construir bloques de contenido reutilizables
Crear entidades de contenido de bloque para fragmentos de contenido comunes (llamadas de atención, biografías de autor, banners promocionales) e incrustarlos en múltiples páginas. Los cambios a la entidad de bloque se reflejan automáticamente en todos los lugares donde está incrustada.
Incrustación de entidades personalizadas
Incrustar entidades personalizadas (eventos, ubicaciones, miembros del equipo) creadas por módulos contrib o personalizados. Configurar un botón de incrustación para el tipo de entidad personalizado y seleccionar modos de visualización apropiados para la presentación.
Selección visual de entidades con Entity Browser
Configurar botones de incrustación para usar Entity Browser para una interfaz de selección visual estilo galería en lugar de autocompletado. Útil para sitios con muchos medios donde los editores necesitan navegar y previsualizar contenido antes de la selección.
Incrustación programática en plantillas
Usar la función Twig entity_embed() para incrustar entidades en plantillas sin interacción del editor: {{ entity_embed('node', 123, 'entity_reference:entity_reference_entity_view', {view_mode: 'teaser'}) }}
Tips
- Configure botones de incrustación separados para diferentes tipos de entidades (uno para medios, uno para nodos) para mantener la barra de herramientas organizada y limitar el alcance de selección para los editores
- Use restricciones de bundle en los botones de incrustación para evitar que los editores incrusten tipos de contenido inapropiados (ej., restringir solo a nodos 'Artículo' para un botón de incrustación de blog)
- Habilite el paso de revisión en los ajustes de Entity Browser para permitir que los editores verifiquen su selección antes de configurar las opciones de visualización
- La configuración rendered_entity_mode en entity_embed.settings puede simplificar el desplegable de plugins de visualización mostrando modos de vista en el nivel superior
- Las sobrescrituras de texto alt y título para imágenes de medios usan el valor especial '""' (dos comillas dobles) para establecer texto alt explícitamente vacío, distinguiendo de heredar el texto alt del medio
- Use hook_entity_embed_display_plugins_for_context_alter para filtrar dinámicamente las opciones de visualización disponibles basándose en la entidad específica que se está incrustando
- Las entidades incrustadas se renderizan con la clase CSS 'embedded-entity' para estilizado dirigido
Technical Details
Admin Pages 3
/admin/config/content/embed
Lista todos los botones de incrustación configurados incluyendo botones de incrustación de entidades. Desde aquí puede añadir, editar o eliminar botones de incrustación que aparecen en la barra de herramientas de CKEditor.
/admin/config/content/embed/add
Crear un nuevo botón de incrustación para incrustar entidades en contenido de texto. Este formulario permite configurar el tipo de entidad, restricciones de bundle, plugins de visualización e integración opcional con Entity Browser.
/admin/config/content/formats/manage/{format_id}
Configurar ajustes de formato de texto incluyendo el filtro Entity Embed y la ubicación del botón en CKEditor.
Hooks 7
hook_entity_embed_display_plugins_alter
Alterar las definiciones de plugins Entity Embed Display globalmente. Usar esto para modificar, añadir o eliminar definiciones de plugins de visualización.
hook_entity_embed_display_plugins_for_context_alter
Filtrar plugins Entity Embed Display basándose en el contexto. Usar esto para eliminar plugins que no deberían estar disponibles para entidades o botones de incrustación específicos.
hook_entity_embed_context_alter
Alterar el array de contexto antes de que una entidad incrustada sea renderizada. Permite la modificación de valores de contexto que serán pasados al plugin de visualización.
hook_ENTITY_TYPE_embed_context_alter
Variante específica de tipo de entidad de hook_entity_embed_context_alter. Reemplazar ENTITY_TYPE con el nombre de máquina del tipo de entidad (ej., hook_node_embed_context_alter).
hook_entity_embed_alter
Alterar el render array después de que una entidad incrustada ha sido construida. Esto se llama después de que el plugin de visualización ha generado el array de construcción.
hook_ENTITY_TYPE_embed_alter
Variante específica de tipo de entidad de hook_entity_embed_alter. Reemplazar ENTITY_TYPE con el nombre de máquina del tipo de entidad.
hook_entity_embed_values_alter
Alterar los valores antes de que sean enviados al editor WYSIWYG. Llamado en el envío del formulario de diálogo de incrustación.
Troubleshooting 7
Asegúrese de que el filtro 'Mostrar entidades incrustadas' está habilitado para el formato de texto y que el botón de incrustación ha sido añadido a la barra de herramientas de CKEditor en la configuración del formato de texto.
El filtro entity_embed no está habilitado o no está procesando. Habilite el filtro 'Mostrar entidades incrustadas' para el formato de texto. Verifique el orden de procesamiento de filtros - entity_embed debe ejecutarse después de filter_align, filter_caption y filter_html_image_secure.
Si usa el filtro 'Limitar etiquetas HTML permitidas', asegúrese de que la etiqueta drupal-entity está en la lista blanca con todos los atributos requeridos: data-entity-type, data-entity-uuid, data-entity-embed-display, data-entity-embed-display-settings, data-align, data-caption, data-embed-button, alt, title.
El tipo de entidad puede no tener plugins Entity Embed Display compatibles, o la configuración del botón de incrustación restringe los plugins disponibles. Verifique los ajustes del botón de incrustación y asegúrese de que el tipo de entidad tiene modos de visualización o formateadores de campo compatibles.
Solo están disponibles instancias de Entity Browser con plugins de visualización compatibles. Los navegadores que usan visualizaciones 'modal' o 'standalone' son filtrados. Cree o configure un entity browser con visualización 'iframe' u otra compatible.
El usuario actual puede no tener permiso de visualización para la entidad incrustada, o la entidad ha sido eliminada. Verifique los permisos de la entidad y confirme que la entidad todavía existe.
Una entidad contiene una incrustación de sí misma o crea una cadena de referencia circular. El módulo tiene protección incorporada (límite: 20 recursiones) pero debe revisar el contenido para eliminar incrustaciones circulares.
Security Notes 5
- La incrustación de entidades respeta el sistema de acceso de entidades de Drupal - las entidades solo se renderizan si el usuario actual tiene permiso de visualización
- El filtro maneja automáticamente entidades faltantes o eliminadas de forma elegante, mostrando un marcador de posición en lugar de errores
- El HTML en las leyendas se escapa antes del almacenamiento para prevenir ataques XSS
- Se prefieren los UUIDs de entidad sobre los IDs de entidad para la incrustación para prevenir problemas con staging de contenido y migración
- El módulo valida que las entidades incrustadas existen y son accesibles tanto durante el diálogo del editor como el procesamiento del filtro