- History of Media Management In Drupal 8 (00:02:22)
- Manage and Create Media (00:09:44)
- Media Field (00:19:56)
- Media Library (00:23:45)
- Embed Media into the Editor (00:28:41)
- Create Custom Media Type (Instagram posts) (00:41:03)
- Questions (00:57:59)
➡️ The tutorial below is the show notes for this video. If you prefer text you can read the tutorial below or watch the video above.
If you want to learn how to use Entity browser and Entity embed then read “Manage Media using Entity Browser and Entity Embed in Drupal 8“.
A lot of media functionality has been added into Drupal core over the last few releases. First, we got the Media module in 8.5 which offers fieldable media types. Then we got the Media Library module which offers a popup where users can select media assets. Now for Drupal 8.8 and above you have the ability to embed media assets directly into the editor.
There are three important parts when it comes to media functionality. You need the following:
- Store media assets (media types)
- Reuse media assets (media library)
- Embed media assets
As of Drupal 8.8+, the above-mentioned functionality is all supported in Drupal core without installing any extra modules.
This functionality could be achieved before Drupal 8.8 by using Media entity, Entity embed and Entity browser. But required a fair bit of site-building and configuring. However, now all you need to do is install Media and “Media Library” and you’re good to go.
In this tutorial, you’ll learn how to create and manage assets, using the Media field and Media library. Then we look at how to embed assets directly in the editor. We finish things off by creating a custom media type to manage Instagram posts.
History of Media in Drupal 8
Before we jump into things let’s take a moment and talk about the history of media in Drupal 8.
On November 19, 2015, Drupal 8.0.0 was released into the wild. Out-of-the-box it didn’t offer any new media functionality other than an image and file field. You could, however, embed one-off images into the editor but that’s it.
Then the community got together and built some modules for handling media:
These modules are great and work pretty well but require decent site-building to get going. You can’t just install a module and you’re done.
But then it was decided that Drupal core should have this functionality (which I totally agree with) and the Media Initiative was born. And over the last couple of years, most of the functionality offered by the above-mentioned modules is in Drupal core, Drupal 8.8 to be exact.
So here’s what has changed:
- Media Entity replaced by Media
- Entity Browser instead use Media Library
- Entity Embed No specific module; functionality shared between Media and Media Library
I should mention that Entity Browser and Entity Embed are still highly useful modules. They allow you to embed and browse any entity type not just the media entity. So you could use these modules to browse and embed products into an article just to name an example.
First, go ahead and install the Media module.
How to Create and Manage Assets
Once you’ve installed the Media module, you can create and manage assets from the Media tab in the administration section. Log in as an administrator, click on Content in the toolbar, then the Media tab. Or go directly to
You’ll be able to view and manage all media assets from this page. You can filter by name, type, published status and language.
Creating an asset is pretty straightforward.
1. Click on “Add media” from the Media page.
2. Select which type of media you want to create by clicking on one of the media types.
The available media types are relatively self-explanatory, and you’ll only see it if you installed Drupal using the Standard installation profile. The two most used are Image and “Remote video”.
There are differences between the Video and “Remote video” media type. Video allows you to upload an mp4 file and it’ll render the video using the
<video> tag in Drupal. “Remote video”, on the other hand, is used when you want to embed a YouTube or Vimeo video. So they do have two different use cases.
In this example, click on Image.
3. Upload an image using the Image field then click on Save.
4. Once you clicked on Save, you should be redirected back to the Media page, there you should see the image you just uploaded.
How to Use the Media Field
So far we’ve looked at how to create media assets, let’s now look at how to attach them to content using a field.
The Media module ships with a field type with the same name: Media.
If you go to the “Add field” page on any fieldable entity, for example, a content type. You’ll see the Media field in the reference section. This field type allows you to reference media assets.
Note: You’ll only see this field type if you installed the Media module.
Create Media Field
Let’s go ahead and create a Featured field on the “Basic page” content type so an editor can select a featured asset.
1. Go to Structure, “Content types”, and click on “Manage fields” on the “Basic page” row.
2. Click on “Add Field” and select Media from the “Add a new field” drop-down, then enter Featured into the Label field.
Then click on “Save and continue”.
3. Leave the “Field settings” page as is, and click on “Save field settings”.
4. In the “Reference type” fieldset, check Image and “Remote video” in the “Media type” checkboxes, then click on “Save settings”.
Reference Media Asset
Now that we created a Media field let’s create a page and reference an asset.
1. Go to Content, “Add content”, and click on “Basic page”.
2. Enter in a title and reference an asset by searching using its name.
Note: Make sure you’ve created a media asset if you haven’t go to the Media page and create one.
3. Once you’ve filled out the fields, click on Save.
The default field widget that comes with the Media field, as shown below, isn’t the most intuitive.
First, if you want to create a new media asset, you have to click on “media add page”, which will take you to another page.
Second, to select an existing asset, you need to use the “Use existing media” autocomplete field, which just shows you the name of the asset. You can preview or see what you’re selecting.
Luckily there’s a module called “Media Library” which offers an enhanced interface for browsing and selecting assets.
The first thing you want to do is go ahead and install the module. So go to Extend and install the Media Library module.
Configure Field Widget
To use the “Media Library” widget on the Featured field which we created earlier, we need to simply reconfigure the field widget on the “Manage form display” page.
1. Go to Structure, “Content types” and click on “Manage form display” on the “Basic page” row.
2. Find the Featured field and select “Media library” from the Widget drop-down.
Scroll to the bottom and click on Save.
If you create a Media field and the “Media Library” module is already installed, the “Media library” field widget will be automatically selected. You won’t have to manually change the field widget like we just did.
3. Now, if you go back to the “Basic page” edit form and look at the Featured field, you should see something different.
When you click on the “Add media” button you’ll get a pop-up where you can browse existing assets and upload new images.
As you can see the interface is much better than the generic autocomplete field.
How to Embed Media Assets into Editor
In the above section, we looked at how to select an asset using a media field. Now let’s learn how to embed assets directly into the editor.
First, make sure you installed both Media and “Media Library” module.
1. Go to Configuration, “Text formats and editors”, then click on Configure on the “Basic HTML” row.
2. Scroll down to the “Toolbar configuration” section, move the “Media library” into a region in the active toolbar.
If you can’t see the button then make sure you’ve installed “Media Library”.
3. Scroll down to the “Enabled filters” section and enable “Embed media”.
4. If you’re using the “Limit allowed HTML tags and correct faulty HTML” filter in your text format. Make sure you can see the following in “Allowed HTML tags”:
<drupal-media data-entity-type data-entity-uuid data-view-mode data-align data-caption alt title>
Once everything is configured, scroll to the bottom and click “Save configuration”.
5. Go and create or edit a basic page or article and then click on the “Media library” button in the editor. You should see the same media library used on the media field.
Select an asset then click on “Insert selected”.
6. Once embedded, click on “Edit media” to align the asset and to add a caption.
How to Create a Custom Media Type
When you install Drupal using the Standard installation profile, you’ll get 5 different media types: Audio, Document, Image, “Remote video” and Video.
The two media types you’d use the most are Image and “Remote video”.
This being Drupal you can, of course, create your own media type by going to Structure and clicking on “Media types”.
In this section, we’ll create a media type for Instagram posts.
If you edit or create a new media type then you’ll see a drop-down called “Media source”.
The “Media source” is in charge of handling the actual file such as an image file for example, or an embeddable URL like a YouTube URL. The 5 sources in the screenshot above are the ones that ship with Drupal core. However, you can download others from drupal.org.
If you go to the Media entity project and scroll down to the “Media provider modules” section, you’ll see links to a whole bunch of modules which ship a media source.
Now make sure you read the project page and see which version of the modules supports core Media or Media Entity module.
For example, if you go to the Media entity Instagram project page. You’ll see two versions of the module: 8.x-1.x and 8.x-2.x. The 8.x-2.x is the version you want to use because we’re using the core Media module and not the Media Entity module.
Download Media Entity Instagram
Seeing as we want to embed Instagram posts we’ll need to download and install the Media entity Instagram module.
composer require drupal/media_entity_instagram
Once downloaded go ahead and install the module.
Create Media Type
1. Go to Structure, “Media types” and click on “Add media type”.
2. Enter “Instagram” into Name and add a description if you like.
3. Select Instagram from the “Media source” drop-down.
4. Select “- Create -” from the “Field with source information”.
5. Scroll down and click on Save.
You’ll need to configure the Instagram formatter. Or it’ll just display the URL to the post and not embed the actual Instagram post.
From the “Media types” page, go to the “Manage display” page for the Instagram media type.
Change the Instagram formatter from “Plain text” to “Instagram embed”.
Create Instagram Media Asset
Now that we’ve created the media type and configured everything, let’s test it out.
1. Go to Content, Media, “Add media” and click on Instagram.
2. Enter in a Name and paste in an Instagram URL.
3. Now go ahead and try embedding it into the editor.
If all has been configured properly you should see the embedded post.
Media handling in Drupal 8 has come a long way. I am really surprised by what you can achieve by using just the Media and “Media Library” module. Powerful functionality can be built using just core modules. If you need to handle embeddable content such as Tweets or Instagram posts then luckily there are modules out there that can help.