Media embedding in Drupal 8.8

published on September 3, 2019

2007 is the year of my first DrupalCon, and the year the #1 most wanted end-user feature was Better media handling. 2019 is the year that Drupal will finally have it. Doing things right takes time!

Back then I never would’ve believed I would someday play a small role in making it happen :)

Without further ado, and without using a mouse:

The text editor assisted in producing this HTML:

<p>Let's talk about llamas!</p>

<drupal-media alt="A beautiful llama!" data-align="center" data-entity-type="media" data-entity-uuid="84911dc4-c086-4781-afc3-eb49b7380ff5"></drupal-media>

<p>(I like llamas, okay?)</p>

If you’re wondering why something seemingly so simple could have taken such a long time, read on for a little bit of Drupal history! (By no means a complete history.)

2007 and Drupal five

Twelve years ago, in Dries’ State of Drupal talk 1, Better media handling was deemed super important. I attended a session about it — this is the (verbatim) session description:

  • Drupal’s core features for file management and media handling
  • common problems and requirements (restrictions, performance issues, multi-lingual content, dependencies between nodes and files)
  • first approaches: own node types for managing, improved filemananger.module (example: Bloomstreet,European Resistance Archive, Director’s Cut Commercials)
  • next step: generic media management module with pluggable media types, mutli server infrastructure, different protocols, file systems, file encoding/transcoding

It’s surprisingly relevant today.

By the way, you can still look at the session’s slides or even watch it!

2007–2013 (?)

The era of the venerable Media module, from which many lessons were learned, but which never quite reached the required level of usability for inclusion in Drupal core.

2013 (?) – 2019

The Media initiative started around 2013 (I think?), with the Media entity module as the first area of focus. After years of monumental work by many hundreds of Drupal contributors (yes, really!), only one missing puzzle piece was left: WYSIWYG embedding of media. The first thing I worked on after joining Acquia was shipping a WYSIWYG editor with Drupal 8.0, so I was asked to take this on.

To help you understand the massive scale of the Media Initiative: this last puzzle piece represents only the last few percent of work!

Drupal has always focused on content modeling and structured content. WYSIWYG embedding of media should not result in blobs of HTML being embedded. So we’re using domain-specific markup (<drupal-media>) to continue to respect structured content principles. The result is document transclusion combined with an assistive “WYSIWYG” editing UX — which we wished for in 2013.

A little less than two months ago, we added the MediaEmbed text filter to Drupal 8.8 (domain-specific markup), then we made those have previews using CKEditor Widgets for assistive “WYSIWYG” editing, followed by media library integration and per-embed metadata overriding (for example overriding alt, as shown in the screencast).

I was responsible for coming up with an architecture that addressed all needs. To maximally learn from past lessons, I first worked on stabilizing the contributed Entity Embed module. So this builds on many years worth of work on the Entity Embed module from Dave Reid, cs_shadow and slashrsm! Thanks to the historical backlog of reported issues there, we are able to avoid those same problems in Drupal core. The architecture of the CKEditor integration was designed in close collaboration with Krzysztof Krzton of the CKEditor team (thanks CKSource!), and was also informed by the problems reported against that module. So this stabilization work benefited both Drupal core as well as tens of thousands of existing sites using Entity Embed.

I then was able to “just” lift Drupal core patches out of the Entity Embed module (omitting some features that do not make sense in Drupal core). But it’s phenaproxima (thanks Acquia!), oknate and rainbreaw who got this actually committed to Drupal core!

Complete media management shipped in increments

Fortunately, for many (most?) Drupal 8 sites, this will not require significant rework, only gradual change. Drupal 8.8 will ship with complete media management, but it’ll be the fifth Drupal core release in a little over two years that adds layers of functionality in order to arrive at that complete solution:

  • Drupal 8.4 added foundational Media API support, but still required contributed modules to be able to use it
  • Drupal 8.5 made Media work out-of-the-box
  • Drupal 8.6 added oEmbed support (enabling YouTube videos for example) and added an experimental Media Library
  • Drupal 8.7 made the Media Library UI-complete: bulk uploads, massively improved UX
  • Drupal 8.8 will contain the key thing that was blocking Media Library from being marked stable (non-experimental): WYSIWYG integration

