Media Collections

Illustrated drawing of Amadeus Maxmimilian StadlerIllustrated drawing of Amadeus Maxmimilian Stadler

Amadeus Stadler

Last updated June 30, 2023

Media Collections are a special type of Collection that does not specify a Schema, but rather functions more closely to the Media Library in the sense that it allows uploading binary data as opposed to text content.

In this article, you’ll learn more about what that means and how you can make use of Media Collections to allow Content Editors to easily link files such as PDF documents in Link fields.

Creating a Media Collection

Just like all other Collections, Media Collections are created by clicking “Add Collection” in the Collections tab of the project settings. There, you can specify a content directory and turn the Collection into a Media Collection by setting the content type to “Media”.

This changes the following options, as Media Collections do not support Schemas, drafts, previews or comments. Instead, you’ll be able to specify a maximum file size for the files uploaded to the Collection, as well as which file extensions are allowed.

For performance reasons, the file type validation only compares the extension of the file name with the list of allowed extensions.

If you do not provide a maximum file size, the maximum file size set in the Media Library settings is used. And if you specify no allowed file extensions, all file types are implicitly allowed.

Media Collections are also linkable by default, with a pre-filled URL template that returns the path to the file including its extension within the content directory of the Collection. You are of course free to adjust that template to your needs or disable the option entirely.

Content items within a Media Collection cannot be edited, or marked as drafts, which is why those two permissions don’t exist. Instead, you will be able to control who is allowed to upload new content items to the Collection.

Using Media Collections

Once created, a Media Collection can be added to your project’s sidebar just as any other Collection, and opening it will reveal the files and folders within it. From here, you will be able to upload new items, create folders and move or rename existing ones.

In addition to that, you are also able to replace content items by right-clicking or using the “more” icon next to the item’s name. Replacing an item in a Media Collection has the same benefit as doing so in the Media Library: it allows you to swap a file with a different one of the same type without changing the path. This means that all links to that content item will remain valid, but show the updated version instead.

It’s ideal for when you need to quickly fix a typo in that PDF that you already linked to in ten different places. 😉

Why not just use the Media Library?

Mattrbld already allows uploading binary files such as PDF documents, ZIP archives and of course images and videos through the Media Library and File fields. So why is there yet another way?

The Media Library is excellent for images, especially because of the ability to attach metadata to those files. However, it has a single root directory which contains all the media files and in many static site generators, these media files get transformed during the build of the project, while archives and documents typically only need to be copied to their final destination as-is. Additionally, the items in the Media Library can only be linked to by their file path, which might not be flexible enough for all scenarios.

Similarly, while File fields allow uploads to directories outside the Media Library, they store only the full path to that uploaded file and require prior knowledge that a content item will link to a file, since they have to be added to the Schema.

Media Collections, however, can have their own URL templates and will show up when creating an internal link. This means it is possible to link to a page or a media file from link fields and in rich-text editors! This would not be possible without Media Collections.

So while the Media Library and File fields each have their own strengths and merits, they aren’t the perfect tool for every job, and that is where Media Collections come in.

While it is problematic from an accessibility point of view, many (website-) projects still require a set of PDF documents to be downloadable and linkable from content. This is the perfect use-case for a Media-Collection: simply create a dedicated “downloads” folder to house the PDF documents, point the Media Collection to it and benefit from URL templates, fine-grained permissions and the ease of linking only a Collection can provide.

In the next article, you’ll learn more about how you can customise the URL templates of linkable Collections. Or you can skip ahead to see how you can use Mattrbld to manage content in multiple languages.