Mercury Editor
mercury_editor
Replaces the standard Drupal edit screen with an enhanced drag-and-drop editor interface for content creation and layout management.
Overview
Mercury Editor is a comprehensive content editing solution that transforms Drupal's default content editing experience into a modern, intuitive drag-and-drop interface. It provides a split-screen editing environment where content editors can see a live preview of their changes while editing in a sidebar panel.
Built on top of Layout Paragraphs, Mercury Editor enables visual page building with components that can be inserted, edited, reordered, and deleted using simple drag-and-drop interactions. The module features a sophisticated dialog system for component editing, mobile preview capabilities, and seamless integration with Drupal's content translation and moderation workflows.
The editor interface includes a toolbar with desktop/mobile preview toggle, save and done buttons, and a collapsible sidebar containing the entity form. Components can be organized into custom groups in the component menu, and the editing experience can be customized per content type and entity bundle.
Install
composer require 'drupal/mercury_editor:^2.2'
Features
- Drag-and-drop visual page editor with live preview in an iframe
- Split-screen editing interface with form sidebar and content preview
- Mobile preview with configurable device presets (iPhone 12 Pro, iPhone XR, Pixel 5)
- Component-based content creation using Layout Paragraphs integration
- Customizable component menu with grouping and filtering capabilities
- Mercury Dialog system for component editing with resizable dialogs
- Support for nodes and taxonomy terms as editable entity types
- Content translation support with language-aware editing
- Content moderation integration for editorial workflows
- Configurable skip form feature to bypass creation forms for specific paragraph types
- Theme negotiation for consistent admin theme usage in edit screens
- Tempstore-based editing to prevent data loss before saving
- Section templates submodule for saving and reusing layout sections
Use Cases
Visual Page Building
Content editors can build complex page layouts by dragging and dropping paragraph components into the content area. The split-screen interface shows the edit form on the right and a live preview on the left, allowing editors to see their changes in real-time without switching between edit and view modes.
Mobile-First Content Review
Before publishing, editors can use the mobile preview feature to check how content appears on different device sizes. Select from preset mobile dimensions (iPhone 12 Pro, iPhone XR, Pixel 5) or configure custom presets to match your target devices.
Reusable Section Templates
With the Templates submodule enabled, editors can save frequently used layout sections as templates. For example, a 'Hero with CTA' section or a 'Three Column Features' layout can be saved once and reused across multiple pages, ensuring consistency and speeding up content creation.
Component Organization
Site builders can organize paragraph types into logical groups using the Menu Settings. This helps editors find the right component quickly when building pages. Groups might include 'Content', 'Media', 'Layout', 'Call to Action' etc.
Streamlined Simple Component Creation
For simple components that don't require initial configuration (like a spacer or divider), use the Skip Form Settings to allow immediate insertion without showing a form. This speeds up the editing workflow for commonly used simple components.
Multilingual Content Editing
Mercury Editor integrates with Drupal's content translation system, allowing editors to create and edit content in multiple languages while maintaining the same visual editing experience. The preview respects the current language context.
Tips
- Configure mobile presets to match your target audience's most common devices for accurate mobile preview testing
- Use the Skip Form Settings for simple components like spacers, dividers, or containers that don't need initial configuration
- Organize components into logical groups in Menu Settings to help editors find the right component quickly
- The dialog tray width setting affects the edit sidebar - adjust it based on your form complexity and screen requirements
- When using Content Moderation, Mercury Editor integrates seamlessly - the moderation state selector appears in the edit form
- For best performance, keep the number of components on a page reasonable - very complex pages with many nested components may impact editor responsiveness
- The Templates submodule is particularly useful for marketing teams who need to maintain consistent page sections across the site
Dependencies
Related Projects
Core dependency. Mercury Editor builds on Layout Paragraphs for drag-and-drop component management and provides enhanced UI and routes.
Core dependency. Provides styling options for components within the Mercury Editor interface.
Full integration with Drupal's content moderation system for editorial workflows. Custom form alter and entity prepare hooks ensure moderation states work correctly.
Supports multilingual content editing with language-aware routing and hreflang link generation.
Modal selection integration for browsing and selecting entities within Mercury Editor dialogs.
Special handling for Gin admin theme and Gin Toolbar to ensure proper styling in Mercury Editor context.
When available, provides syntax highlighting for YAML configuration fields in settings forms.
Library integration for image-based radio button styling in component forms.
Admin Pages
| Title | Path | Description |
|---|---|---|
| Mercury Editor Settings | /admin/config/content/mercury-editor |
Main configuration page for Mercury Editor. Configure which entity bundles use the Mercury Editor interface, set the edit tray theme, and define mobile preview presets. |
| Skip Form Settings | /admin/config/content/mercury-editor/skip-form |
Configure which paragraph types should skip the content creation form when inserting new components. When a paragraph type is selected here, clicking to insert it will immediately create the component without showing a form. |
| Menu Settings | /admin/config/content/mercury-editor/menu |
Configure how components are organized and displayed in the 'Add Component' menu. Define custom groups and assign paragraph types to each group using YAML format. |
| Dialog Settings | /admin/config/content/mercury-editor/dialog |
Configure the appearance and behavior of modal dialogs used for component editing. Settings are defined in YAML format with support for per-dialog type customization. |
| Mercury Editor Template Settings | /admin/structure/me-template |
Configure settings for the Mercury Editor Templates entity type. Access requires the 'administer mercury editor template' permission. |
| Mercury Editor Templates | /admin/content/me-template |
View and manage saved section templates. Templates allow editors to save and reuse layout sections across different content. |
Permissions
| Permission | Description |
|---|---|
|
Required to access Mercury Editor settings forms |
|
Access template settings and configuration (restricted) |
|
View the list of available templates (restricted) |
|
Save new section templates from the editor |
|
Modify existing templates |
|
Remove saved templates |
|
View template content |
|
Insert templates when editing content in Mercury Editor |
Hooks
| Hook | Description |
|---|---|
hook_library_info_alter |
Attaches Mercury Editor dialog libraries to core and contrib libraries that need dialog functionality. |
hook_ajax_render_alter |
Replaces Drupal's standard openDialog and closeDialog AJAX commands with Mercury Editor equivalents on mercury_editor routes. |
hook_preprocess |
Sets CSS classes for Mercury Editor edit mode and handles contextual links on preview routes. |
hook_preprocess_layout_paragraphs_builder_controls |
Modifies component controls in Layout Paragraphs builder to use Mercury Editor routes and dialog settings. |
hook_preprocess_html |
Removes admin toolbar and related classes from Mercury Editor edit screens for a cleaner editing interface. |
hook_theme_suggestions_page_alter |
Adds page__mercury_editor theme suggestion for Mercury Editor routes. |
hook_entity_type_build |
Registers Mercury Editor form classes for supported entity types (nodes, taxonomy terms). |
hook_entity_display_build_alter |
Activates Layout Paragraphs builder for entity reference revisions fields when in Mercury Editor preview or editor mode. |
hook_block_alter |
Swaps Field Block class with Mercury Editor version to detect preview mode for paragraph fields. |
hook_form_layout_paragraphs_component_form_alter |
Adds tabbed interface and styling to component edit forms with Content and Styles tabs. |
Troubleshooting
Navigate to /admin/config/content/mercury-editor and ensure the content type's checkbox is selected under 'Bundles'. Also verify the content type has at least one Layout Paragraphs field configured.
Check that paragraph types are properly configured and have the necessary fields. Verify the Menu Settings if using custom groups - orphaned paragraph types should appear in the default group.
Ensure JavaScript is working correctly and no console errors are present. The sync-changes functionality requires proper data-sync-changes attributes on fields. Clear Drupal cache and browser cache.
Review the Dialog Settings at /admin/config/content/mercury-editor/dialog. Adjust width, height, and resizable settings. The default 'fit-content' should work for most cases.
Mercury Editor should automatically hide the toolbar. If using custom toolbar modules, check that mercury_editor_preprocess_html is properly removing toolbar classes. Check for CSS conflicts.
Disable all Mercury Editor submodules before upgrading. Note settings before upgrade, then restore them manually after. Run: drush pmu mercury_editor_components mercury_editor_layouts mercury_editor_content_moderation mercury_editor_scaffold mercury_editor_dialog mercury_editor_skip_form mercury_editor_edit_tray mercury_editor_style_options mercury_editor_iframe mercury_editor_tabs mercury_editor_inline_editor
Security Notes
- Mercury Editor respects Drupal's permission system - users need appropriate entity access permissions to edit content
- Template creation requires the 'create mercury editor template' permission - restrict this to trusted editors
- The tempstore stores unsaved changes privately per user session to prevent data leaks between users