Today is the perfect moment to start looking into adopting it shortly after Drupal 8.8 ships in December!

Thanks to phenaproxima for feedback on this post!

  1. See slide 40! ↩︎


Gopi Ramanujam's picture
Gopi Ramanujam

Exciting news! How about migration from Drupal 7 file to <drupal-media> tags?

drico's picture

To add some details to this history, from 2007 to 2013 two solutions were available for media handling, the famous Media module and the Scald suite which already enabled reusability of media content and drag and drop of Scald atoms into WYSIWYG-enabled fields. The fusion of the ideas led to the media entity into Drupal 8.

slybud's picture

Such a great leap in Drupal’s history, I’ve been waiting for this moment for years with the Scald team! Great work Wim, thank you for it and this feels like the landing of Apollo 11, what a great timing!

Wim Leers's picture
Wim Leers

I wouldn’t quite compare it to that, but I’m glad your so excited! :D

frank kelly's picture

With Drupal 8, I use the contrib Juicebox module to create photo galleries. These consist of thousands of jpg files (and thumbnail versions of jpg files) spread across dozens of Galleries. I upload the files to a directory structure that I manage using FTP within sites/default/files. If I want to re-use these jpg files within an article content type I use the contrib IMCE module. It lets me browse through my directory structure and insert the image into the article using CKEditor. It works fine.

So, now what happens? Will media library “discover” my existing files and directory structure? Do I leave the existing files where they are and start adding new files to Media Library? Is there a conversion or migration step. My current Galleries depend on a pre-specified set of files in a pre-specified directory structure. If this changes my galleries go ker-plunck.

Wim Leers's picture
Wim Leers

It’s going to be up to to provide an update path. There actually already is an issue for adding Media support to the Juicebox module, and it’s been open for more than 2.5 years: It also seems that the Juicebox module is not actively maintained: the latest release is a beta, which is more than 2.5 years old too…

Then again, this module seems highly optimized for one particular use case that you could also choose to continue to use this.

There is no simple answer here: because it depends.

The high-level meta issue for migrating into Media is

Michelle Cox's picture
Michelle Cox

I use Juicebox and views to make image galleries from core media entities and it works fine. It sounds like that issue was maybe for the contrib version of Media? Works fine with core.

Mike's picture

Why only media? Same goes for the media gallery module which provides the browser to populate media reference fields. That’s like making moderation only available for nodes.

Wim Leers's picture
Wim Leers

There’s so many reasons to only do embedding of media and not arbitrary entities! This was discussed in detail at

Here are some of the high-level reasons:

  • To offer a great embedding UX, you also need a great selection UX. For Media, there’s the Media Library. For all other entity types, there’s only title-based search. Which is fine for some, but definitely not all entity types.
  • There needs to be a sensible embeddable representation of the embedded entity. This is evident for media. For many other entity types, this is not evident. Even for node entities, it’s non-trivial since for example the “full” view mode includes the full comment list and the “teaser” view mode is usually used in listings, not in embeddings (when embedded, things like author and published date are less important).
  • We didn’t want to block bringing embedding of media entities on having embedding of arbitrary entities. But it’s been designed in a forward-compatible way — the generated & stored HTML is highly structured, making it easy for functionality to be expanded in the future.
  • For those who want arbitrary entity embedding, there’s still — which has to do some very complex trickery and requires some rather confusing configuration to make arbitrary entity types embeddable.
Joseph Olstad's picture
Joseph Olstad

Nice work Wim, media embedding is finally about to make it into “core”. I haven’t yet tried out 8.8.x however I did recently try the varbase distribution and was very impressed with it’s media handling, very very nice.

Victor's picture

Congrats !!! , Media is finally here , a few years after Wordpress did it , but importantly we did a million times better. Thanks to everybody in the media team for all the work. The demonstration video with the keyboard is super awesome and a nice touch.

Wim Leers's picture
Wim Leers

Glad you like it so much! :D