View source for ICT:D Media-Library uploading one file in an Asset

= Media Library use in Asset for uploading ONE single media file =

== Media field edit in Asset ==
* is an Entity Reference to Media with types: Audio, Document, Image and Video
* Required field
* Referencemethod to default
* Limited to 1  (very important - one asset one file)

== Media in Manage form display ==
* Widget = Media Library
* Tab order: Image, Document, Video, Audio

== Media in Manage display ==
* View mode = Media Library

After this configurtion there is an important GUI finetuning needed to simplify the interface and mask unneeded filters and buttons.
Therefor the next chapter is very important.


= Media Library Widget UI Simplification (CSS Overrides) =

== Purpose ==
This document records the CSS overrides applied to the **Drupal Media Library widget**
to simplify the user interface for editors.

The goal is to:
* reduce cognitive load
* hide internal mechanics (filters, buttons)
* provide a clean, focused media selection experience
* preserve full Media Library functionality

These overrides are **intentional**, **documented**, and **part of the UI contract**.

---

== Context ==
The Media Library widget is powered by:
* a Drupal View (for listing media)
* exposed filters (search, filtering)
* a jQuery UI modal dialog

By default, the UI exposes:
* filter forms
* layout switches
* confirmation button bars

For this project, these elements are **not required** and confuse users.

---

== Design Principle ==
Editors should:
* focus on selecting or replacing a single media item
* not be exposed to filtering mechanics
* not be presented with redundant confirmation actions

Filtering and constraints are applied **silently** via Views configuration.

---

== Applied CSS Overrides ==

The following CSS rules are applied to the admin theme (e.g. gin-custom.css).

=== 1. Hide the exposed filter form ===

<syntaxhighlight lang="css">
/* Hide the Views exposed filter form inside Media Library */
.media-library-view .views-exposed-form {
  display: none !important;
}
</syntaxhighlight>

Effect:
* Removes the visible filter form from the Media Library modal
* Filters continue to work internally
* Prevents users from interacting with unintended controls

---

=== 2. Hide the dialog button bar (Select / Cancel) ===

<syntaxhighlight lang="css">
/* Hide the bottom button bar in the Media Library modal */
.ui-dialog--media-library .ui-dialog-buttonpane {
  display: none !important;
}
</syntaxhighlight>

Effect:
* Removes the redundant “Select / Cancel” button pane
* Selection happens directly via clicking media items
* Avoids duplicate confirmation paths

Note:
* Media Library uses jQuery UI dialogs
* Hiding the button pane via CSS is a supported and safe approach

---

=== 3. Hide the Grid / Table display switch ===

<syntaxhighlight lang="css">
/* Hide the Grid / Table view switch */
.media-library-view--display-switch {
  display: none !important;
}
</syntaxhighlight>

Effect:
* Enforces a single, consistent layout
* Removes unnecessary UI choices
* Simplifies training and usage

---

== What These Overrides Do NOT Do ==

These CSS rules:
* do NOT affect data
* do NOT alter Media entities
* do NOT disable Media Library functionality
* do NOT change Views filtering logic
* do NOT interfere with file replacement

They are **presentation‑only**.

---

== Operational Notes ==

* These CSS rules are required for correct UI behavior
* Removing them may:
  * reintroduce clutter
  * confuse editors
  * appear to “break” Media Library UX
* They must be restored after experiments or refactoring

---

== Maintenance Recommendation ==
Maintain a dedicated section in documentation for:
* UI‑level CSS overrides
* why they exist
* where they are applied

This prevents accidental removal during future development.

---

== Summary ==
{| class="wikitable"
! Area !! Decision
|-
| Media selection UI || Simplified via CSS
|-
| Filters || Hidden visually, active internally
|-
| Confirmation buttons || Removed to avoid redundancy
|-
| Layout switching || Disabled for consistency
|-
| Impact || UI only, no data or logic changes
|}

---

== Appendix: Why CSS UI Simplification Is Required for Media Library Upload/Replace ==

=== Observation ===
During testing, it was observed that when the Media Library modal UI elements
(exposed filters, dialog buttons, layout switches) were visible:

* selecting an existing media item
* and attempting to upload or replace the file

did NOT trigger the expected switch to the upload/replace interface.

After restoring the CSS rules that hide these elements, the upload and replacement
behavior started working again immediately.

At first sight this appears surprising, because CSS is normally considered
“presentation only”.

---

=== Explanation (Important) ===

The Media Library widget is NOT a single, isolated component.
It is a composite UI made of:

* a Views-powered listing (grid/table)
* exposed filter forms
* a selection state manager
* jQuery UI dialog controls
* AJAX-driven JavaScript behaviors

All of these parts communicate via DOM presence, focus events, and click handlers.

In particular:

* the Media Library JavaScript uses **visible UI elements** to determine
  the current interaction state:
  * browsing
  * selecting
  * uploading
  * replacing
* when multiple interaction paths are visible at the same time
  (filters, dialog buttons, layout switches),
  the internal state machine can no longer reliably determine
  which action the user intends

As a result:
* the transition to the upload/replace state is not triggered
* the upload box never appears
* replacement of the currently selected file fails silently

This effect is **amplified inside modal dialogs**, where focus handling
and AJAX re-rendering are especially fragile.

---

=== Why Hiding UI Elements Fixes the Problem ===

The applied CSS rules intentionally remove UI elements that are not needed
for the single-file Media Library workflow.

By doing so, they:

* eliminate competing interaction paths
* remove focus and submit-event conflicts
* prevent redundant confirmation logic
* reduce layout re-rendering during selection

This forces the Media Library widget into a **deterministic interaction model**
that matches its expectations for:

* cardinality = 1
* direct selection
* upload or replace of a single file

Once the UI state becomes unambiguous, the JavaScript correctly switches
into upload/replace mode.

---

=== Important Conclusion ===

These CSS overrides are **not cosmetic tweaks**.

They are an **integral part of the Media Library configuration** for this project.

Removing them may:
* reintroduce UI ambiguity
* break upload or replacement behavior
* make Media Library appear “corrupt” or inconsistent

Therefore:
* the CSS must be preserved
* the CSS must be documented
* the CSS must be restored after experiments

---

=== Design Principle (Summary) ===

In the Media Library modal:

''Hiding unused UI elements is required to stabilize widget behavior,
not just to simplify appearance.''

---

== End of Appendix ==

== End of document ==