Last updated 13 October 2016. Created on 24 July 2012.
Edited by Kristi Wachter, pbulebar, mariacha1, firfin. Log in to edit this page.


This tutorial will outline how to install and configure Media 2.0. We will create nodes with file fields (which can be documents, images, videos, etc) and configure the display of these fields.

As Media has developed, it has used many different approaches, so old sites are left with a jumble of overlapping features and it's incredibly confusing. Hopefully this tutorial will help outline the suggested method for approaching managing media on your Drupal site. (Please provide feedback if there are better ways to handle things).

Key to this issue is that Drupal ships with several features that are similar to Media. The ability to upload files and images is not replaced by Media, but rather supplemented. This means that the user is left with both options (if not more) and must somehow know which one is the built in (not to be used), and new (preferred method).

For a collection of useful materials for anyone working with media modules in Drupal, see Resource Guide: Managing Media in Drupal.

Modules Used

How Does Media Work?

Media along with File Entity, provides a way to manage the storage and display of all types of media or files. It does this by creating new File Types such as Document (PDF, etc), Audio, Image, and Video. When you add a File field, Media takes over. It lets you configure additional fields for each File Type, such as an "Image Tags" field for the Image File Type. Then, when you upload an Image, you can provide more details for those additional fields. From a display side, you can set up different View Modes and determine which Styles are used. (That part is confusing, so see below.) Most of this is done automatically for you which is different than the normal Drupal method of configuring most stuff by hand. If you have used field collections before, think of Media Files as Field Collections that can have any number of fields.

How Does a File Get its Style?

