[4.x] Switch to Drupal Core field_media_* fieldnames

Created on 6 March 2024, 10 months ago
Updated 9 April 2024, 8 months ago

Problem/Motivation

The following field names still have the old name from the former Drupal 8 media contrib module:

  • field_document => field_media_document
  • field_image => field_media_image
  • field_video_file => field_media_video_file

As presumably the Drupal Core names will never change in the future and some contrib modules for example also base on these field names (even if they should not do it;)) it would make sense to change our old field names to the new standard.

As there's no core API to rename field machine names, that means we'd have to write an update hook that creates the new field and afterwards migrates the old tables data to the new tables. We already did this in other modules like drowl_paragraphs, but have to ensure it doesn't break anything. Afterwards the old fields can be deleted. Here we have to ensure that the files referenced will not be deleted / cleaned up, but I think it should work.

This is a breaking change and may also need changes in other used modules or theme (where the field name might be hard-coded) so we should do this in a major release (4.x).
This should be combined with related fixes like 📌 [4.x] Unify image:field_image_caption to image:field_caption Active

Steps to reproduce

Proposed resolution

Remaining tasks

User interface changes

API changes

Data model changes

📌 Task
Status

Fixed

Version

4.0

Component

Code

Created by

🇩🇪Germany Anybody Porta Westfalica

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Merge Requests

Comments & Activities

  • Issue created by @Anybody
  • 🇩🇪Germany Anybody Porta Westfalica
  • Open on Drupal.org →
    Core: 10.2.1 + Environment: PHP 8.0 & MySQL 5.7
    last update 9 months ago
    Waiting for branch to pass
  • Status changed to Needs review 9 months ago
  • 🇩🇪Germany Grevil

    All done, please review!

  • Assigned to Grevil
  • Status changed to Needs work 9 months ago
  • 🇩🇪Germany Anybody Porta Westfalica

    The most complex part is missing: The update hook! ;)

  • Issue was unassigned.
  • Status changed to Needs review 9 months ago
  • 🇩🇪Germany Grevil

    Alright, all done and works as expected! Just tested it on a local copy of our "Vorlage" and it worked as expected!

    • All fields are renamed.
    • All revisions seem intact.
    • All media types are editable and their source_field is adjusted accordingly.
    • All view display components across all view modes seem to be correctly imported.
    • All existing medias have their images mapped to the new field.
    • The old field is deleted.

    Please review!

  • 🇩🇪Germany Anybody Porta Westfalica

    Thanks, reviewing!

  • 🇩🇪Germany Anybody Porta Westfalica

    RTBC from my side!

    @thomas.frobieter would you please quick-check the template changes?
    We should merge the new _bs templates in a separate issue then. Perhaps we might keep these old twig files in place then and rename them to _foundation, if we'll do a switch in an existing project in the future?

    I think that wouldn't be bad.

    Alternatively, we could implement a switch-case in an include-template... you decide if it's worth it. Perhaps we'll never use 4.x with foundation. Let's proceed the discussion in the separate issue anyway, you may copy over this.

  • Assigned to thomas.frobieter
  • 🇩🇪Germany Anybody Porta Westfalica
  • 🇩🇪Germany Anybody Porta Westfalica

    Revoking RTBC because of outstanding fixes.
    If this takes too much time, we'll make the config changes manually in our template to unblock it for now and update the script later, if needed.

  • Assigned to Grevil
  • Status changed to Needs work 9 months ago
  • 🇩🇪Germany Grevil

    Ok, changing every single occurence of "field_xxx" to "field_media_xxx" as it is also changed as a substring. Let's just change it manually via drush cex after update.

  • 🇩🇪Germany Grevil

    Alright, can't do much more here. We need to manually adjust the config after update.... the old field names are also embedded as substrings in many parts of the config (also in config file names! e.g. "modules/drowl_media_types/config/install/field.field.media.slide.field_image_caption.yml". If I updated them all separately, this will become a job for a whole day or two.

    Same with the translations of the view displays. There seems to be no way to not automatically delete the translations after update. This seems like a Drupal core bug, which we can not resolve, unfortunately.

    I updated the hook description accordingly:

    /**
     * Rename the media fields on the schema.
     *
     * This is done, to conform with the new drupal core naming. IMPORTANT:
     * some configs will not get properly updated through this update hook. Please
     * export your config and replace all occurences and file names containing the
     * old field names with their new counterparts as follows:
     *
     * field_document -> field_media_document
     * field_image -> field_media_image
     * field_video_file -> field_media_video_file
     *
     * Furthermore, you should diff the config before and after update, since Drupal
     * seems to unintentionally delete all available "entity_view_display"
     * translations.
     */
    

    I hope this suffices.

    PS: For our schema update helper, we should just go through all config keys of all changed configs and see if the old field name is present as a substring and replace it accordingly, but this is out of scope here

  • Issue was unassigned.
  • Status changed to Needs review 9 months ago
  • Status changed to Needs work 9 months ago
  • 🇩🇪Germany Grevil

    Just realised, that we should discuss "field_media_image_caption" and the other fields actually... Should we rename them at all? I think renaming these would make matters worse. I'll reverse the rename process for them.

  • Status changed to Needs review 9 months ago
  • 🇩🇪Germany Grevil

    Ok let's finish this. I adjusted the update hook description accordingly:

    /**
     * Rename the media fields on the schema.
     *
     * This is done, to conform with the new drupal core naming. IMPORTANT:
     * some view and form display configs will not get properly updated through this
     * update hook. Please export your config and adjust the following view_display
     * settings manually (You can simply search for the old field names
     * "field_document", "field_image" and "field_video_file" and replace them with
     * the new field names "field_media_document", "field_media_image" and
     * "field_media_video_file", but make sure they only contain that word exactly).
     *
     * Here is the list on what exactly is missing:
     *
     * hidden -> The hidden section inside both view and form displays still
     * contains old field names. You should manually adjust these to the new field.
     *
     * content (view display only) -> When a content section holds either the
     * "field_media_document" or the "field_media_video_file", you need to manually
     * adjust the settings "link_title" and / or "link_text" as it both might still
     * contain the old field name.
     *
     * third_party_settings -> The crop settings might still contain the old field
     * name. You should manually adjust these settings as well.
     *
     * Furthermore, you should diff the config before and after update, since Drupal
     * seems to unintentionally delete all available "entity_view_display"
     * translations. This is a bug in core and should
     */
    

    This will hopefully make things clear. There are too many issues with manually trying to adjust the view display directly for some reason...

  • Assigned to Grevil
  • Status changed to RTBC 9 months ago
  • Looks good to me, I'll need to replace the Templates afterward 🐛 Replace Foundation Twig Templates with Bootstrap Templates Active .

  • Status changed to Needs work 9 months ago
  • 🇩🇪Germany Grevil

    Sorry, one last thing....

  • Issue was unassigned.
  • Status changed to RTBC 9 months ago
  • 🇩🇪Germany Grevil

    Alright, just setting back to RTBC here, I forgot to revert the unintended template changes (e.g. field__image_caption).

    • Grevil committed 7d7660d7 on 4.x
      Issue #3426028 by Anybody: [4.x] Switch to Drupal Core field_media_*...
  • Status changed to Fixed 9 months ago
  • Automatically closed - issue fixed for 2 weeks with no activity.

Production build 0.71.5 2024