URL Embed
Allows URLs to be embedded using a text editor (CKEditor5) or link fields, supporting oEmbed-compatible services like YouTube, Flickr, Instagram, and Facebook.
url_embed
Install
composer require 'drupal/url_embed:^3.0'
Overview
URL Embed module provides a comprehensive solution for embedding external URLs into Drupal content. It leverages the powerful oscarotero/Embed PHP library to fetch oEmbed data from hundreds of supported providers including YouTube, Vimeo, Flickr, Twitter, Instagram, Facebook, and many more.
The module integrates seamlessly with CKEditor5, adding a toolbar button that opens a dialog where users can paste URLs to embed. When the content is displayed, the module's text filter transforms the <drupal-url> placeholder tags into rich embedded content like video players, image galleries, or social media posts.
Additionally, URL Embed provides a field formatter for Link fields, allowing embedded content to be displayed anywhere link fields are used without requiring a WYSIWYG editor. The module also supports responsive embeds that automatically scale to fit their container while maintaining the correct aspect ratio.
Features
- CKEditor5 integration with toolbar button for embedding URLs in WYSIWYG content
- Display embedded URLs text filter that transforms <drupal-url> tags into rich embedded content
- Convert URLs to URL embeds text filter that automatically detects and converts plain URLs to embed elements
- Field formatter for Link fields to display URLs as embedded content
- Responsive embed support with CSS-based aspect ratio preservation
- Facebook and Instagram embedding support via Facebook App credentials configuration
- Extensible architecture allowing other modules to alter embed options via hook_url_embed_options_alter
- Support for hundreds of oEmbed providers through the oscarotero/Embed library
Use Cases
Embedding YouTube Videos in Content
Content editors can easily embed YouTube videos by clicking the URL Embed button in CKEditor5, pasting a YouTube URL, and clicking Embed. The video player will be rendered inline in the content with proper responsive scaling.
Displaying Social Media Posts
Embed Twitter/X posts, Instagram photos, or Facebook content directly in articles. For Instagram and Facebook, configure the Facebook App credentials first in the module settings.
Link Field as Embedded Content
Use the 'Embedded URL' field formatter on Link fields to display URLs as embedded content. For example, a 'Featured Video' link field can automatically display as a video player instead of a plain link.
Auto-converting URLs in User Content
Enable the 'Convert URLs to URL embeds' filter to automatically convert plain URLs in user-submitted content to embedded media. Optionally use a prefix like 'EMBED-' to control which URLs get converted.
Responsive Media Galleries
Enable responsive embedding to ensure all embedded media scales properly on mobile devices and different screen sizes while maintaining correct aspect ratios.
Tips
- Place the 'Display embedded URLs' filter after 'Limit allowed HTML tags' in the filter processing order to prevent the embed markup from being stripped.
- Use the 'Convert URLs to URL embeds' filter with a URL prefix like 'EMBED-' to give content editors control over which URLs become embeds.
- The default aspect ratio setting (66.7%) approximates a 3:2 ratio. Use 56.25% for 16:9 video content.
- Test embed URLs before publishing by using the CKEditor5 preview functionality or viewing in draft mode.
- For high-traffic sites, consider caching strategies for embedded content as each page view may fetch fresh oEmbed data.
Technical Details
Admin Pages 1
/admin/config/media/url_embed
Configuration page for the URL Embed module. Primarily used to configure Facebook App credentials required for embedding Facebook and Instagram content since October 2020.
Permissions 1
Hooks 1
hook_url_embed_options_alter
Allows modules to alter the URL or options passed to the embed request before it is sent to the oEmbed provider. Useful for customizing embed behavior per-provider.
Troubleshooting 5
Facebook and Instagram require a Facebook App with oEmbed product enabled since October 2020. Create an app at developers.facebook.com, enable the oEmbed product, and enter your App ID and App Secret at /admin/config/media/url_embed. The app must be in 'Live' mode.
Ensure you have added the 'urlembed' button to your text format's toolbar configuration at /admin/config/content/formats. Also verify the 'Display embedded URLs' filter is enabled for that text format.
Not all URLs support oEmbed. The URL must be from a provider supported by the oscarotero/Embed library. Check the browser console and Drupal logs for specific error messages.
Enable the 'Embeds fill container (responsive behavior)' option in the text filter settings or field formatter settings. Also ensure the url_embed/responsive_styles library CSS is loading.
If using 'Limit allowed HTML tags' filter, ensure <drupal-url data-embed-url data-url-provider> is in the allowed tags list. The Display embedded URLs filter should run after the HTML restriction filter.
Security Notes 3
- Facebook App Secret is stored in plain text in Drupal configuration. Restrict access to the configuration export and admin pages.
- Embedded content is rendered using the raw HTML from oEmbed providers. This is generally safe as oEmbed providers are trusted, but be aware that external scripts may be loaded.
- The 'administer url_embed' permission should only be granted to trusted administrators as it allows configuring API credentials.