Problem/Motivation
TL;DR:
If we're accessing field values directly in an entity template (which is a different level and where ever possible should delegate that to the field), we at least have to ensure the preconditions are met, otherwise fall back to the default and log an error or throw a hard error.
The full story:
In our templates, for example for media documents, we expect certain structures (array / object key / values) from the selected field formatters.
As formatters are Drupals way to preprocess the field output before rendering, partially with important modifications, up to security relevant features, we should not simply skip them. Fetching the values from the entity directly may look like a reliable solution, but completely leaves out the important formatter logic.
There are several file / media download modules for Drupal, for different use cases, which we'd skip with unexpected results, if grabbing the value directly from the entity, so this is no option.
The real issue
If an unsupported formatter is selected, the template is unable to handle its unknown structures correctly.
For example, the following line is such a case:
{{ link(link_label, content.field_document.0['#url'], media_link_attributes.addClass(link_classes)) }}
https://git.drupalcode.org/project/drowl_media/-/blob/3.x/modules/drowl_...
Steps to reproduce
In a media document display (e.g. admin/structure/media/manage/document/display), for example, select a file field formatter which isn't supported by our module, like file_url_plain where we expect a file_download_link formatter.
Proposed resolution
The most clean way to solve this, would be to lock all the entity displays (e.g. media entity document) formatters to the formatters we expect. But as there's no technical solution for this in Drupal and in special cases we may even want to change that setting, this is not an option, but would guarantee the provided values are always as expected.
Proposed solution
A good solution here should be to be more strict and descriptive about the formatters we expect and support in our template logic!
In the past we made the mistake to not define the expected formatter or at least expected data structure.
This is bad, because it leads to errors which don't point to the key issue (unsupported formatter selected). Instead errors like missing keys or values are thrown, which requires a lot of debugging to find the real issue (unexpected formatter).
So we need to list the supported formatters and
a) fall back to the default output
or
b) Throw an exception if an unsupported formatter is selected for a relevant field
Alternative solution:
Another clean way to solve this, but at the same time presumably with a lot more complexity, would be to not solve this at the level of the media entity, but at the media entities' field level. Due to the added complexity, I guess we'll decide against that, but it should be mentioned, that our implementation pulls kind of internal data from fields into a different (the entity template) level.
Remaining tasks
- Prepare a list of all affected twig files in this module.
- Provide a section in the head of the twig files to define and check for the supported formatters
- Put variables differing based on the formatter into a consistent variable, e.g. "link_uri" to use it consistently below
- Otherwise fall back to default entity representation:
{{ content }}
- Test
- Release
User interface changes
None
API changes
None
Data model changes
None