Working with media
Background
In lay parlance, “media” is a nonspecific term that can refer to images, documents, and videos you upload as well as external content referenced on your site. In the Drupal Kit, “media” has a more specific meaning. This page clarifies unfamiliar terminology related to Drupal media and offers practical tips for integrating media.
Contents
What “files” and “media” mean in Drupal
In Drupal, files and media have distinct technical meanings:
File: an actual digital file, such as a
.pdfdocument or a.jpgimage, stored in the site’s filesystem. Drupal keeps track of these files through a numbering system (“File 1”, “File 2”), so that the site can retrieve the actual file when referenced in page content. Drupal files store only very basic information: the file size, file type, and upload date.Media: a system for referencing and displaying files. Content editors create media entities by associating a file reference with other metadata (alt text for an image, or a thumbnail for a video, for example). Drupal keeps track of these through a separate numbering system (“Media item 1”, “Media item 2”). Content editors can then display these media items in content. One media item can display in multiple places, and can have different displays in those different contexts.
Practically speaking, content editors interact directly with Drupal media. They only indirectly reference files through the media items they create. Content editors do upload files, but do so by creating a media item that references the file.
The Media Library
All media added to the site displays in the Media Library and becomes available to reference anywhere in the site. Anything in the Media Library can be inserted, by any content editor, into a rich text area, or into a display element that has a media component.
Access the Media Library at Content > Media (/admin/content/media)
The important takeaway: all media is shared across content editing, and any given media item can display in multiple places. Media added from within a specific page still ends up in the Media Library.
Put another way, there is no way to limit a media item’s usage to only one location. Because of this, deleting media includes risks, as discussed below.
How to create media
There are two ways to add media for general use on the site:
Upload new media items to the Media Library directly from Content > Media > Add media (
/media/add)Add media during page creation, from either a rich text toolbar or from a component that has a media upload option.
Reusable media
Newly added media items will show in the Media Library, eligible for reuse anywhere on the site.
Removing media vs. deleting files
Because Drupal media are shared assets, exercise caution when considering deletion. You may have added it in one place, but another content editor may be referencing it elsewhere. Instead of deleting the media item, a safer approach is to remove the reference where the media item displays.
Because of the likelihood of someone unintentionally deleting a media item that is used somewhere else on the site, the system currently does not allow deletion of Drupal files, period.
If you truly need to delete a file, email drupal-kit-support@utlists.utexas.edu.
Disambiguation: “media” vs. “embedded content”
In the context of a Drupal Kit site, media is distinct from embedded content. Embeds are external media, such as Qualtrics forms or other Other embeds that require <script> or <iframe> tags. These embeds are not part of the Drupal media system and not stored in the Media Library.
When to use an external file sharing service instead of uploading files?
We do not recommend uploading documents in non-web formats (e.g. PDF, Word, or Excel) or large files such as high-resolution images to the site. File sharing platforms offer a better experience both for the site manager who must upload and maintain these files, as well as for the end-user clicking on a link to one of these files.
Use case |
Where to store |
|---|---|
Images displayed inline in your website pages |
Upload images directly to the site |
Everything else (documents, high-resolution images for download) |
Host files on a third-party cloud file sharing platform such as SharePoint and link to them. |