Video sections:
- 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.
Getting Started
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 /admin/content/media.
You’ll be able to view and manage all media assets from this page. You can filter by name, type, published status and language.
Create Media
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.
Media Library
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.
Media Source
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.
Configure Formatter
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.
Summary
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.
As one of the media system’s maintainers, thanks for this fantastic and useful article! 🙂 It contains a couple of common misconceptions, though: Media Library definitely does NOT replace Entity Browser. Media Library only works with media, and it was meant to be fairly limited. Although it is customizable, it is nowhere near as powerful and flexible as Entity Browser, which is why EB will continue to exist for the foreseeable future. Likewise, Entity Embed also is a lot more powerful, flexible, and customizable than what’s in core, so it too will continue to exist.
Hi phenaproxima,
Thanks for the feedback. I do like it when a maintainer comments. 😁
Perhaps the word “replace” isn’t the correct one. I understand the Media Library works with just media entities. There’s a bit of copy in the tutorial mentioning that Entity browser and Entity embed are still highly useful modules that work with any entity type.
Cheers,
Ivan
Also, I tweeted this out. It’s by far one of the best and most through articles I’ve seen about media in Drupal 8; awesome job!!
Thanks.
Thanks, a good explanation. I like to organize images into groups. Currently using folders, and Imce File Manager. Is there a best practice way to organize images with the new media modules?
Hi Kieran,
This type of functionality is not supported out-of-the-box.
I’ve noticed, however, it’s something a lot of users are asking for.
Cheers,
Ivan
There is a new module Media Directories (https://www.drupal.org/project/media_directories) which released a first RC in February. Maybe it could be helpful.
Thanks, I’ll have to check out the module.
Great article. I use images a lot on our sites, and the one thing I don’t see anymore, unless I’m just missing it, is a way to customize the embedded images. A long time ago, when you used the editor to embed an image into text, you had a way to add borders, margins, change the size, etc. I know I can do that by making custom styles, then add them to the image, but the old way was easier. Do you know of a way to get that back?
Hi TomP,
Which version of Drupal were you using?
The type of functionality you’re talking about isn’t available out-of-the-box. The Media module lets you embed assets into the editor, but you can’t add a border.
Cheers,
Ivan
It was D7, with ckeditor, and IMCE for inserting the images. I still have one site with it. I’d insert a screen cap if I could showing the editor.
Great article Ivan, thanks! Question, what would be the best way to allow users to CREATE media items only (and not browse or select preexisting media). It seems as though this would be a typical use case. I have created a new Media Type, and only want users to be able to ADD media to this field (within a node form) but it seems Media Library forces a browse area. Tried a few things, but no success. Any tips? Thanks!
Hi Char,
Use inline entity form (https://www.drupal.org/project/inline_entity_form) instead of the media library.
Here’s a link on how to use it, https://www.webwash.net/manage-media-using-entity-browser-and-entity-embed-in-drupal/#use-inline-entity-form-to-upload-media-assets
Cheers,
Ivan
Thanks for the reply… I should have been more specific. Looking to upload multiple Media images at one time, then fill out the rest of the fields attached to that image once they’ve uploaded (like media library handles it). Inline entity form forces you to upload one image (Media item) at a time. Cannot upload multiple.
I’ve combed thoroughly through file entity, entity browser, inline entity form, and a bunch of others with no solution. Last resort may have some be something custom i’m guessing.
Hi Char,
Yes, I think you’ll need to develop something custom for that.
Cheers,
Ivan
Hi Ivan. Thanks for your article!!
Can we use one type of media on article node type (from CKEditor), and a different one in static pages node type using Layout Builder?
I tried to configure different type of images on different content types but I really couln’t do it.
Thanks for your time.
Solved by adding two image media types. CKEditor allows to chose into all media types by default.
Very useful tutorial. Thanks especially for specifying the version(s) for which these features work. So many tutorial writers just slap “Drupal 8” in there and much wailing and gnashing of teeth inevitably follows.
Thanks.
Hi Iven, thanks for your article.
After this tut I only want to use the media-module for my youtube-videos. I know, if I need the youtube-video-url in my twig-template, I can use: {{ node.field_media.value }}. But how can I get the youtube-video-preview-image-url with twig? Can you help out?
Thank you
Hi Kay,
To be honest I have no idea.
I’ve never had to get the YouTube thumbnail image.
Cheers,
Ivan
In CK, when you upload an image via media library there doesn’t seem to be any way to scale it – there’s no draggable square in the bottom corner like you get when you do a straight image upload. Is there anyway you know of to get the scale functionality back?
Hi Bob,
I know what you’re talking about.
You can’t resize the image when you upload via the media library module.
Cheers,
Ivan
Thanks for your tutorial. I would love to see an ability to use the crop api as good 50% of the images our clients use must be cropped due to different responsive image styles.
Is there any chance that the media entity browser can coexist with the cropper widget?
Hi Moritz,
I don’t know if entity browser supports that type of functionality. I could be wrong, it’s been a while since I’ve looked at all the modules.
Cheers,
Ivan
Ivan,
One thing Drupal doesn’t do is allow you to filter media in Views. I’m currently setting up “asset” content types for documents. Assigning taxonomy to these document content type assets. Then using views to pre-populate them on necessary pages. Reasoning for this… The documents assets will be archived after xx time and we want to control how they display visually as well as how they’re sorted, etc.
Is there a better way to do this?
Hi Alex,
I may have misunderstood the sentence. But you can create a view using Media entities and add exposed filters.
Just install the Media module and look at the Media view. “/admin/structure/views/view/media”
Cheers,
Ivan
Thank you for this tutorial! I am missing something, though. I added pdf, excel and word documents to media assets. I have tried embedding a file asset into an article, but only the link to the asset shows up on the page. I would like the file itself show up on the page. I have embedded jpg images in the article and they display correctly (not a link to the file). Thank you.
Hi Jim,
PHP can resize images and HTML can display an image. That’s why resizing images are easy.
Embedding doc file is something else. What should an embedded PDF, excel or word doc look like?
If you want to display a thumbnail of a document then you’ll need a 3rd party library for that.
Cheers,
Ivan
First choice: We want to create nodes that display the full pdf, excel or word document and give the node a URL alias.
Second choice: Link directly to the document. If the link is directly to the document, we don’t want the URL to be sites/default/files/documents/file.pdf so we would like a URL alias.
How would we go about doing either one? Thank you!
Option one, you’ll need to embed the document files somehow, https://stackoverflow.com/a/5566092/614586
Option two, I found this on drupal.org, https://www.drupal.org/forum/support/post-installation/2019-08-11/d8-how-to-url-alias-file-location
Hello Ivan! First of all thank you for the tutorial.
It’s been a while since you created it and the media entity instagram has changes and it requires a Facebook for developers account.
I’ve made one and i’m using on my drupal 9 project the media entity instagram 3.0.6 patch.
When i try to create an Instagram media type content it says “The provided URL does not represent a valid oEmbed resource.” I’ve searched everything and found no solution to it…
Got any ideas/solutions? Thanks!
Hi Dimitris,
I haven’t used the 3.x version of Media entity instagram, so I can’t help there.
Cheers,
Ivan