CKEditor Media Embed Plugin
Adds the CKEditor 5 Media Embed plugin to Drupal, enabling content authors to embed media from external providers like YouTube, Vimeo, Twitter, and over 1700 other content sources.
ckeditor_media_embed
Install
composer require 'drupal/ckeditor_media_embed:^2.0'
composer require 'drupal/ckeditor_media_embed:8.x-1.14'
Overview
The CKEditor Media Embed module integrates the CKEditor 5 Media Embed plugin with Drupal's CKEditor implementation, allowing content authors to embed rich media content from external providers directly into their content using the WYSIWYG editor.
The module uses oEmbed protocol to fetch embed codes from configurable providers. By default, it uses the Iframely proxy service which supports over 1715 content providers including YouTube, Vimeo, Twitter, Instagram, Imgur, GitHub, Google Maps, and many more. Alternative providers like Noembed or embed.ly can also be configured.
The module stores <oembed> tags in the database rather than the full embed HTML, and uses a text filter to transform these tags into actual embed HTML during rendering. This approach ensures better portability and allows the embed code to stay current even if providers update their embed format.
Additionally, the module provides a field formatter that allows Link fields to be rendered as oEmbed media embeds, enabling media embedding outside of text fields.
Features
- CKEditor 5 Media Embed toolbar button for inserting media from URLs
- Support for 1700+ content providers through configurable oEmbed proxy services (Iframely, Noembed, embed.ly, etc.)
- Text filter that converts <oembed> tags to embedded media HTML on render
- Link field formatter to display Link fields as embedded media using the configured oEmbed provider
- Drush commands for installing and updating required CKEditor plugin files
- Automatic accessibility enhancement by adding title attributes to embedded iframes
- Configurable provider URL with {url} and {callback} token substitution
- Version tracking and status reporting for installed CKEditor plugins
Use Cases
Embedding YouTube videos in content
Content editors can paste a YouTube URL in the CKEditor and use the Media Embed button to convert it into an embedded video player. The video will be displayed directly in the content without requiring users to leave the site.
Embedding social media posts
Twitter tweets, Instagram posts, and other social media content can be embedded by pasting their URLs and using the Media Embed feature. This allows rich social content integration while maintaining the original formatting and interactivity.
Creating a video gallery with Link fields
Create a content type with a multi-value Link field and use the 'Oembed element using CKEditor Media Embed provider' formatter. This allows creating structured video galleries where each link is automatically rendered as an embedded video player.
Embedding code snippets from GitHub Gists
Developers can embed GitHub Gists by pasting the Gist URL and using Media Embed. The code snippet will be displayed with proper syntax highlighting directly in the content.
Embedding interactive maps
Google Maps and other map service URLs can be embedded to show interactive maps within content, useful for location-based content, event pages, or contact information.
Tips
- Use a proxy service like Iframely or Noembed rather than direct provider URLs to support the widest range of media sources with a single configuration.
- Always enable the 'Convert Oembed tags to media embeds' filter on any text format that uses the Media Embed button, otherwise embeds will not render.
- The module stores <oembed> tags rather than HTML, so if you change providers or provider configurations, existing embeds will automatically use the new settings.
- For custom theming of embeds, implement hook_ckeditor_media_embed_object_alter() to modify the embed HTML wrapper or add custom classes.
- After upgrading Drupal core, run 'drush ckeditor_media_embed:update' to ensure plugin compatibility with the new CKEditor version.
- You can override the CKEditor version used for downloading plugins by setting the ckeditor_version configuration value using 'drush config-edit ckeditor_media_embed.settings'.
Technical Details
Admin Pages 1
/admin/config/media/ckeditor-media-embed/settings
Configure the oEmbed provider URL used by the CKEditor Media Embed plugin to fetch embed codes for media resources.
Hooks 1
hook_ckeditor_media_embed_object_alter
Allows modules to alter the oEmbed object before it is rendered. The module itself implements this hook to add title attributes to iframes for accessibility.
Drush Commands 2
drush ckeditor_media_embed:install
Downloads and installs the required CKEditor Media Embed plugin files from the NPM registry to the libraries directory.
drush ckeditor_media_embed:update
Updates the CKEditor Media Embed plugin files to match the version of CKEditor installed with Drupal core.
Troubleshooting 5
Ensure the CKEditor plugins are installed by running 'drush ckeditor_media_embed:install'. Check the status report at /admin/reports/status for any missing plugin errors.
Enable the 'Convert Oembed tags to media embeds' filter on the text format being used. Go to Administration > Configuration > Content authoring > Text formats and editors, edit the format, and check the filter checkbox.
The installed plugins have a different version than CKEditor core. Run 'drush ckeditor_media_embed:update' to update the plugins to match the core CKEditor version.
The configured oEmbed provider may not support that content source. Consider switching to a provider like Iframely that supports more content providers, or check the provider's documentation for supported sources.
The default Iframely endpoint uses HTTP. For HTTPS support, create an Iframely account and update the provider URL in the module settings to use your API key with HTTPS.
Security Notes 3
- Embedded content is rendered from third-party sources, so ensure you trust the configured oEmbed provider.
- The module adds title attributes to embedded iframes for accessibility compliance.
- Consider the security implications of allowing untrusted users to embed external content, as this could potentially be used for phishing or malicious content.