Skip to content

Upgrading

Media Directories 3.x replaces the two original editor submodules with a single modern one:

Deprecated submodule What it did Replaced by
media_directories_ui Entity Browser–based admin browser and field widget. media_directories_browser
media_directories_editor entity_embed/CKEditor integration and the "Image with dimensions" field formatter. media_directories_browser

Both are deprecated. This page walks through moving an existing site onto media_directories_browser and explains what the module does automatically to protect your existing display and widget configuration when you remove the old submodules.

Back up / export first

On a configuration-managed site, export your configuration before you start (drush config:export) and work through the steps on a copy you can throw away. Several steps below rewrite core.entity_form_display.* and core.entity_view_display.* configuration.

Step 1 — Enable the browser

drush en media_directories_browser

See the Browser page for its configuration and the CKEditor 5 / text-format setup.

Step 2 — Switch field widgets

Media reference fields that still use core's Media library widget (or the old Media Directories entity-browser widget) need to move to the Media Directories Browser Widget. The Switch widgets tab (/admin/config/media/media_directories/switch-widgets) lists every eligible field and converts the ones you select in one click — see Switch every field at once for exactly what is and isn't carried over.

You're reminded, and it's handled on uninstall either way

While a deprecated submodule is still enabled, the site's Status report (/admin/reports/status) flags how many fields still use an old widget and links back to this action. And even if you skip this step, uninstalling media_directories_ui (Step 3) migrates any field still on its entity-browser widget automatically — to the Browser widget when media_directories_browser is enabled, or core's Media library widget if it isn't. Doing it explicitly here is still recommended: it also covers fields on core's Media library widget and lets you tune the new widget's settings.

q.trim is not a function on node edit forms

Some Drupal 11 sites report a q.trim is not a function JavaScript error in the AJAX dialog on node edit forms while a media field still uses core's Media library widget. It comes from a jQuery 4 incompatibility outside Media Directories, not from this project. Switching the field to the Browser widget (this step) removes core's Media Library widget from the form and clears the error.

Step 3 — Keep inline CKEditor embeds working

Do this before you uninstall the editor if any rich-text content contains images embedded through the old entity_embed button — markup like:

<drupal-entity data-entity-type="media"
  data-entity-embed-display="entity_reference:media_directories_image_dimensions" …>

Those embeds are rendered by the editor's media_directories_image_dimensions embed display. When you remove media_directories_editor (Step 4) that display plugin disappears — but the entity_embed module, and its text-format filter, normally stay enabled. The filter then hits the now-missing display and throws a PluginNotFoundException, taking down every page that contains such an embed with a fatal error (a white screen). Enabling the compatibility module first avoids that window entirely.

drush en media_directories_compat

On install the Compatibility submodule wires itself into every text format that runs the entity_embed filter: it enables its Legacy entity embed compatibility filter (which rewrites <drupal-entity> media tags to core <drupal-media> tags) and core's Embed media (media_embed) filter that renders them. When media_directories_browser is enabled it also turns on that module's Media image dimensions filter, which reapplies the original sizing. The compatibility filter runs before entity_embed, so each media tag is converted before entity_embed can hit the removed display — no fatal. The entity_embed filter is left enabled, so any non-media entity embeds keep working.

Image styles and dimensions are preserved

A legacy embed that used a specific image style — or an explicit width/height set without one — keeps it. The converter carries it over as a data-image-style (or data-width / data-height) attribute on the <drupal-media> tag, and media_directories_browser's Media image dimensions filter applies it to the rendered image. The media is embedded in its default view mode, with the image style layered on top. (If the browser module isn't enabled, add that filter — or set a matching view mode — yourself.)

If you have no inline <drupal-entity> embeds, you can skip this step.

Step 4 — Uninstall the deprecated submodules

drush pm:uninstall media_directories_editor media_directories_ui

media_directories_editor depends on media_directories_ui, so uninstall the editor first (Drush orders this for you when both are listed). Each module migrates its own configuration on the way out — the editor converts image field displays (below), and media_directories_ui converts any field still on its entity-browser widget (to the Browser widget, or core's Media library widget when the browser isn't enabled).

Image field displays are migrated automatically

media_directories_editor provided the "Image with dimensions" field formatter (media_directories_image_dimensions). If any Manage display configuration used it — common on image/media reference fields — simply removing the module would make Drupal fall back to the "Label" formatter, so those media items would render as their filename instead of a thumbnail, and the field would drop to the bottom of Manage display with its label forced to Above.

To prevent that, the editor's uninstall step converts those displays to core's "Thumbnail" formatter (media_thumbnail) before Drupal removes the module:

  • The image style and link settings carry over unchanged.
  • The field keeps its label and position.
  • An explicit custom width/height set without an image style cannot be represented by the Thumbnail formatter and is dropped — those items render at the image's original size. Set an image style under Manage display if you need a specific size. A status message reports how many displays were affected and how many lost custom dimensions.

The site's Status report (/admin/reports/status) warns you ahead of time how many displays still use the deprecated formatter, so the change is never a surprise.

Configuration-managed sites

The automatic conversion is skipped during a configuration import (drush config:import), where your exported configuration already defines the displays. Run the uninstall on a live environment, then drush config:export and commit the converted displays.

The browser_thumbnail image style is preserved when in use

media_directories_ui shipped an image style named browser_thumbnail. Its uninstall now checks whether any other configuration still references that style and keeps it when something does — it is only deleted when nothing depends on it. If you reused browser_thumbnail in your own field displays, they keep working after the uninstall.

Remove the stale embed button from your toolbars

Uninstalling the editor deletes its Media embed button, but the button's item may linger in a text format's CKEditor 5 toolbar. CKEditor silently drops the missing item (logging a harmless toolbarview-item-unavailable warning in the browser console). To clear it, edit each affected format under Configuration → Content authoring → Text formats and editors (e.g. Full HTML) and remove the Media button from the toolbar.

Checklist

  • [ ] drush config:export (start from a clean, captured state)
  • [ ] Enable media_directories_browser and configure the text format / toolbar
  • [ ] Switch field widgets on the Switch widgets tab
  • [ ] Check the Status report for deprecated-formatter usage
  • [ ] Enable media_directories_compat before uninstalling, if any content has legacy inline <drupal-entity> embeds (prevents a fatal error)
  • [ ] drush pm:uninstall media_directories_editor media_directories_ui (image displays auto-convert to Thumbnail)
  • [ ] Remove the stale Media embed button from your text-format toolbars
  • [ ] Review Manage display for any field that lost custom dimensions
  • [ ] drush config:export and commit the result