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

Appendix: Medialite Module File Structure

This appendix documents the current state of the medialite module and the additional files and directories that will be added when implementing the custom Media Library opener.

1. Current File Structure (after today's work)

modules/custom/medialite/

 medialite.info.yml
 medialite.libraries.yml           (if present, depending on our stripped version)
 medialite.routing.yml             (may exist if the stripped clone kept routes)
 medialite.services.yml            (may exist if the stripped clone kept services)

 src/
   Plugin/
     Field/
       FieldWidget/
         MedialiteWidget.php       ← Our custom widget (Media Lite / restricted)

   # Other directories may exist depending on what we kept from the clone:
   Controller/                     (optional)
   Form/                           (optional)
   Templates/                      (optional)
   # These are remnants of the stripped-down Media Library clone.

2. Files Already Involved in the Workflow

• medialite.info.yml

 Declares the module and makes it discoverable by Drupal.

• MedialiteWidget.php

 Our custom field widget.  
 This is the entry point for the Media Lite (restricted) workflow.

• Optional files (depending on what we kept from the clone):

 - controllers
 - forms
 - templates
 - services

These are not directly involved in the opener logic but remain part of the module’s internal structure.

3. New Files and Directories to Be Added (tomorrow)

To implement the custom Media Library opener, we will add the following:

3.1 Directory structure

modules/custom/medialite/

 src/
   Plugin/
     media_library/
       opener/                     ← NEW directory
         MedialiteOpener.php       ← NEW file (the opener plugin)

3.2 New file: MedialiteOpener.php

This file will:

• implement MediaLibraryOpenerInterface
• override the modal behaviour
• hide the media grid
• show only the upload form
• auto-select the uploaded media
• return the media to the widget
• auto-close the modal

This is the core of the upload-only workflow.

3.3 Widget update

We will update:

modules/custom/medialite/src/Plugin/Field/FieldWidget/MedialiteWidget.php

to instruct the widget to:

• use the Medialite opener instead of the default Media Library opener

4. Resulting File Structure (after adding the opener)

modules/custom/medialite/

 medialite.info.yml
 medialite.libraries.yml
 medialite.routing.yml
 medialite.services.yml

 src/
   Plugin/
     Field/
       FieldWidget/
         MedialiteWidget.php

     media_library/
       opener/
         MedialiteOpener.php       ← NEW (custom opener)

   Controller/                     (optional)
   Form/                           (optional)
   Templates/                      (optional)

5. Summary

• medialite is our custom module.
• It already contains the custom widget.
• Tomorrow we add the opener plugin inside the same module.
• The opener will give us:

 - upload-only
 - no grid
 - no browsing
 - no Insert step
 - auto-close
 - immediate thumbnail in the form

This appendix provides a stable reference for understanding the module layout and the components involved in the custom Media Lite workflow.