How to Manage Media Assets in Drupal 8

Join us for a FREE live webinar this week on managing media assets in Drupal 8.
Click here to save your seat!

I attended a core conversation titled “LET’S FIX FILE AND MEDIA HANDLING ONCE AND FOR ALL” at DrupalCon Prague in 2013.

This got my attention, not because the title was in all caps, but because Drupal needed to fix media management, as the title says: “ONCE AND FOR ALL”.

Let’s face it, Drupal doesn’t handle media very well when compared to other systems. I’ve worked with clients who are used to a certain level of functionality when it comes to managing images or videos on websites.

In Drupal 7 you had a few options.

You could use the Media module. But embedding images through the editor could be buggy depending on which module you’d use to implement the editor, i.e., Wysiwyg or CKEditor.

Then you have Scald, which is a pretty good module. Another module which has been around for a long time is IMCE.

However, adding media management into a Drupal site isn’t as straightforward as you think. That’s why I attended the core conversation in Prague. I too thought Drupal needed a great and robust media system.

Fast forward a couple of years since DrupalCon Prague and things have changed.

Thanks to the work from the Drupal Media team, managing media in Drupal 8 has got a lot better.

Now they are working on getting this functionality in Drupal core, which I think is absolutely amazing.

In this tutorial, I’ll show you how to set up media management in Drupal 8.

3 Parts to Handling Media in Drupal

Everyone has their own definition of media management. In this tutorial, I’m going to focus on three parts:

1. Storing assets
2. Embedding assets
3. Browsing assets

I want to give users the ability to create media assets. Then have a button in the editor which they can use to browse assets and then embed them.

We’ll utilize three modules to handle this: Media Entity, Entity Embed and Entity Browser.

What’s Happened to the Media Module?

In Drupal 7, the Media module was jam-pack with a lot of functionality. In Drupal 8, a lot of its functionality has been broken out into seperate modules. There is a Drupal 8 version of Media and it’ll be used to create an out-of-the-box solution. The module doesn’t do much other than ship a bunch of configuration.

Part 1: How to Create Media Entities

To store media assets you’ll need the Media Entity module. The module itself won’t handle any media, it’s just a base entity.

So you’ll need to download other modules which are media providers. For example, if you want to handle images then download and install “Media entity image“. If you want to handle audio files you’ll need the “Media entity audio” module.

For a full list of media handlers go to the Media Entity project page.

I’m only going to focus on two types of assets in the tutorial: images and embedded videos (YouTube or Vimeo).

Let’s start by downloading the following modules:

Then install, “Media image entity” and “Video embed media” (sub-module of “Video embed field”)

Using Drush:

$ drush dl media_entity entity media_entity_image video_embed_field
$ drush en media_entity_image video_embed_media

Create Image Media Bundle

To handle images we’ll need to create a media type for images.

1. Go to Structure and click on “Media bundles”.

From this page you manage all the different media bundles. This is similar to the “Content types” page.

2. Click on “Add media bundle”.

3. Enter Image into Label, “Used for images.” into Description and select Image from the “Type provider” drop-down.

Ignore the other fields for now and scroll to the bottom and click on “Save media bundle”.

You can ignore the “Field with source information” drop-down. We’ll need to create a field and map it after.

4. Now click on “Manage fields” from the Operations drop-down.

We need to create an Image field that’ll be used to store the actual image field.

5. Click on “Add field”, select Image from “Add a new field” and enter Image into the Label field.

6. Leave the “Field settings” page as is and click on “Save field settings” at the bottom.

7. Leave the Edit page as is and click on “Save settings” at the bottom.

8. Click on the Edit tab from the “Manage fields” page to edit the media bundle.

9. Make sure the “Field with source information” drop-down has selected the image field which we created and click on “Save media bundle”.

Type Provider Configuration

The “Media entity” is like any other entity type: it’s fieldable. You can add custom fields, you can configure the form display and general display like you do with content types.

The only difference is, we need to tell the media bundle which field will store the actual file. If you’re creating a document media bundle, then you’d create a File field and select that in “Field with source information”.

Field Mapping

The “Field mapping” section lets you store metadata from the image into custom fields. If you want to store the width, then you’ll need to create a text field and select it from the Width drop-down.

Take note, the possible metadata properties are determined by the type of provider. You’d get different options if you were configuring a document media bundle.

Create Embed Video Media Bundle

Now it’s time to create another media bundle and this one will be used for embedding videos, i.e., YouTube or Vimeo videos.

1. Go back to “Media bundles” and click on “Add media bundles”.

2. Enter “Video embed” into Label, “Used for embedding videos.” into Description and select “Video embed field” from the “Type provider” drop-down.

3. Scroll to the bottom and click on “Save media bundle”.

We won’t have to create a “Video embed” field and map it across like we did for the Image bundle because “Video embed media” module did it for us.

Take note of this message:

So we’ve created our media bundles now let’s look at how to create a media asset.

How to Create a Media Assets

At this point, you can only create assets from the Media page.

1. Go to Content and click on Media.

