Contrib.social

Change default output for file/image fields

Open on Drupal.org →
Created on 21 January 2025, 2 months ago

Problem/Motivation

The "Auto" formatter (i.e. the output from default processors) is a single HTML string.

Let's take this example: blog output from Drupal CMS -- which is a little more complicated: it's actually

  • field_featured_image = an reference to a media entity of type "image", which has
  • field_media_image = an image field

Normalized JSON for the field in the blog, currently comes out as (brackets unescaped):

    "featuredImage": {
      "element": "media-image-full",
      "mediaImage": {
        "element": "field-image",
        "content": "\n  <div class=\"wide-content field field--name-field-media-image field--type-image field--label-visually_hidden\">\n    <div class=\"field__label visually-hidden\">Image</div>\n              <div class=\"field__item\">  <img loading=\"lazy\" src=\"https://drupal-cms.ddev.site/sites/default/files/styles/large/public/2024-08/drupallogoblue.png.webp?itok=5TXp_tXc\" width=\"480\" height=\"480\" alt=\"The Drupal logo\" />\n\n\n</div>\n          </div>\n"
      }
    },

Steps to reproduce

- Install Drupal CMS + lupus_decoupled (lupus_ce_renderer would also be fine, just the test URL will differ)
- Visit the example blog entry: /ce-api/blog/2024-08/building-blog-using-drupal
- See above output

Proposed resolution

  1. Fix up the default output
  2. Make sure this works for multi-value fields.

Alternative A (or: first quick solution)

In default settings for (unsaved) CE Display config, make file/image fields use the "file" formatter instead of the "auto" formatter.

This implies: the default file/image field processor will keep outputting the above HTML.

It produces the following output for the entityreference. Note that all properties have the image field name prefix, because the formatter "flattens them into the parent (media) entity".

    "featuredImage": {
      "element": "media-image",
      "mediaImageAlt": "The Drupal logo",
      "mediaImageTitle": "",
      "mediaImageWidth": "1080",
      "mediaImageHeight": "1080",
      "mediaImageUrl": "https://drupal-cms.ddev.site/sites/default/files/2024-08/drupallogoblue.png"
    },

When rendering to markup, the relevant part of the "content" property becomes: 

<media-image-full media-image-alt=\"The Drupal logo\" media-image-title=\"\" media-image-width=\"1080\" media-image-height=\"1080\" media-image-url=\"https://drupal-cms.ddev.site/sites/default/files/2024-08/drupallogoblue.png\" slot=\"featured-image\"></media-image-full>

This currently only works for single-value image fields, because FileCeFieldFormatter extends the "flattened" formatter. It could be changed/extended; obviously multi-value fields's properties will look somewhat different.

roderik's preference is A: we want configurability for images. (At the very least, to output the URL to an image style instead of the source image.) We get configurability with a field formatter, not with a processor.

Alternative B (added for completeness)

Add a processor to override FileReferenceFieldItemListProcessor, containing the code that is currently in FileCeFieldFormatter - except also works on multi-value fields.

This implies:

  • 'Auto' does the same as 'File properties' formatter, which therefore becomes possibly-obsolete.
  • The current FileReferenceFieldItemListProcessor with its Drupal-like HTML output is unused by default. It's only be a reference for old code and will be removed in the next major version.

Remaining tasks

  • Review
    • do we still agree these above 'long' property names are fine? (I know nothing.)
  • Add tests for this formatter/processor
  • Write change record

API changes

Default (i.e. when no CE Display is present) output changes for file/image fields (regardless of the alternative chosen).

  • Needs change record.
  • IMHO breaking default output is not 100% ideal, but better than keeping 'bad' output / we should probably just do it. The currently reported install base is 66.
📌 Task
Status

Active

Version

3.0

Component

Code

Created by

🇳🇱Netherlands roderik Amsterdam,NL / Budapest,HU

Live updates comments and jobs are added and updated live.
  • Needs change record

    A change record needs to be drafted before an issue is committed. Note: Change records used to be called change notifications.

Sign in to follow issues

Merge Requests

Comments & Activities

  • Issue created by @roderik
  • Merge request !114Change default CE field formatter for single-value file/image fields → (Open) created by roderik
  • Comment 2 months ago →
    🇳🇱Netherlands roderik Amsterdam,NL / Budapest,HU

    Only adding for completeness: if we remove FileReferenceFieldItemListProcessor altogether (which is responsible for producing the Drupal-HTML output), and let it fall through to the DefaultFieldItemListProcessor, the output becomes:

        "featuredImage": {
      "element": "field-image",
      "mediaImageTargetId": "3",
      "mediaImageAlt": "The Drupal logo",
      "mediaImageTitle": "",
      "mediaImageWidth": "1080",
      "mediaImageHeight": "1080",
      "content": "3"
    },

    ...which is not good: there is no "URL" property (and instead there's an opaque entity ID).

    I'm guessing FileReferenceFieldItemListProcessor may not have been used in years (and therefore we haven't really paid attention to this old code yet), because our custom internal distro uses custom processors.

  • Comment 2 months ago →
    🇳🇱Netherlands roderik Amsterdam,NL / Budapest,HU

    @fago needs review. If the "Alternative A" output (in the issue summary) is OK for a default, then I will amend this MR to also support multi-value file/image fields.

    My first thought would be to add multi-value support to the "Flattened" formatter, so that its output becomes non-flattened for multi-value fields. But I know you've spoken out against that, so I'll instead copy some code into FileCeFieldFormatter to support the two cases, and possibly make it not extend FlattenedCeFieldFormatter anymore.

    This still means that FileCeFieldFormatter will output a somewhat different structure for single- vs multi-cardinality fields. (Just like DefaultFieldItemListProcessor does, basically.)

  • Comment 2 months ago →
    🇦🇹Austria fago Vienna

    yes, alterantive-A with customized default config is great!

    - Let's stop using legacy processors for things like this! They are mostly around for BC, we should adapt the new API for new things!

    My first thought would be to add multi-value support to the "Flattened" formatter, so that its output becomes non-flattened for multi-value fields

    yeah, I see no point in configuring a "flattened" formatter when the data is multiple. We cannot flatten it then.

    That said, the configured default behaviour for multiple image/media fields should mimic the one for single ones, but instead of a single, flattend JS object it should give us an array of similar objects. Can we configure that? Then we should simply have default-config generated based upon the field cardinality and use flattening only for single-value fields.

    . But I know you've spoken out against that, so I'll instead copy some code into FileCeFieldFormatter to support the two cases, and possibly make it not extend FlattenedCeFieldFormatter anymore.

    hm, the "flattening" issue seems generic, thus we should better avoid building it into FileCeFieldFormatter - this would mean we would have to build it into many plugins in the end imo. Can we solve it by generating suiting config as suggested above instead?

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024