Advanced Media Library

The Advanced Media Library feature of Mattrbld allows you and your team members to manage arbitrary metadata attached to your media files in one central location. This is most commonly used for things such as alt and title attributes on image files, but can be expanded to include other types of data as well.

In this article, you’ll learn how to enable the Advanced Media Library and configure it to suit your needs, how to tell if it is enabled, how it works behind the scenes and how this associated metadata is stored in your content items.

Enabling the Advanced Media Library

Since not all projects may need the features of the Advanced Media Library, it is disabled by default. It can be activated by enabling the toggle in the Advanced Media Library section of the Media Library tab in the project settings.

Activating the toggle will immediately define a new Schema for your media library items with two default fields: alt and title, since those are usually what’s most commonly associated with images.

As with regular content Schemas, you can fully customise this Schema to the needs of your project by adding and removing fields and setting up validation or even localisation.

Once it is configured, all users with the “edit media” permission will be able to see and modify the fields specified in this Schema when clicking on a media file in the Media Library, or when inserting images Image or into Rich Text fields.

The values entered in the Media Library will serve as the default values when the image is then inserted into content, but it is possible to override these values on individual content items, for example to better match an image’s fallback colour to the design of a specific content item.

As can be seen in the screenshot above, another indicator that the Advanced Media Library is active is the pill with the label “Advanced” next to the heading of the Media Library.

How it Works

Whenever a media file is uploaded or first clicked on in the Media Library, Mattrbld creates a corresponding metadata file in the .mattrbld/media directory, which is a direct mirror of the upload directory configured in the Media Library settings. So if you have an /content/uploads/image.jpg in your Media Library, the metadata for it would be stored in .mattrbld/media/image.jpg.json.

Like other JSON content, these files contain the content defined by the Advanced Media Library Schema. For example with just the default alt and title fields, the file’s contents might look like this:

{
  "alt": "The alt text for the image",
  "title": "The image title text, if specified"
}

If the media file is moved or renamed, the corresponding metadata file will be moved or renamed accordingly, so the files are always connected.

Metadata in Content Items

Normally, the output of an Image field is a simple string containing the path of the image file in your project, or at the outputPath property, if configured in the Media Library settings. If the Advanced Media Library is active, however, the output of then Image field is instead an object with a src property containing the path to the image and the other properties specified in the Advanced Media Library Schema.

For example:

{
  "src": "/content/uploads/image.jpg",
  "alt": "The alt text for the image",
  "title": "The image title text, if specified"
}

This association puts the metadata inside the content items, allowing you to overwrite it on a per-content-item basis and make use of it directly in your project’s frontend, for example by processing these images including their metadata in your static site generator.

If an image is added to a Rich Text field while the Advanced Media Library is active, the metadata is embedded into the resulting HTML. src, alt, and title will be set as the attributes of the resulting <img> tag, while all other properties will be be serialised to data-* properties on that tag. If the Rich Text field allows for captioned images and there is a field with the key of caption in the Advanced Media Library Schema, the contents of that field will also be pre-filled into the caption of that image, although they can subsequently be overridden by the user.

If a new image is uploaded directly to a content item bypassing the Media Library interface, the values entered into the metadata fields will be persisted to the metadata file – but only once. All subsequent edits to the values of those fields will happen locally in that content item. This means that if an image is added directly to an Image field and the metadata fields are left blank when “Done” is clicked, the metadata file will be empty, until it is filled from the Media Library itself, even if values were to be added to the content item afterwards.

There is no direct link to the central metadata file once the image was inserted into a content item. This also means that if the metadata is later modified, the changes won’t propagate to images in existing content items.

Making the Most of the Advanced Media Library

The Advanced Media Library is ideal for attaching meta information directly to media files in one central place, which is especially useful if files like images are used in multiple places throughout the project.

To make the most of this feature, it’s important to either upload and assign metadata to media files directly in the Media Library interface, or to immediately do so when a new image is added directly to a content item.

Used properly, the Advanced Media Library can be a huge timesaver for both content editors and developers, while providing the benefit of accessible images to the users of your project.

Coming Up

This is the last article in the section on the Media Library feature of Mattrbld, which was introduced in the Overview. You have also learned about some things to keep in mind while storing binary files in Git, as well as security concerns around SVG files.

The next section will deal with Mattrbld’s Real-Time Preview feature, which not only allows content editors to see the changes they’re making right in the final frontend, but also opens the door for many other use-cases.