Paragraphs Entity Embed
Allows paragraph entities to be embedded directly into CKEditor WYSIWYG editor fields.
paragraphs_entity_embed
Install
composer require 'drupal/paragraphs_entity_embed:^3.0'
Overview
Paragraphs Entity Embed bridges the gap between the Paragraphs module and CKEditor, enabling content editors to insert rich, structured paragraph content directly within text editor fields. This module creates a seamless workflow where users can either create new paragraph items or reuse existing ones within their WYSIWYG content.
The module provides a custom entity type called 'Embedded Paragraphs' that acts as a container for paragraph references. When a user clicks the Paragraphs button in CKEditor, a modal dialog opens where they can either create a new paragraph or select an existing embedded paragraph via autocomplete. The embedded paragraphs are then rendered inline within the text content using a special 'embed' view mode.
This approach is particularly useful for sites that want to maintain consistent, reusable content components while giving editors the flexibility to place them anywhere within their body text, not just in dedicated paragraph fields.
Features
- CKEditor integration with a dedicated toolbar button for inserting paragraphs into WYSIWYG content
- Modal dialog interface for creating new paragraphs or selecting existing embedded paragraphs
- Autocomplete functionality for quickly finding and reusing previously created embedded paragraphs
- Custom 'Embedded Paragraphs' entity type that stores paragraph references with labels for easy identification
- Filter plugin that processes and renders embedded paragraphs when content is displayed
- Paragraph type filtering to restrict which paragraph types can be embedded via specific embed buttons
- Double-click editing support for quickly modifying embedded paragraphs in CKEditor
- Context menu integration in CKEditor for editing embedded paragraphs
- Dedicated 'embed' view mode for paragraphs to control how they appear when embedded
- Field widget extending the standard Paragraphs widget for managing embedded paragraph references
Use Cases
Embedding call-to-action blocks within article text
Content editors can create reusable call-to-action paragraph components (with buttons, images, and styled text) and insert them at any point within their article body text, not just at the top or bottom of the content.
Inserting product highlights in blog posts
E-commerce sites can define product teaser paragraphs and allow blog authors to embed product highlights directly within their post content, creating a seamless reading experience.
Reusing testimonial quotes across multiple pages
Create testimonial paragraphs once and embed them in multiple content pieces. The autocomplete feature makes it easy to find and reuse existing testimonials without recreating them.
Adding interactive elements to long-form content
For sites with complex paragraph types like accordions, tabs, or media galleries, editors can embed these interactive elements anywhere within their text content rather than being limited to fixed field positions.
Tips
- Create a dedicated 'Embed' view mode for each paragraph type with appropriate field visibility and formatting for inline display within text content
- Use descriptive labels when creating embedded paragraphs so they are easy to find via the autocomplete when reusing them
- Consider creating a content editor role with appropriate paragraph embed permissions to control who can create and manage embedded paragraphs
- Test embedded paragraph rendering in both the default view mode and embed view mode to ensure consistent styling
Technical Details
Admin Pages 2
/admin/config/content/embed
Manage embed buttons including the Paragraphs embed button. The Paragraphs button is created automatically on module installation and can be configured here.
/admin/structure/paragraphs_entity_embed/{paragraphs_type}
Administrative interface for editing embedded paragraph entities directly.
Permissions 5
Hooks 2
hook_entity_type_build
Adds a custom form class to the embedded_paragraphs entity type for handling the CKEditor dialog form
hook_preprocess_html
Hides page elements (toolbar, footer, sidebars) when displaying the paragraph embed form in an iframe within CKEditor dialog
Troubleshooting 4
Ensure the Paragraphs button has been added to the toolbar configuration for your text format. Go to Configuration > Text formats and editors, edit your format, and drag the Paragraphs button to the active toolbar.
Enable the 'Display embedded paragraphs' filter for your text format. Also verify that the filter order is correct - entity embed filters should typically run after HTML correction.
Check that you have created paragraph types and that the embed button is not configured to filter paragraph types to an empty selection.
Configure the 'Embed' view mode for your paragraph types at Structure > Paragraphs types > [type] > Manage display. Select the 'Embed' view mode and configure which fields should display.
Security Notes 3
- The 'administer paragraphs entity embed' permission is marked as restricted and should only be granted to trusted administrators
- Users need both text format access and appropriate paragraph embed permissions to insert embedded paragraphs
- Embedded paragraph content is subject to the same access controls as the parent content type