Skip to content

Compatibility

media_directories_compat is a migration helper. Enable it on sites that previously embedded media using the entity_embed module and want existing content to keep rendering after switching to core's media_embed filter. It rewrites legacy <drupal-entity> markup to <drupal-media> at render time, so you don't have to bulk-update every existing field value.

The submodule has no admin UI and no configuration. The conversion runs as part of the filter pipeline.

When you need this

  • Your site was on entity_embed for media embeds.
  • You're moving to Media Directories (or to core's media embed in general).
  • Existing field values contain <drupal-entity data-entity-type="media" …> tags that you don't want to migrate by hand.

If your content was created on a site that already used <drupal-media> — which is the case for most fresh installs — you don't need this submodule.

Install

drush en media_directories_compat

Dependencies: media_directories, core media. No dependency on media_directories_browser, so you can use it standalone during a migration without committing to the Vue.js browser.

Additional setup

None in the common case. On install the submodule scans every text format that runs the entity_embed filter and wires itself in automatically:

  • it enables its Legacy entity embed compatibility filter at a weight that runs before entity_embed, so each <drupal-entity> media tag is rewritten to <drupal-media> before entity_embed can try (and fail) to render it with a removed display;
  • it enables core's Embed media (media_embed) filter to render the resulting <drupal-media> tags;
  • if media_directories_browser is enabled, it also enables that module's Media image dimensions filter (after media_embed), which reapplies the original image style or width/height the converter carried over.

The entity_embed filter is left enabled, so any non-media entity embeds keep working.

Enable it before removing media_directories_editor

If you remove the editor while content still has <drupal-entity> media embeds and this module is not yet enabled, entity_embed hits the now-missing media_directories_image_dimensions display and the page fails with a fatal error. Enable this submodule first — see the upgrade guide.

Custom or unusual text formats that never had the entity_embed filter are left untouched; add the Legacy entity embed compatibility and Embed media filters to those by hand if they render legacy markup.

When the migration is complete and you've fully cut over to <drupal-media> markup — either by saving content through the new editor or by running a one-time migration — you can disable the submodule.

Verifying the install

  • View a piece of pre-existing content that still contains <drupal-entity data-entity-type="media" …> markup. The rendered output shows the same media as before — but viewing the raw HTML reveals <drupal-media> tags instead of <drupal-entity> ones.