ICT:Drupal - Medialite Opener

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:

1. Upload + Save
2. 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:

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

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

1. 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).