Creating and configuring Media Types

Basic concepts

If you have worked with nodes before, you will find some similarities in the basic concepts when dealing with media entities. For example, Media Types are the equivalent to media entities of what Content Types are for nodes. In other words, the media entity (just like any other content entity in Drupal 8) has bundles, which for the end user are exposed using the terminology of Media Types.

As soon as you enable the Media module, some Media Types will be created automatically for you:

• Document
• Image
• Audio file (local)
• Video file (local)
• Remote video

(Note that these are available when using the Standard profile. If you are using another distribution or install profile, other types may be available instead of these ones, or you may need to create your own.)

They are ready to use, and if you want to directly create a Media entity you can go to /media/add/{type_name} and see how the media entity form looks like.

One important difference of media entities when compared to nodes is that not all media types are equal. They are specialized so that they are able to know how to manage the media resource they are dealing with in the best way. For example, media types that deal with images will be able to validate file extensions, as well as know how to map width/height image information to Drupal fields. On the other hand, this knowledge won't be necessary or useful to youtube media entities, which in turn will probably need to know how to retrieve a thumbnail or the video author information from the remote video server.

This specialization is done by delegating all this "domain" knowledge to a specific plugin type, called Source Plugin. All Media Types (created by Drupal or by the end user) need to define what Source Plugin they will use. For example, you can have many image media types that are all using the "image" source plugin. At this moment, Drupal comes with three Source Plugins implemented in core:

• The File source plugin
• The Image source plugin
• The oEmbed source plugin

They largely correspond to the contributed modules Media Entity Document, Media Entity Image, and Video Embed Field, when Media Entity was not part of Drupal core. Other plugins will probably be added to Drupal core in the future. In parallel, many contributed modules provide source plugins (providers) for core media entities:

• Slideshow
• Twitter
• Facebook
• Instagram
• Slideshare

... and many more.

Any site listed in https://oembed.com/providers.json is supported by the core oEmbed source plugin. Though currently only YouTube and Vimeo are enabled. The oEmbed Providers module can be used to enable others via the UI.

Creating and configuring a Media Type

Just like with content types, you will probably want your site to have additional Media Types, or you may want to edit the existing types Drupal core creates for you. In order to do so, navigate to Structure -> Media Types, or visit /admin/structure/media: 

You will need then to provide the basic information for your media type:

1 - Indicate the Media Source plugin

Here is where you need to choose what plugin will be used for this media type. If you need to create a type different from those provided by Drupal core, you can install a contributed module that provides it. Please refer to the section above for some examples.

2 - Define the source field

All media entities need to have at least one field to store essential media resource information. This field is called the source field and you can either use an existing field or let the system create a suitable field for you. When you create the first type of a given source, the system will automatically create a source field. In the screenshot above, however, we are creating a second type that uses the "Image" source plugin, which then allows us to choose either to create a new field or to re-use the field that was created for the previous media type.

3 - (Optionally) indicate metadata mapping information

Source plugins know how to retrieve media-specific metadata information from their assets, and this allows for a powerful feature of Media Entities: you can map metadata from the media resource into standard Drupal fields every time a new entity is created. For example, the \Drupal\media\Plugin\media\Source\Image media source plugin allows for the following metadata attributes:

...
  'name' => $this->t('Name'),
  'mimetype' => $this->t('MIME type'),
  'filesize' => $this->t('File size'),
  'width' => $this->t('Width'),
  'height'  => $this->t('Height'),
...

while the \Drupal\media\Plugin\media\Source\OEmbed source plugin allows for the following:

...
      'type' => $this->t('Resource type'),
      'title' => $this->t('Resource title'),
      'author_name' => $this->t('The name of the author/owner'),
      'author_url' => $this->t('The URL of the author/owner'),
      'provider_name' => $this->t("The name of the provider"),
      'provider_url' => $this->t('The URL of the provider'),
      'cache_age' => $this->t('Suggested cache lifetime'),
      'default_name' => $this->t('Default name of the media item'),
      'thumbnail_uri' => $this->t('Local URI of the thumbnail'),
      'thumbnail_width' => $this->t('Thumbnail width'),
      'thumbnail_height' => $this->t('Thumbnail height'),
      'url' => $this->t('The source URL of the resource'),
      'width' => $this->t('The width of the resource'),
      'height' => $this->t('The height of the resource'),
      'html' => $this->t('The HTML representation of the resource'),
...

These values, when mapped as indicated in the picture above, will be copied into empty field values when the entity is first created in Drupal. Once #2983456: Expose triggering update of media metadata + thumbnail to end users is fixed, there will be an additional mechanism that will allow users to trigger / refresh copying these values from the source into the entity fields manually.

This step is optional, and won't do any action if left unconfigured.

Creating media items manually

In order to manually create some media entities go to /media/add and choose the Media Type you are interested in.

You will then see the entity form (which you can configure in /admin/structure/media/manage/{type_name}/form-display). Fill up all the fields and save the entity.

Taking advantage of the automatic name generation for media entities

As with any entity in drupal, all media entities need to have a human-readable label attached to each instance created. The Media module automatically creates a base-field for this, called "Name".

If you want your editors to be able to input/edit this value manually on each entity, you don't need to do anything, aside from probably configuring some of the field widget settings on the form, such as textfield size, placeholder, etc. These settings can be configured at the URL: admin/structure/media/manage/{media-type-machine-name}/form-display

On the other hand, if you do not want to expose this to be created/modified for each entity, the module provides an "automatic label" functionality. This actually happens each time a media entity is being saved without a manual value introduced. In order to take advantage of this, just disable/hide the name field from the entity form configuration (on the same URL indicated above), and your entities will be created with a default name/label.

Note that each type provider (media source plugin) is requested to provide a sensible default name, according to each source characteristics. For example, the "image" type provider will probably provide a default name based on the image filename, or the "twitter" source will provide a default name based on the tweet's author/tweet ID.

If the source provider does not indicate any type-specific name to be used as default and a media entity is created without name, the Media module will use the following pattern as a fallback: media:{media_type_machine_name}:{uuid}.

Using the pre-defined Media Gallery

There is a list of all media entities created on your site available at the URL: /admin/content/media .