Media Library Minimal Clone – Problem Description and Architectural Outline

1. The Problem

Drupal’s built‑in Media Library widget uses a multi‑step modal workflow:

Step 1: Upload file → validate → create file entity → create media entity.
Step 2: Display a selection grid inside a modal/iframe.
Step 3: User selects the media item → modal returns the media ID to the field.

This workflow is powerful but problematic for simple use cases:

The modal is implemented as a Drupal dialog with no reliable events.
The modal often loads inside an iframe, blocking parent‑window JavaScript.
AJAX events do not consistently fire.
The “Save” button inside the modal cannot be intercepted cleanly.
Gin theme dialog overrides do not apply to Media Library.
The modal cannot be closed programmatically in a deterministic way.
The selection UI is unnecessary when the user only uploads a single file.

As a result, it is extremely difficult to implement:

auto‑closing the modal after upload,
returning the media ID directly,
or integrating the workflow into custom forms.

The core issue is that the Media Library modal is a “black box” with no hooks.

2. Architectural Approach: A Minimal Media Library Clone

Instead of modifying or forking the entire Media Library module, we create a

- minimal custom field widget** that reuses the good parts of Media Library

(upload + validation + media entity creation) and replaces the problematic UI.

This is not a fork of the module. It is a small subsystem that uses Drupal’s existing APIs.

2.1 What We Keep (from Media Library)

File upload handling
File validation (MIME, size, dimensions)
File entity creation
Media entity creation
Metadata extraction
Access checks
Storage logic

These parts are stable, well‑engineered, and should not be rewritten.

2.2 What We Remove

The modal dialog
The iframe wrapper
The multi‑step wizard
The selection grid
The “Add selected” button
All AJAX‑based selection logic

These parts cause the unpredictability and cannot be reliably extended.

2.3 What We Replace

We replace the Media Library widget with:

A custom field widget that renders a simple “Upload image” button.
A custom modal (or inline form) that contains only the upload form.
A modified save handler that:
- creates the media entity (using core logic),
- immediately returns the media ID to the parent form,
- closes the modal.

This eliminates the entire selection UI and second step.

2.4 Resulting Workflow (Simplified)

User clicks “Upload image”.
A minimal modal opens with the upload form.
User uploads a file.
Drupal validates and creates the media entity (core logic).
The save handler returns the media ID directly to the field.
The modal closes immediately.

No iframe. No selection grid. No multi‑step wizard. No AJAX events. No Gin dialog interference.

2.5 Advantages

Deterministic behaviour.
No dependency on Drupal’s dialog system.
No dependency on Gin theme.
No fragile JavaScript hooks.
Fully successor‑friendly.
Uses Drupal’s backend logic without modification.
Minimal code surface.
Easy to document and maintain.

2.6 Components to Implement

A custom field widget plugin.
A custom route/controller for the upload form.
A custom modal (or inline form wrapper).
A save handler override that:
- calls Drupal’s media creation logic,
- returns the media ID,
- closes the modal.

No need to rewrite Media Library. No need to fork the module. No need to override core services.

3. Summary

The Media Library modal is not extensible in a reliable way. The simplest and most maintainable solution is to create a minimal clone of the Media Library widget that:

reuses the upload + validation + media creation logic,
removes the selection UI,
returns the media ID immediately after save.

This produces a clean, deterministic subsystem that avoids all modal issues and is easy to maintain for future administrators.