View source for 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'' and 
''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).

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