Last updated January 30, 2013. Created by RobW on September 24, 2012.
Edited by rustybike. Log in to edit this page.

The File Entity and Media modules work together to provide a unified method for storing, managing, and displaying Media in Drupal. They allow a user to create file fields that can be configured to store and display many different types of media, including images, video, and audio, sometimes created by Media provider modules (e.g., Media: YouTube, Media: Soundcloud, or OEmbed). In order to display these different types of media, file fields use formatters, often added by the provider module, that need to be configured when setting up your site.

The following documentation is for Media 2.x and File Entity, although much of it works with Media 1.x with slight alterations (e.g., in Media 1.x, the link to the "File Types" page is in Configuration instead of Structure).

Definitions

File types

Files are grouped into File Types. Each file type is defined by a list of mime types, a universal way of specifying file formats on the internet. The default file types are Application, Audio, Image, Text, Video, and Other. There is currently no way to define new file types in the UI.

View Modes

View Modes are used to tell Drupal 7 (and soon 8) that a piece of content is in a certain context. The content can then be altered or displayed in a way that best suits that context. Two view modes that most people are probably familiar with are the default teaser and full modes. Custom view modes can be defined with modules like Entity View Mode, Display Suite, or in a custom module with hook_entity_info_alter().

The Good Stuff, or: Managing the display of your File Field

A file field's display is managed per file type. Navigate to Structure -> File Types. You will see a list of available file types with links to "Manage fields", "Manage display", and "Manage file display" for each.

Manage Fields

The File Entity module makes all files full fieldable entities, the same as nodes and taxonomy terms. Just like in the "Content types" section, you can add custom fields to each file type.

Manage Display

Again, like in "Content types", you can manage the display of custom fields on each file type. This section does not control the formatting of the files themselves, only the display of fields attached to the file entity.

In this section you will also see a toggle for "Custom Display Settings". When expanded you can enable and disable view modes available for this entity. A view mode must be checked here in order for it to be available in "Manage File Display". At this time it's recommended to use only custom view modes defined by the user and the following default view modes; the rest are left over from Styles module integration and will eventually be removed:

  • "Teaser" (Currently not included by default. You can add it with the patch in the issue above or define it as a custom view mode)
  • "Full"
  • "Preview" (Used in admin contexts, e.g., for placeholders in WYSIWYG fields, in the Media browser, and in the Media field widget)

Manage File Display

In "Manage File Display" you can configure formatters for your file types. Many Media provider modules add their own formatters here; for example, Media: Youtube and Media: Vimeo both provide a "Preview Image" and "Video" formatter.

Formatters can be enabled and configured for each view mode enabled in their file type's "Manage Display" section. For example, a user may want to display a Media: Vimeo preview image when a node is viewed as a teaser, the Vimeo video when the full node is viewed, and a video with different width and height formatter settings when the node is viewed with a custom view mode called "video gallery". Many formatters (notably "Image") allow the user to select the image styles they have defined in Configuration -> Image Styles.

Because multiple media providers can use the same field, formatters are arranged in a top-to-bottom cascade. Drupal will use the first formatter that can be applied to the output of a field. If a video field enables the "Media: Youtube Video", "Media: Vimeo Video", and "Large filetype icon" formatters for the "Full" view mode, Drupal will use the Youtube formatter if the file's mime type is video/youtube, the Vimeo formatter if the mime type is video/vimeo, and fall back to the large filetype icon if the mime type is video/{anything else}.

Configuring the File Field to display using "Manage File Display" settings

In order for the file field to display using the formatters defined in "Manage File Display", it must be set to display the "rendered file". Navigate to the "Manage Display" page for the content type that contains your file field. Choose "Rendered file" as the file field's format for all view modes in which you would like to use the formatters defined in "Manage File Display".

Further Theming

You can create custom theme functions and template files for even more control with theme hook overrides. The theme suggestions provided by the File Entity module are:

file__{file type}
file__{file type}__{view mode}
file__{mime type}
file__{mime type}__{view mode}
file__{file id}
file__{file id}__{view mode}

Replace all '/' and '_' in mime types with '_' for theme functions and '-' for template files.

Some Media provider modules replace these with their own templates and theme hook suggestions. You can view all available theme hook suggestions with the Devel Theme Developer module, Mothership's Poor Themer's Helper, or hopefully consult the provider's docs for more info.

Note that inserting media into the text body using the media module WYSIWYG integration is quite limited, and the above "Further Theming" doesn't currently work for this. For example, when inserting images the output is not themed, so no wrapper divs or classes are included. Other types of media don't seem to work at all.

A work-around is to use the WYSIWYG fields module. For more information about these limitations see the issue: http://drupal.org/node/1283844

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

Comments

Note that inserting media into the text body using the media module WYSIWYG integration is quite limited, and the above "Further Theming" doesn't currently work for this.

For more information about these limitations see the issue: http://drupal.org/node/1283844