Embed
Provides a framework for different types of embeds in text editors, including an API for creating embed type plugins and a UI for managing embed buttons.
embed
Install
composer require 'drupal/embed:8.x-1.10'
composer require 'drupal/embed:8.x-1.9'
Overview
The Embed module provides a foundation framework for embedding various types of content within WYSIWYG text editors like CKEditor 4 and CKEditor 5. It serves as a base API that other modules can extend to provide specific embed functionality.
The module introduces the concept of "Embed Buttons" which appear in the text editor toolbar and allow content editors to insert embedded content. Each button is associated with an "Embed Type" plugin that defines what kind of content can be embedded and how it is configured.
Key capabilities include:
- A plugin system for defining custom embed types
- Configuration entity for managing embed buttons
- Full CKEditor 4 and CKEditor 5 integration
- CSRF-protected preview system for embedded content
- Icon management with SVG support for CKEditor 5 compatibility
- DOM manipulation utilities for filter implementations
This module is typically used in conjunction with modules like Entity Embed or Media Embed that provide specific embed type implementations.
Features
- Plugin-based architecture for defining custom embed types that can embed different kinds of content
- Configuration entity system for creating and managing embed buttons with custom labels and icons
- Full integration with both CKEditor 4 and CKEditor 5 text editors through dedicated plugin bases
- CSRF-protected preview endpoint that renders embedded content using the appropriate filter format
- Icon management system supporting custom icons stored as base64-encoded data, with SVG requirement for CKEditor 5 compatibility
- DOM helper utilities (DomHelperTrait) for manipulating DOM elements in filter plugins
- Access control system that validates embed button availability in editor configurations
- AJAX command system for inserting embedded content into editor instances
- Automatic CKEditor 5 plugin derivation from embed button configurations
Use Cases
Creating an Entity Embed Button
Install Entity Embed module which provides the 'entity' embed type. Navigate to Admin > Config > Content authoring > Embed buttons. Click 'Add embed button', enter a label like 'Node', select 'Entity' as the embed type, configure which entity types and bundles can be embedded, upload an SVG icon, and save. Then edit your text format to add the button to the CKEditor 5 toolbar and enable the required filter.
Developing a Custom Embed Type
Create a custom embed type by implementing a plugin in your module's src/Plugin/EmbedType directory. Extend EmbedTypeBase and add the @EmbedType annotation with id and label. Implement getDefaultIconUrl() to provide a default button icon. Optionally override buildConfigurationForm(), validateConfigurationForm(), and submitConfigurationForm() to add button-specific settings. For CKEditor 5 integration, create a CKEditor 5 plugin extending EmbedCKEditor5PluginBase.
Previewing Embedded Content
The module provides a preview endpoint at /embed/preview/{filter_format} that renders embedded content. CKEditor plugins use this endpoint with CSRF protection to show live previews of embedded items while editing. The preview uses the same filter processing as the final rendered content.
Tips
- Always use SVG icons for embed buttons to ensure CKEditor 5 compatibility
- The Embed module is a framework - install Entity Embed or similar modules for actual embedding functionality
- When developing custom embed types, extend EmbedTypeBase for sensible defaults
- Use the DomHelperTrait utility methods when implementing filter plugins that process embedded content
- Embed buttons are config entities and can be exported/imported with configuration management
- The module validates that required filters are enabled when buttons are added to editor toolbars
Technical Details
Admin Pages 4
/admin/config/content/embed
Lists all configured embed buttons showing their label, embed type, and icon. Provides operations to edit and delete each button. This is the main management interface for embed buttons.
/admin/config/content/embed/button/add
Form for creating a new embed button. Allows setting the button label, machine name, embed type, type-specific settings, and custom icon.
/admin/config/content/embed/button/manage/{embed_button}
Form for editing an existing embed button. The machine name and embed type cannot be changed after creation.
/admin/config/content/embed/settings
Global configuration settings for the Embed module, controlling where uploaded button icons are stored.
Permissions 1
Hooks 1
hook_embed_type_plugins_alter
Allows modules to alter embed type plugin definitions after they are discovered. Can be used to modify labels, add settings, or change plugin behavior.
Troubleshooting 4
Ensure the button uses an SVG icon (required for CKEditor 5). Check the Status Report page for CKEditor 5 compatibility warnings. Edit the button and upload an SVG icon file.
Install a module that provides embed type plugins, such as Entity Embed or Media Embed. The Embed module is a framework and requires embed type plugins to function.
Verify that the CSRF token is being sent with preview requests. For authenticated users, the X-Drupal-EmbedPreview-CSRF-Token header must contain a valid token. Also check that the user has permission to use the filter format.
Button icons are stored as base64-encoded data but reference a URI. If the file doesn't exist at the URI, it will be recreated from the encoded data automatically. Clear caches if icons don't appear.
Security Notes 4
- The preview endpoint uses CSRF protection to prevent unauthorized content rendering. For anonymous users, presence of the custom header is sufficient; for authenticated users, the token value is validated.
- Access to embed button administration requires the 'administer embed buttons' permission
- Preview access is controlled by filter format usage permissions - users can only preview content using formats they have permission to use
- The module validates that embed buttons in editor toolbars have their required filters enabled to prevent configuration mismatches