Mngr: Created page with "= 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: *..."

2026-03-10T22:52:20Z

Created page with "= 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: *..."

New page

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

ICT:Drupal Media Library simple clone - Revision history