From this page you can add a media asset and view existing ones.

2. To create an asset just click on “Add media”.

Go ahead and create an image and embeddable video.

Part 2: How to Embed Media Entities

Creating media assets is useful but if you can’t embed them what’s the point of having them.

In this section we’ll embed assets directly into the editor using Entity Embed.

The Entity Embed module allows a site builder to create a button which lets an editor embed entities into a text area, hence the name Entity Embed. It can be used to embed any type of entity not just media bundles. So be creative, you could use it to embed event content types.

To begin, download the following modules:

Using Drush,

$ drush dl embed entity_embed
$ drush en entity_embed

Create Embed Button

1. Go to Configuration and click on “Text editor embed buttons”.

2. Click on “Add embed button”.

3. Add Media into Label, select Entity from the “Embed type” and Media from the “Entity type” drop-down.

4. Once an entity type has been chosen, you can choose which media bundles can be embedded. If none are selected, then all are available.

And finally, upload a button icon which’ll be used in the editor. The default button is just an “E”.

Use this one from the media module: http://cgit.drupalcode.org/media/plain/images/media_embed_icon.png?h=8.x-1.x

At this point you should have two buttons, the Media button which we created and the Node button that comes default with the module.

Add Embed Button to Editor

We created the embed button, now we need to add it to the editor.

1. Go to Configuration, “Text formats and editors” and click Configure on the “Basic HTML” (or any text format) row.

2. Move the icon from the “Available buttons” into the “Active toolbar”.

From this:

To this:

Configure Filters

The next part we need to do is configure the filters.

We need to make sure a few things happen:

1. Correct ordering of filters or the embedding may not work
2. Making sure the “Allowed HTML tags” list accepts the tags used by Entity Embed

Configure “Allowed HTML tags” list

As soon as we added the button to the active toolbar, the following tags should be in the “Allowed HTML tags” list:

<drupal-entity data-entity-type data-entity-uuid data-entity-embed-display 
data-entity-embed-display-settings data-align data-caption data-embed-button>

Make sure these tags are in the text field. If not then embedding media assets WILL NOT WORK.

Enable “Display embedded entities”

Enable the “Display embedded entities” filter. This is required for the embedding to work.

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 you’re 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 Media into a Page

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. 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 choose it, selected a thumbnail size and you’re done.

But if you try and embed a YouTube video using the “Video embed” bundle we created earlier. You’ll just see the video thumbnail and not an embedded player, not the desired result.

Create Media Bundle View Mode

The simple solution is to create a custom view mode for the “Video embed” media bundle. Let’s do this now.

1. Go to Structure, “Display modes”, “View modes” and click on “Add view mode”. Then click on Media.

2. Call this view mode Embed and click on Save.

3. Go to Structure, “Media bundles” and go to the “Manage display” page for the “Video embed” bundle.

4. Enable the Embed view mode which we just created by clicking on “Custom display settings” and select it, then click on Save.

5. Go to the view mode by clicking on it on the top left. Remove all the fields except “Video URL”. Make sure Video is selected from Format and “– Hidden –” from Label.

Then click on Save.

Now when you embed a video, select Embed from “Display as”. If you can’t see the new view mode clear the site cache.

Part 3: How to Browse Media Entities

When we chose an asset, we were given just a single autocomplete field.

This is not ideal. You shouldn’t expect your editors to remember the asset name. It’ll be better to have some sort of browser where we can see all the available media assets.

We’ll use Entity Browser to create browsing functionality and best of all, it integrates nicely with Entity Embed.

Let’s set this up now.

To begin, go download the following modules:

Using Drush,

$ drush dl entity_browser ctools
$ drush en entity_browser ctools

How to Create an Entity Browser

There are two steps involved in creating a browser using the module.

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 new view” form, using the values defined in Table 1.0 and click on “Save and edit”.

Table 1-0. Create a new view

Option	Value
View name	Entity browser
Machine name	entity_browser
Show	Media type of All sorted by Newest first
Create a page	Unchecked
Create a block	Unchecked

3. Next to the Master tab click on “Add” and click 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 a little better.

4. Click on “Unformatted list” next to Format.

5. From the pop-up, select Table and click on Apply.

At this point we’ve switched the view from a list to a table.

Now we need to add two 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 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” from the “Add widget plugin”. Change the Label to “Upload images”.

6. Then select View from the drop-down.

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 with the browser we 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 bundle.

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”.

How do you Add a YouTube Video from the Entity Browser Page?

I haven’t figured this out yet. If you know how, leave a comment.

Summary

Adding functionality to a Drupal 8 site to handle media assets can be done and it’s fairly solid. But as you can see there’s a lot of configuration involved. Hats off to the Drupal Media team for creating a flexible suite of modules. With the “Media in Drupal 8 Initiative” in the works, things are looking very promising.

Extra Resources

FAQs

Q: I created a new view mode but can’t see it when I embed an asset.

Clear the site cache.

Q: When I embed an image and select an image style all I see is a red cross.

Disable the “Restrict images to this site” filter.