Update February 2020
This tutorial has been updated for Drupal 8.8 over at “Managing Media Assets using Core Media in Drupal 8“.
There’s a lot of momentum to fix media management in Drupal 8 thanks to the Media Entity module. By using a combination of Media Entity, Entity Embed, Entity Browser and some media providers such as Media entity image you could add decent media handling in Drupal 8.
Then in Drupal 8.4, the Media Entity functionality was moved into a core module called Media. However, the core module was hidden by default. Now in Drupal 8.5 it’s no longer hidden and you can install it yourself.
In this tutorial, you’ll learn how to install and configure the Media module in Drupal 8 core. This tutorial is an updated version of the How to Manage Media Assets in Drupal 8 tutorial where we cover Media Entity.
Configuring Entity Embed and Entity Browser for the core Media module is essentially the same as with Media Entity. So if you have experience using Media Entity, then you’ll be fine using the core Media module.
- Storing Media Assets
- Displaying Media Assets
- Embedding Assets into the Editor
- How to Browse Media Assets
What’s the Difference Between Media Entity and Media
The biggest difference between the two modules is that the API has changed. Any media provider module for Media Entity such as Media entity Instagram or Media entity Twitter need to be updated to use the new API. A lot of these modules now have a 8.x-2.0 version which only works with core Media. So if you’re going to use a media provider module read the project page.
If you want to see a technical explanation of the changes go to the “Moved a refined version of the contributed Media entity module to core as Media module” change record on drupal.org.
Before we begin, go ahead and install the Media module. It comes with Drupal core but it’s off by default.
Part 1: Storing Media Assets
The Media module implements a fieldable entity type called Media. This means you can add custom fields to them like content types and adjust their look-and-feel through the “Manage display” page. If you know how to manage content types then you’ll be right at home managing media types.
Let’s first look at how media assets are stored in Drupal 8. Saving assets into a Drupal site is similar to creating content.
1. Click on Content in the toolbar.
2. Click on the Media tab, then click “Add media”.
3. Choose which type of media you want to upload, in this example I’ll choose Image.
4. Enter in a name for the asset in the Name field and select an image using the Image, then click on Save.
5. Once you save the form, you’ll be redirected to the public media page.
View all Media Assets
You can view all upload assets from the Media page we were just on, go to the Content page and click on the Media tab.
You can search assets by their name using the “Media name” field or filter by media type using the Type drop-down.
Creating and managing media assets are pretty straightforward but the magic happens in the Media types, let’s look at them next.
Media types are just like content types or taxonomy vocabularies. They are fieldable configuration entities.
Go to Structure then click on “Media types” to create and manage them.
Drupal 8 ships with four media types; Audio, File, Image and Video.
The File and Image media types are fairly self-explanatory use them to upload images or general files such as PDFs.
Audio and Video media types should be used when you want to locally host the video or audio file. The asset will be played using the HTML tags,
<video>. You can’t use the this media type to embed videos from YouTube or Vimeo. To do that you’ll need the “Video embed field” and a new media type which we cover later in this tutorial.
Every media type needs to use a “Media source”, this tells Drupal how the file should be handled, i.e., how the file should be stored or if a thumbnail should be generated.
The Media module in Drupal 8.5 comes with four media sources; audio, video, file and image.
So if you want to store and display tweets for example, then all you’ll need to do is create a media type called “Tweet” (or whatever you want) and install the 8.x-2.0 version “Media entity twitter” module. The 8.x-1.x version only works with Media Entity, whereas, the 8.x-2.x works with the core Media module.
Create Embed Video Media Type
Now let’s go and create a new media type for embedding YouTube videos. But first, download the 8.x-2.0 (make sure it’s 2.0) version of “Video Embed Field“. The module ships a sub-module called “Video Embed Media” which has a media source for handling embedded videos.
composer require drupal/video_embed_field
Once downloaded go and install “Video Embed Media” from the Extend page.
1. Go to Structure, “Media types” and click on “Add media types”.
2. Add “Embed video” into Name and “Used for embedding videos” into Description.
3. Select “Video embed field” from the Media source drop-down box.
4. From the field mapping section, you can store specific metadata about the video into a custom field.
For example, if you want to store the YouTube ID, which’ll be the “Video ID”. All you need to do is create a custom field and select it from the drop-down to map it.
5. Once everything is complete click on Save at the bottom of the page.
Edit Media Type
When you edit the Embed video media type, you should see three familiar tabs: Manage fields, Manage form display and Manage display.
A media type is just a fieldable configuration entity same as content types or vocabularies so managing fields are the same.
If you click on Manage fields you see a single field called “Video Url”. This is where the URL to the embedded video will be stored. We didn’t create the field, instead “Video Embed Media” programmatically attached it for us when we created the media type.
Create an Embed Video
Now that we’ve created our media type, let’s create the actual asset.
1. Go to Content and click on the Media tab.
2. Click on “Add media” then “Embed video”.
3. Enter a name into the Name field and enter in a URL to a YouTube video, then click Save.
It’s important to note that Video Embed Field supports more than just YouTube. Out-of-the-box it supports YouTube and Vimeo but it has support for other video providers via contrib modules. Check out the “Video Providers” section on the project page for more details.
4. Once you’ve saved the form, you’ll be redirected to the media display page.
But as you can see in the screenshot above, the page looks messy. It’s displaying all the fields; date, author, thumbnail and at the bottom the actual embedded player.
Modify Media Display
Let’s clean up the display of the embedded video so only the embedded player shows.
1. Go to Structure, “Media types”.
2. Click on “Manage display” from the Operations drop-down on the “Embed video” row.
3. Move all the fields to the Disabled section except for “Video Url”.
4. Now if you go to the media display page you should only see the embedded player.
Part 2: Displaying Media Assets
You learnt how media assets are stored in part one and how to create your own media types. Now we’ll look at how to display the assets on a content type using a field.
I mentioned earlier that an asset is just an entity. So if you want to attach it to a basic page or article, all you need to do is create an entity reference field. Of course there’s a bit more to it, so let’s look at it now.
Create Media Field
The Media module comes with a field called Media. It simply lets you reference assets using an entity reference field. Let’s create one on the Article content type.
1. Go to “Content types”, “Manage fields” on the Article row.
2. Click on “Add field.
3. Select Media from the “Add a new field” drop-down and enter Asset into the Label field.
4. On the “Field settings” page, leave it as is and click on “Save field settings”.
5. Down in the “Reference type” field-set, you need to select which media type you allow. In this example, I’ll choose Image, then click on “Save settings”.
Now it’s time to test it out.
Go to Content, click on “Add content”, then Article and you should see the Asset field with an autocomplete field.
Then simply search for an asset using the “Use existing media” autocomplete field.
If you need to create a new asset, you’ll need to click on the “media add page” link or just go to Content, Media and create it from there.
But there is a problem with this method. You can’t create an asset directly from the article page. You need to go to the add media page, a totally seperate screen, upload the image then come back and search for it in the autocomplete field.
This workflow is not ideal. Now I’ll show you how to use Inline Entity Form module so you can create the assets without leaving the page.
Use Inline Entity Form to Upload Media Assets
Go download and install the Inline Entity Form module.
composer require drupal/inline_entity_form
1. Once installed, go to the “Manage form display” on the Article row.
2. Then select “Inline entity form – Complex” from the Widget drop-down on the Asset field.
3. Click on the cog wheel and make sure you check both “Allow users to add new media entities.” and “Allow users to add existing media entities.”.
3. Then click on Save.
Now if you go back to the create Article form, you’ll notice that the Asset field looks different.
Just click on “Add new media” if you want to create a new asset. When you click on the button, the create media form appears right here so you can create a new asset and attach it to a content type without leaving the form.
The “Add existing media” button allows you to select existing assets via an autocomplete field.
As you can see Inline Entity Form really does create a better user experience for editors. From the same page you can create/edit/delete and attach assets to a content type without leaving the page.
Part 3: Embedding Assets into the Editor
So far we’ve looked at how to attached assets to fields, but now let’s look at embedding them in the editor.
Entity Embed allows you to create a button which is added to the editor. When you need to embed an asset, just click on the button, select the asset and embed. The module isn’t tied to the Media entity, it can be used to embed any entity type.
Using Composer, download the following modules then enable Entity Embed.
composer require drupal/embed composer require drupal/entity_embed
Create Embed Button
1. Go to Configuration and click on “Text editor embed buttons”.
2. Click on “Add embed button”, enter Assets into Label and select Entity from “Embed type” and Media from “Entity type”.
3. Further down the page you can specify which bundles (Media types) should be allowed. If none are selected then all are allowed.
You can also upload an icon for the button. I’ll be using the media embed icon which comes with the Drupal 8 version of the Media module. You can grab a copy of it from here.
Once you’ve configured the form click on Save.
You can have as many buttons as you want and they can all be managed from the List page. If you need to modify a button then just click on the Edit button in the operations column.
Add Button to Editor
Now that we’ve created the button let’s add it to the editor. It won’t automatically appear in the editor unless we add it ourselves.
1. Go to Configuration and click “Text formats and editors”.
2. Click on Configure on the “Basic HTML” text format.
3. Find the button in the “Available buttons” section and move it into Media in the “Active toolbar” section.
Now comes the tricky part, we’ve added the button but now we need to configure the filters in a specific order.
Few important steps need to happen here:
- Add the correct tags to the “Allowed HTML tags” text area.
- Enable “Display embedded entities” filter
- Reorder filters in specific order.
Configure “Allowed HTML tags” list
Once the button was added you should see the following tags in “Allowed HTML tags”.
<drupal-entity data-entity-type data-entity-uuid data-entity-embed-display data-entity-embed-display-settings data-align data-caption data-embed-button>
Enable “Display embedded entities” Filter
Next, enable the “Display embedded entities” filter from Enabled filters check list.
Confirm Order of “Align images” and “Caption images”
The Entity Embed README.txt mentions if you’re using the “Align images” and “Caption images” filters, to order “Align images” before “Caption images”.
Problem with “Restrict images to this site” Filter
The “Restrict images to this site” filter stops an image being displayed if you embed it and select an image style.
The filter stops a user from pointing to an image which is not hosted on the site. For example, if your Drupal site is hosted at my-drupal.com, then it won’t allow you to add an image such as
<img src="http://random-site.com/image.jpg" />, all your images need to be
<img src="http://my-drupal.com/image.jpg" />.
There is an open issue on drupal.org about it.
The workaround for now, unfortunately, is to remove the filter.
Once everything has been configured, make sure you click on “Save configuration” at the bottom of the page.
The filters list should look like this:
How to Embed Assets into the Editor
Now that the “Basic HTML” text format has been configured, we should be able to embed assets.
1. Go to Content, “Add content” and click on Article.
2. Click on the embed button and a pop-up should appear with an autocomplete field.
Search for the asset using its “Media name” and click on Next.
3. If it’s an image, select Thumbnail from “Display as”, select an image style, align and add a caption.
Then click on Embed.
4. Once embedded you should see the image on the right with the caption.
Save the page and you’re good to go.
Embedding YouTube Videos
In the section above it was easy to embed an image. You simply upload it, select a thumbnail size and you’re done.
Adding a video using the “Embed video” media type we created earlier is just as easy.
1. Click on the embed button within the editor, and search for a video in the Name autocomplete field.
2. Then select “Full content” from the “Display as” drop-down and click on Embed.
3. Once embedded you should see the YouTube player in the editor.
If you do not see an embedded player and just the video thumbnail then you’ll need to configure the formatter on the Media type.
Go to Structure, “Media types” and click on “Manage display” on the Embed video row.
Make sure the “Video Url” field is using the Video formatter.
Part 4: How to Browse Media Assets
We had to use an autocomplete field to find and embed an asset into the editor in the last section. This type of user experience is not great. You can’t upload an image after clicking on the embed icon, without going to a different page, and you can’t easily search assets, you have to know the name of it.
In section, you’ll learn how to use Entity Browser which lets you create a screen where you can search, select and upload new assets.
Using Composer, download the following modules then enable Entity Browser and Chaos tools.
composer require drupal/ctools composer require drupal/entity_browser:~2.0
Make sure you download the 8.x-2.0 version of Entity Browser.
How to Create an Entity Browser
Configuring Entity Browser requires two steps:
- First you’ll need to create a view using a display called “Entity browser”. This view will be used to list out all assets.
- Then you’ll need to configure an entity browser and select the created view.
Create Entity Browser View
1. Go to Structure, Views and click on “Add view”.
2. Fill out the “Add view” form, using the values defined in Table 1-0 and click on “Save and edit”.
Table 1-0. Create a new view
|Media type of All sorted by Newest first
|Create a page
|Create a block
3. Next to the Master tab click on “Add” and select on “Entity browser.
It’s important that you select the “Entity browser” display or you won’t be able to select this view when we’re configuring the actual browser.
Let’s change the view to a table so it looks better.
4. Click on “Unformatted list” next to Format.
5. Select Table and click on Apply.
At this point we’ve switched the view from an unformatted list to a table.
Now we need to add two more fields: Thumbnail and “Entity browser bulk select form”.
6. Click on Add next to Fields, add the Thumbnail field.
This will display a thumbnail of the media asset.
7. Then add the “Entity browser bulk select form”.
This field is used to select the asset when browsing. It is a required field.
8. Reorder the fields so they’re as follows:
9. Once complete the preview should look like the image below:
10. Don’t forget to click on Save.
Create Entity Browser
Now that we’ve created the view, let’s configure the browser.
1. Go to Configuration, “Entity browsers” and click on “Add entity browser”.
2. Enter “Assets browser” into Label, select iFrame from “Display plugin” and Tabs from “Widget selector plugin”.
Leave “Selection display plugin” as “No selection display”.
Then click on Next
Do not select Model from Display plugin if you’re using the browser with Entity Embed it isn’t compatible (Issue #2819871).
3. On the Display page, configure a width and height if you like but do check “Auto open entity browser. This will save an extra click when embedding.
Then click on Next.
4. Just click Next on “Widget selector” and “Selection display”.
5. On the Widgets page, select “Upload images as media items” from the “Add widget plugin”. Change the Label to “Upload images”.
6. Then select View from “Add widget plugin”.
7. From the “View : View display” drop-down, select the view which we created earlier.
If you can’t see your view, make sure you select “Entity browser” when configuring it:
8. Once configured the Widgets page should look like:
Configure Entity Embed to use Browser
Entity Embed now needs to be linked to the browser we just created.
1. Go to Configuration, “Text editor embed buttons” and edit the embed button.
2. You should see a drop-down called “Entity browser”, select the browser you just created and click on Save.
Using the Entity Browser
Go into an article or page and click on the Entity Embed button.
You should now see a pop-up with two tabs: “Upload images and view.
From the “Upload images” tab, you can upload a new image and it’ll create an Image media entity.
If you click on view, you’ll see all the media assets.
To embed an asset, just choose which one you want and click on “Select entities”.
With every new Drupal 8 release you can see that the media functionality is getting better. In Drupal 8.5 , there’s still a lot of manual configuring required but the foundation of how assets are stored exists. If you want to keep track of how everything is progressing then look at “Media in Drupal 8 Initiative” and “Media initiative: Essentials – first round of improvements in core“.