Medialite: Custom Media Library Opener (Architecture & Implementation Plan)

1. Context

This document summarizes the architectural decisions and implementation steps for adding a **custom Media Library opener** to the medialite module.

The medialite module is our custom, stripped‑down clone of Drupal’s Media Library. It provides the widget “Media Lite (restricted)” and implements a simplified media selection workflow.

The goal is to extend medialite with a custom opener that replaces the default Media Library modal workflow with an **upload‑only**, **no‑browsing**,

- auto‑close** behaviour.

2. What is a Media Library opener?

A Media Library opener is a Drupal plugin that controls the behaviour of the Media Library modal. It determines:

what appears inside the modal
whether the grid of existing media is shown
whether browsing is allowed
whether the “Insert” step is required
how uploaded media is returned to the widget
whether the modal auto‑closes

In Drupal 11, the modal is no longer a View. It is controlled entirely by the opener system.

3. Why we need an opener

The default Drupal 11 Media Library workflow requires two steps:

Upload + Save
Select + Insert

This forces the user to browse the grid and click twice before returning to the form.

Our requirement:

upload‑only
no grid
no browsing
no “Insert” step
auto‑close
immediate thumbnail in the form

This behaviour cannot be achieved by:

the widget
permissions
Views (removed in Drupal 11)
configuration
theming

Only a custom opener can implement this workflow.

4. Where the opener belongs

The opener must be implemented **inside the medialite module**, because:

medialite provides the custom widget
the widget will call the opener
the opener will return the uploaded media to the widget
both pieces belong to the same feature
Drupal discovers opener plugins inside custom modules
Drupal does NOT discover plugins inside cloned core modules unless they are

 treated as custom modules (which medialite now is)

Therefore, the opener is added under:

modules/custom/medialite/src/Plugin/media_library/opener/

5. Target workflow

The opener will implement the following behaviour:

User clicks “Add image” in the Medialite widget.
Modal opens showing **only the upload form** (no grid, no list).
User uploads a file.
Media entity is created.
Opener automatically:

  * selects the uploaded media  
  * returns it to the widget  
  * closes the modal

Widget receives the media ID and displays the thumbnail.

This eliminates:

browsing
grid view
“Insert” button
second click

6. Implementation steps

Step 1: Create the plugin directory

Inside medialite:

modules/custom/medialite/src/Plugin/media_library/opener/

Step 2: Create the opener class

A new PHP class implementing:

Drupal\media_library\MediaLibraryOpenerInterface

This class will:

override the modal content
hide the grid
show only the upload form
auto‑select the uploaded media
return it to the widget
close the modal

Step 3: Register the opener

Add the plugin annotation so Drupal discovers it.

Step 4: Modify the Medialite widget

The widget will specify:

“Use the Medialite opener instead of the default one.”

Step 5: Test the round‑trip

Verify:

modal opens with upload‑only
upload creates media
modal closes automatically
widget receives media
thumbnail appears

7. Architectural summary

medialite is our custom module.
The opener belongs inside medialite.
The opener controls the modal.
The widget controls the field.
Together they implement the restricted workflow.

8. Status

Ready to implement. Estimated build time: 20–30 minutes (45 minutes with step‑by‑step validation).