In brief (we'll go over it with images later) this is the path a file takes while being displayed.

File Field is used in a content type.

Media File Selector Widget is used which handles how a file is stored AND displayed. This widget decides which File Type each value of the field is and from then on, that file type will be used. You DO NOT select this as a user.

View Mode is then selected. This is similar to the Default and Teaser View Modes that you have for nodes. This is the selection you make when managing the content type's display.

Displays (Display Handlers) are really a set of ways to handle a file. You select a number of these Displays and Drupal will start at the top and try to use that method. If it fails, it goes to the next one. For example, if you pick Image for a text file, it can't display an image, so it will try the next option, such as URL to File.

Display Handler Settings are further options to configure how each Handler works. Build in Image Styles are one way that Drupal manages the display of Images. These are available here. You can create a new Image Style (such as a 75px by 75px thumbnail) and select it as an Image Handler Setting. Not all Handlers have settings.

Theming then takes over.

Note on Theming: There are multiple template files you can use for files themed this way. The easiest is structured as such, file--<file-type>--<view-mode>.tpl.php. For example: file--image--preview.tpl.php or file--video--my-custom-view-mode.tpl.php. For a template (of the template), use the file_entity.tpl.php file inside the file_entity module.


We want to add an image to our node and have it display as a 200px by 300px image.

We first create a File Field and select the Media File Selector Widget. Then we select settings so that only images can be selected, otherwise use the defaults. For our 200px by 300px option, we create an Image Style called 200by300. We then edit the Default View Mode for the Image File Type and select the Image Handler. Then under the Image Handler Settings, we choose our 200by300 Image Style.

Now, with Screenshots!

Screenshot Tutorial

Please see the example right above for a description of what we are going to do.

Add a Media Field

Configuration path: admin/structure/types/manage/example-type/fields (Manage Fields under Content Type)

Here we create a new field, called Example Image. We select the File field type and the Media File Selector Widget. (Note: we do NOT select Image, Multimedia Asset, or the File widget.)

Save the first screen of Field Settings as default (there are no options), then go to the next.

Note: In Media 7.x-2.0-unstable7, the old "Library" Plugin was removed, and "View Library" was renamed to "Library". If you are using this version of Media or later, use the "Library" Plugin wherever "View Library" is referenced below.

In the Field Settings screen above, choose which Browser Plugins you want. I recommend Upload, View Library, and Web. Upload will handle uploading image, View Library is the new way of searching for existing files, and Web allows you to link to externally hosted files (such as Youtube files).

In the Allowed File Extensions field, enter the extensions you want to use. We will pick, "jpg, jpeg, gif, png".

For Allowed Remote Media Types, we will select Image since this is an image field.

Set Content Type Display Settings for the Field

Configuration path: admin/structure/types/manage/example-type/display (Manage Display under Content Type)

Here we select the Formatter. We want the Rendered File Formatter for our image. This formatter will allow our Image to be handled by Media on the Display side and allows us to pick which View Mode and Handler to use. Note the View Mode is set as Default. We can change this later, and we'll see where we set settings for each View Mode.

Create an Image Style

Configuration path: admin/config/media/image-styles

We want to add an Image Style to format the image to 200px by 300px. We add the style here.

Creating Image Styles is a little beyond the scope of this tutorial, but we will create a simple one here. Use the Scale and Crop effect and select 200px and 300px. We've created our new style!
Note:For more information on Image Styles see the "Adding and changing styles" section of Working with images in Drupal 7 and 8. The rest of that page is about the core image module, you should probably ignore or skim over those sections.

Manage the Display of Images (Manage File Types)

Configuration path: admin/structure/file-types

Here we can manage all of our File Types. This includes the extra fields for these types as well as the Display using different View Modes. Finally, there is the File Display settings. This option is where we manage the display of the actual file (which is the main field of this File entity).

Select Manage Display.

Manage our View Modes

Configuration path: admin/structure/file-types/manage/image/display

Here we can manage our view modes for Images. Under Custom Display Settings, we can select the View Modes that are available. The Additional View Mode was added by me using the Entity View Mode module. Once you clear Drupal's Cache, you will see this view mode listed on the top right as well. By creating new View Modes, we can assign special ways of displaying content.

You will also see the Rights field that I added to the Image File Type. You can add any fields you like to the File Types and manage their display like a normal content type. This allows you to tag files or provide extra information on them. They are kind of like Field Collections if you have used those.

Manage How We Display the File

Configuration path: admin/structure/file-types/manage/image/file-display

This is the central location to manage how we display files. You see the View Modes in the top right, the Display Handlers on the left, and the Handler Settings on the bottom.

Think of the View Modes as level 2 tabs. For now, we are using the Default View Mode, but we could create another one or use one of the presets.

Then, since we only want to display images using the built in Image Handler, we select that. If you had Handlers that only work for one type of file, such as a Youtube handler for video files, you could select multiple to try. Drupal will try to use the top handler first, and if it fails, it will use the next. So, if you have Youtube and uploaded video files, you could have Youtube try to make an embedded view first, and then display the URL to file if that fails.

Lastly, our Image Handler lets us select the Image Style to use, so we'll pick our newly created "200by300" style.

I believe the Rendered File Handler is used if you want the module Styles to handle the rendering of this type of file. This is not covered here, but it's worth noting that the Handler has a confusing name! Don't select it unless you know what it is!

Create a New Node and Upload an Image:

Uploading the image is fairly straight forward. However, once you upload it, you can select Edit Media to set the Title and other Fields you've added. This process is a little confusing. And the UI is styled differently!

Test it Out

Looking for support? Visit the forums, or join #drupal-support in IRC.


_sania’s picture

I don't have 'enable browser plugins' and 'remote media types' options, I have file field and media file selector. May be there are some screencasts?

Had enabled media YouTube module and it appeared. Add it to learning text, when you firs work width module, you don't expect this. Maybe just me)) Thank you for good module and documentation!!!

pandaeskimo’s picture

Thanks for the feedback. I believe the remote media is an optional module filefield_sources. That part isn't necessary.

I'm not sure of your other issue, can you clarify a bit. You should enable all the modules you need to get them to show up. The Youtube one won't show up if you don't install and enable that module.

If you don't set any of those options, you should still be good with the defaults.

itsdavidbaxter’s picture

I am having the same issue. When I go to the second Field Settings screen the "Enabled browser plugins" and "Allowed remote media types" sections do not appear. I have enabled all the modules listed on this page (Media, File Entity, and Entity view modes), although I did install Media 1.x and not 2.x. Could this be the cause?

pandaeskimo’s picture

I have not used Media 1.x in a while. All of this is using the new methods in Media 2.x. Media 2.x uses tight integration with File Entities and the whole process is quite different.

If you are starting a new site, my recommendation is to go with Media 2.x, but if you already have Media 1.x, you may find sticking with that a little easier. Converting will leave you with modules that support one and not the other and the options you need to pick become very confusing.

On that front, File Entities seems to be progressing really well and adding a lot of support you'd expect such as replacing files (and keeping the file name), having the upload workflow work as expected, and being able to specify extensions for file types.

It's hard to keep these guides up to date and clear since things keep changing. The goal for this was to get people (mostly) on the right track since there is so much outdated information and confusing modules. This was very much a guide on what worked for me and I (we) welcome other's contributing any helpful feedback on it.

If you were confused by the Media 2.x requirement, it may help for you to edit the guide with a warning or clarification.

leliem’s picture

Hi Guys,

thanks for the nice guide.
Unfortunately, for my new site it isn't working.

The problem is, that in the media browser settings (as well as in the media-module-provided "add media" dialog) the media library is not shown.
On admin/config/media/browser i can only choose to activate "Upload" and "Web".
"Library" and "View Library" are missing.
Also, when adding media to an article, the only option/tab available is "Upload".
It is not possible, to reuse images already present on the server by browsing the library.

I already tried reinstalling the media module (Version 7.x-2.0-unstable7).
The plugins are present in the module folder (in media/includes/), but they just are not recognized.

Does anyone know, how to solve this problem? Google didn't help so far..
[Media 7.x-2.0-unstable7, Drupal 7.18, PHP 5.3.10-1]

Thanks & greets

pandaeskimo’s picture

Since this is an issue with configuring / a bug in the Media module, please post your issue to that issue queue. You likely won't get much of a response here.

I would check your permissions, but I've never had this issue so I don't know what might be causing it.

Best luck!

leliem’s picture

good idea, I just posted it there.

Just in case anybody else is interested in this, it can be found here:

firfin’s picture

Maybe I am completely missing the point here, but I find very little mention of the filetypes here?
The first step in the screenshots is going to a contenttype and adding a file field there.
Shouldn't the first step be going to 'structure' -> 'file types' -> whatever filetype you want to use / edit?

It was my understanding that the 'file type' were stand alone entities. Not just fields to attach to nodes? Like it says on the Displaying Media handbook page.
Should this be cleared up?

pandaeskimo’s picture

It seems like your largest concern is that this guide describes the whole process someone might use when adding files as fields to a content type and doesn't just focus on file entities. Media 2.x uses file entities and perhaps you are looking for a guide on using that alone. Media 2.x is the management of these file entities and their use as fields in content types / entities. This guide is intended to give not only an overview of the entire process in a way that mirrors how Drupal is typically configured, but also gives an example of one of the more common use cases.

You could write a whole guide about file entities and files can be managed and displayed outside of content types. However, this is not the typical use case and has nothing to do with Media. The second half of the tutorial / guide describes how to manage file types since you need to understand this system to use Media 2.x well.

I tried to describe this in a way that made sense to me, in a general to more specific way that mirrors how you create pre-defined types of fields. Add Field -> Set Widget -> Configure Widget -> Configure View Mode that Widget is Set to -> Configure Image Style that View Mode is Using. I can see how it would make more sense to go the other way as well, define the image, then add it to the content type.

There is a description of the entire process in the beginning and then if you skim the example in the tutorial there are headings that mention defining File Types.

What changes / improvements would you suggest?

firfin’s picture

First of all thanks for your substantial and astute reply. You are absolutely correct in assuming what I am missing. You are indeed describing a typical (or 'old-style from the days of CCK') based approach. What I was hoping for was a new way or approach, utilizing all the power and flexibility that fields and entities give us.
Especially in this case, how to use the file types entities in combination with media.
And I have indeed missed the second half, apologies for that.

Maybe we should mention or make more explicit that this handbook page describes the typical use, but that is also possible to use file entity/media in other ways? Possibly create another page describing this process?
If this is indeed possible ...
I am currently exploring these possibilities (and making screenshots along the way.)

pandaeskimo’s picture

If you are able to put together a guide or even start one, that would be great. It's always nice to have an example or use case for other people to look over. As you have hinted at, many components in Drupal take radically different approaches and some of these are from out-dated systems.

This was the way I was able to wrangle Media 2.x and File Entities. The modules are great, but since Media 1.x was / is so different, there are so many competing methods for dealing with this stuff. This is especially troublesome for a project that starts with one and transitions to the other since at times you'll see all of the competing methods on the screen at once.

My overview of Media 2.x, File Entities, and Display Suite (covered in a guide I made in the DS documentation) feels the most consistent with out of the box Drupal. It's what made sense to me, but I'm sure there is a better way out there or a better way for people who think about things in a different way. The more documentation the better.

If you are able to make another guide, I think we should link to each or make a page that describes the two examples and why you might prefer one to the other.

Not intended as a dig against the community, but while I was exploring and compiling this guide, the only documentation I could find was this spider web of a flowchart describing the relationships between all the components.

firfin’s picture

The other handbook page Displaying Media has some more information about usage of file entity and fields. I found this page very useful.
Thanks for your effort!

mparker17’s picture

If you enable both the Convert Media tags to markup text filter (i.e.: to convert [[{type:media... ]] tags into markup) and the Typogrify module's Typogrify text filter (i.e.: to add typographic refinements), be careful to ensure Convert Media tags to markup runs first (i.e.: give it a lower weight in the Filter processing order)!

By default, Convert Media tags to markup runs after (i.e.: has a higher weight than) Typogrify, which means the quotes in the Media tags will be converted to "fancy quotes", and drupal_json_decode won't be able to decode it.

mikebrooks’s picture

The Add a Media Field screenshot shows "Media file selector" as the widget. In my installation, using media-7.x-2.0-alpha4, the widget value is "Media browser". Does the screenshot need to be updated?

rwilson0429’s picture

Thank you for the excellent and detail documentation. I've been using the Media module, and its supporting modules (i.e. File Entity) for all of my installations for the past 3 to 4 years. This documentation of integrating Media is well written, comprehensive, enhanced by detail screen shots, puts all of the key pieces together and provide a good explanation of what each piece does and how they all play together to deliver the desired output. New-comers will find integrating Media in Drupal a lot easier to wrap their heads around when documentation like this exists. Kudos to all that contributed to this documentation.