Embedded Content
Provides a CKEditor 5 plugin system that allows editors to insert styled, configurable components into rich text content without requiring HTML permissions.
embedded_content
Install
composer require 'drupal/embedded_content:^2.0'
Overview
Embedded Content is a powerful module that bridges the gap between content editors and developers by providing a flexible system for embedding custom components within CKEditor 5. Editors can insert pre-configured styled components through intuitive toolbar buttons, while developers have full control over what components are available and how they render.
The module uses a plugin architecture where developers create EmbeddedContent plugins that define configuration forms and rendering logic. These plugins are then made available through configurable toolbar buttons that can be added to any CKEditor 5 text format. When content is saved, the module stores component data as custom HTML elements (<embedded-content>) which are processed by a text filter to render the final output.
Key benefits include: editors don't need 'Full HTML' permissions to use styled components, developers can create complex interactive elements, and the CKEditor 5 integration provides immediate visual preview of embedded content while editing.
Features
- CKEditor 5 integration with custom toolbar buttons for embedding styled components
- Plugin system for developers to create custom embedded content types with configurable forms and rendering logic
- Text filter that processes <embedded-content> and <embedded-content-inline> tags into rendered HTML
- Admin UI for managing embedded content buttons with custom icons, labels, and dialog settings
- Support for both block-level and inline embedded content
- Configurable dialog/modal settings including width, height, and renderer type (modal or off-canvas)
- SVG icon customization for toolbar buttons
- Plugin filtering using wildcard patterns and regex conditions
- Dynamic permission generation for each configured button
- Live preview of embedded content within the CKEditor 5 editor
- Edit functionality for existing embedded content through widget toolbar
Use Cases
Callout boxes and alerts
Create an EmbeddedContent plugin that allows editors to insert styled callout boxes (info, warning, success, error) with custom text. Editors select the type and enter content, and the module renders a consistently styled alert box without needing CSS class permissions.
Social media embeds
Build plugins that let editors paste a social media URL and have it rendered as an embedded post. The configuration form validates the URL, and the build method outputs the appropriate embed code with proper styling.
Data visualization widgets
Create plugins for charts, tables, or other data visualizations. Editors configure the data through a form, and the plugin renders interactive charts using a JavaScript library, all without direct HTML access.
Product or content references
Build plugins that allow editors to search for and embed product cards, article teasers, or other entity references with custom display options, providing a more guided experience than raw entity embed.
Interactive components
Develop plugins for accordions, tabs, or other interactive UI components. Editors configure the sections through the form, and the module outputs proper HTML structure with associated JavaScript behaviors.
Code snippets with syntax highlighting
Create a plugin that provides a code editor in the configuration form, allowing editors to paste code and select the language. The build method outputs syntax-highlighted code blocks using a library like Prism or Highlight.js.
Tips
- Create separate buttons for different content types or user roles to control which plugins are available to different editors
- Use the off-canvas dialog renderer for a less intrusive editing experience, especially for simpler plugins
- Plugin conditions support regex patterns for complex matching scenarios beyond simple wildcards
- Implement the isInline() method in your plugin to return true for inline elements that should flow within text
- Use the getAttachments() method in plugins to attach CSS/JS libraries needed for frontend rendering
- The massageFormValues() method allows you to transform form values before they're stored, useful for cleanup or normalization
- Consider caching implications in your plugin's build() method, especially for plugins that render dynamic or user-specific content
Technical Details
Admin Pages 5
/admin/config/content/embedded-content
Main administration page for the Embedded Content module. Provides access to button configuration.
/admin/config/content/embedded-content/button
Lists all configured embedded content buttons. Each button represents a toolbar item that editors can use to insert embedded content. The list shows the button label, machine name, and status.
/admin/config/content/embedded-content/button/add
Form to create a new embedded content button that will appear in the CKEditor 5 toolbar. Configure the button's appearance, behavior, and which plugins it can access.
/admin/config/content/embedded-content/button/{embedded_content_button}
Edit an existing embedded content button configuration. Same form fields as the add form, with an additional icon preview section.
/admin/config/content/embedded-content/button/{embedded_content_button}/delete
Confirmation form to delete an embedded content button. This will remove the toolbar button from all text formats using it.
Permissions 2
Hooks 1
hook_embedded_content_info_alter
Allows modules to alter the embedded content plugin definitions discovered by the plugin manager.
Troubleshooting 5
Ensure you have enabled a module that provides EmbeddedContent plugins. The core module does not include any plugins by default. You can enable the embedded_content_test module for examples, or create your own plugins in a custom module.
Make sure: 1) The embedded content button is configured at /admin/config/content/embedded-content/button, 2) The button is dragged to the toolbar in the text format configuration, 3) The 'Embedded Content' filter is enabled for that text format, 4) The user has permission to use that specific button.
Check the 'Plugin conditions' field in the button configuration. If patterns are specified, your plugin ID must match one of them. Leave the field empty to show all available plugins.
The embedded content may reference a plugin that no longer exists or has been disabled. Delete the embedded content and re-insert it with a valid plugin.
Ensure the 'Embedded Content' text filter is enabled and ordered correctly in the text format. It should run after filters that might interfere with the custom HTML tags but before those that sanitize output.
Security Notes 3
- Embedded content plugins should validate and sanitize all configuration values in the build() method to prevent XSS attacks
- The module stores plugin configuration as JSON in data attributes; plugins should never trust this data without validation
- Only users with the specific button permission can use that toolbar button, providing granular access control