Media Scene

Introduction

Media Scene lets content editors transform any section of a page into a visually
engaging scene by placing existing content in front of a background image all
directly from the standard CKEditor 5 editing experience. If you've ever wanted
a landing page, article, or paragraph to look like a hero banner without editing
templates, writing CSS, or asking a developer, Media Scene makes it possible.

Simply select an image from Drupal's built-in Media Library, click a toolbar
button, and your existing content is instantly displayed on top of the image as
a styled background. No custom content types, Twig templates, or CSS are
required.

Features

Media Scene adds three toolbar buttons to CKEditor 5 for any enabled text
format.

• Add Background Image – Opens Drupal's native Media Library,
  allowing editors to select an existing image or upload a new one using the
  familiar media selection interface.
• Background Scene Settings – Configure the appearance of an
  individual background scene with options including:
  • Width and Height – Define the dimensions of the
    background area in pixels.
  • Overlay Tint – Apply a color overlay with adjustable
    opacity to improve text readability.
  • Focal Point – Choose from a 9-position grid to control
    which part of the image remains visible when cropped.
  • Parallax Effect – Enable a fixed background that
    creates a scrolling parallax effect.
• Remove Background Image – Remove the background image and
  restore the content to its normal layout.

Common use cases include:

• Hero sections on landing pages
• Themed content dividers within articles
• Call-to-action banners
• Campaign and event pages

Since the background configuration is stored within the content itself,
editors can create rich layouts without developer assistance. The styling also
travels with the content if it is moved, duplicated, or reused in Paragraphs or
other entities.

Backgrounds always reference the selected Media entity rather than a static
image. If the media item is replaced or the configured image style changes, all
pages using that image automatically display the updated version.

Post-Installation

After enabling the module, choose which text formats should support Media
Scene.

1. Go to
   Configuration → Content authoring → Text formats and editors
   (/admin/config/content/formats) and edit the desired text
   format.
2. In the CKEditor 5 toolbar configuration, move the following buttons from
   Available buttons to the Active toolbar:
   • Add Background Image
   • Background Scene Settings
   • Remove Background Image
3. If the text format uses the
   Limit allowed HTML tags filter, also enable the
   Render Media Scene backgrounds filter. This ensures
   background scenes are rendered correctly when HTML filtering is enabled.
4. Save the text format.

No additional configuration is required to begin using the module.

An optional configuration page is available at
Configuration → Media → Media Scene
(/admin/config/media/media-scene), where administrators can
select an Image Style to optimize all background images. If no Image Style is
selected, the original uploaded image is used.

Editors only require Drupal's standard
Access Media Library permission. The optional configuration
page is protected by the
Administer Media Scene permission.

Additional Requirements

Media Scene depends only on Drupal core modules:

• Media
• Media Library
• CKEditor 5
• Editor

No external JavaScript libraries, third-party services, or API keys are
required.

If your text format restricts HTML tags, ensure the
Render Media Scene backgrounds filter is enabled alongside the
toolbar buttons, otherwise background scenes will not display.

Recommended Modules

• Image Styles (Drupal core) – Create an optimized image
  style for large background images to reduce bandwidth and improve page
  performance.
• Focal Point –
  Ideal for sites that already manage image focal points. Media Scene also
  includes its own lightweight 9-position focal point selector, making this
  module optional.

Similar Projects

Several Drupal modules provide related functionality, but each approaches the
problem differently.

• Background Image
  and
  CKEditor Background Image
  allow background images through direct uploads rather than Drupal's Media
  Library, so images are not reusable Media entities and do not benefit from
  Media Library features such as image styles and usage tracking.
• Background Image Field
  works by rendering a dedicated field as a background image instead of
  allowing editors to apply backgrounds directly from CKEditor.
• Parallax Background
  focuses solely on adding parallax scrolling effects and does not provide
  integrated image selection, overlays, sizing, or focal point controls.

Media Scene uniquely combines:

• Drupal Media Library integration
• Background sizing controls
• Overlay color and opacity
• 9-position focal point selection
• Optional parallax scrolling
• Direct CKEditor 5 integration

All of this works without creating new fields, modifying templates, or writing
custom CSS.

Supporting This Module

There is currently no dedicated funding page for this project. Contributions
through the Drupal issue queue are always welcome, including bug reports,
feature requests, documentation improvements, and code patches.

Community Documentation

The project's README provides detailed documentation covering installation,
configuration, permissions, architecture, and usage beyond what is included on
the project page.

If you create tutorials, walkthroughs, or demo videos for Media Scene, feel
free to share them in the issue queue so they can be referenced by the project.

Media Scene is actively maintained and tested with
Drupal 11. It requires no dependencies beyond Drupal core and
provides a simple, editor-friendly way to create visually rich background
sections directly from CKEditor 5.