[drupalMedia] CKEditor 5 allow caption/linking/view mode/alignment functionality to be enabled per bundle

Created on 1 February 2024, 11 months ago
Updated 1 July 2024, 5 months ago

Problem/Motivation

By default, CKEditor 5 provides buttons in the drupalMedia toolbar (when editing an embedded item) that allow for the following plugins to transform the media embed:

  • Caption
  • Link
  • View mode
  • Alignment

Additionally, a plugin for mediaimagetextalternative adds the ability to set alternative text for media types with an image file field.

The default installation of media and media library creates five commonly used media types:

  • Audio
  • Document
  • Image
  • Remote video
  • Video

Adding a link to media could in some cases be destructive to how the media functions. Editors that can embed a document (which would typically have a download link defined in the view mode. Links would also break the typical function for rendered media types such as video, audio, or embeds such as social media, charts, or maps.

Site builders should be able to configure media embeds to exclude plugin buttons that create incorrect HTML or a confusing editor experience. Examples for each "transformation" where it doesn't make sense for some media type:

I can probably train editors to work around all of these scenarios, but if I could hide the feature I don't want them to use, they will be much happier and it lowers the chance of confusion.

Steps to reproduce

  1. Enable Media and Media Library
  2. Configure the Basic HTML text format to use CKEditor 5 will the following common settings:
    • Add Drupal Media to the active toolbar.
    • Enable "Allow the user to override the default view mode".
    • Enable the filter for "Embed media".
    • Enable the filter for "Align images" (it's a bit odd that this filter is not titled "Align media").
    • Enable the filter for "Caption images" (it's a bit odd that this filter is not titled "Caption media").
    • In the embed media filter settings, select at least two view modes under "View modes selectable in the 'Edit media' dialog".
    • In a "Basic page" or similar content type, use the Drupal Media button in the CKEditor 5 toolbar to embed media other than an image.
    • After embedding the media, click the media item to show the CKEditor balloon toolbar for the media entity

    At this point, you'll see all the extraneous settings that may not make sense outside of the context of an image media entity.

    Proposed resolution

    A possible resolution would be to add per toolbar button/plugin settings to the media configuration or the embed media filter settings. For example:

    Merge request link

    Remaining tasks

    User interface changes

    API changes

    Data model changes

    Release notes snippet

Feature request
Status

Active

Version

11.0 🔥

Component
CKEditor 5 

Last updated about 23 hours ago

Created by

🇺🇸United States joshuami Portland, OR

Live updates comments and jobs are added and updated live.
  • JavaScript

    Affects the content, performance, or handling of Javascript.

  • Usability

    Makes Drupal easier to use. Preferred over UX, D7UX, etc.

  • Needs tests

    The change is currently missing an automated test that fails when run with the original code, and succeeds when the bug has been fixed.

Sign in to follow issues

Comments & Activities

  • Issue created by @joshuami
  • 🇺🇸United States joshuami Portland, OR

    It's worth noting that nearly all of Media and Media Library's test coverage and development have been focused on images. The result is that new features for images tend to be added to all media types (whether they are appropriate or not). There are many more areas where adding or removing embed options would make other media types such as video, audio, documents, maps, charts (and more) significantly more usable and accessible. Overriding this experience was much easier in CKEditor 4 with the entity embed dialog (modal) as it allowed for Drupal form alters per media type. With CKEditor 5, this all has to be considered as part of the plugin architecture for the balloon toolbar that appears on each embedded media item.

  • 🇺🇸United States joshuami Portland, OR
  • Status changed to Postponed: needs info 10 months ago
  • 🇧🇪Belgium wim leers Ghent 🇧🇪🇪🇺

    Very interesting and astute observation, @joshuami! 👏🙈

    Audio might have a caption, but it would be rare.

    Would you expect only a player, and no caption? I think a caption can be reasonable here.

    I cannot think of a use case or semantic approach for captioning documents when embedded.

    I can: an accompanying description? Just like one could have

    <figure>
      <blockquote>An epic quote here</blockquote>
      <figcaption>Explanation contextualizing the quote.</blockquote>
    

    Is that not reasonable/realistic? 🤔

  • 🇺🇸United States joshuami Portland, OR

    @Wim Leers, thanks for asking the clarifying questions.

    Audio might have a caption, but it would be rare.

    Okay, "rare" may have been an overstatement. 😄

    Originally, I was thinking of documents as not really something you would semantically mark up as a figure, but you might have a point. Reading through the HTML 5 definition of flow content (https://www.w3.org/TR/2011/WD-html5-author-20110809/content-models.html#...), I guess it would be a correct usage to wrap a document media link in a figure and provide a figcaption as the description.

    I've certainly implemented a description field on documents and used the display mode template to output a description with an aria-describedby on the document. There wasn't a way to add a caption to a document in earlier releases of media library with CKEditor 4, so I hadn't really given it thought to using it.

    Generally, a little more configurability for what appears in the drupalmedia toolbar would be helpful. There are so many use cases were the

    Updated the issue summary to focus on the link button as that is the larger issue for creating patterns that will break media players and document download links.

  • 🇧🇪Belgium wim leers Ghent 🇧🇪🇪🇺

    Generally, a little more configurability for what appears in the drupalmedia toolbar would be helpful. There are so many use cases were the

    You're leaving me hanging there! 🤣 Where were you going with that? 😄

    Could you please also list one example for each of Caption/Link/View mode/Alignment to show why these features only make sense sometimes? 🙏

  • 🇺🇸United States joshuami Portland, OR

    You're leaving me hanging there! 🤣 Where were you going with that? 😄

    😆 At least you can tell it wasn't generated by AI.

    That was a few days ago, so I can only guess at what I was going to say, but it would have been something like this. 🤔

    It would be nice to be able to choose whether or not caption, link, display mode, and even alignment appear per each type of media. As a developer, I can put all sorts of things into a media entity display mode. Here are some examples of where I might want to prevent one of the default toolbar items.

    Caption: I may choose to provide a caption rather than have CKEditor provide the caption functionality because I want to include license and attribution meta data in the caption.

    Link: I might want to prevent editors from adding a link around an image to discourage the creation of gaudy image "buttons" that break from the style guide. I would definitely want to hide the link functionality from documents, audio, and video because it would break the functionality and lead to more support requests. (Sorry, that's two examples 😜)

    Display mode: If there is only one display mode for a media type, I might want to hide that display mode to reduce the visual complexity for my editors.

    Alignment: I might want to hide alignment from videos because I want my editors to always embed full-width videos and the align left and right forces a 50% width by default.

    I can probably train editors to work around all of these scenarios, but if I could hide the feature I don't want them to use, they will be much happier and it lowers the chance of confusion.

  • Status changed to Active 10 months ago
  • 🇧🇪Belgium wim leers Ghent 🇧🇪🇪🇺

    Moving #7 into the issue summary 👍

  • 🇧🇪Belgium wim leers Ghent 🇧🇪🇪🇺

    Thank you — that's very helpful. I agree this would significantly increase usability (as well as accessibility: far less "noise" to sift through).

    This will require

    1. significantly expanding the configuration for the media_embed plugin
    2. updating the CKEditor 5 JS plugin to respect this
    3. test coverage to prove it's all working

    Actually … it kind of depends whether these settings belong on the media_embed filter or in the CKEditor 5 plugin. If it's in the filter settings, then the filter would be able to enforce those restrictions (for example, to avoid those gaudy image buttons you're referring to). If it's in the CKEditor 5 plugin settings, then it'd be "UI-only-enforcement": we wouldn't offer the UI affordances, but they might set those attributes in the Source Editing view anyway.

    Thoughts on that?

  • 🇺🇸United States joshuami Portland, OR

    That is a good question. I think just the CKEditor plugin would meet the need. Adjusting the media_embed filter for all possible configurations would get complicated quickly. And, there might be a need to support legacy content that used one of the disabled features.

    A disallowed patterns filter would a pretty slick feature as well. It would be nice to strip empty elements like headings and paragraphs that editors always seem to be leaving behind. I'll have to think about writing that up as a separate issue. 😁

  • 🇧🇪Belgium wim leers Ghent 🇧🇪🇪🇺

    And, there might be a need to support legacy content that used one of the disabled features.

    Correct. I am glad you surfaced that. I was curious if that'd be a concern or not — hence I intentionally omitted it from #9.

    So it sounds like you're thinking about UI-only enforcement?

  • 🇺🇸United States joshuami Portland, OR

    I think UI-only enforcement would be sufficient.

  • 🇺🇸United States chuck_theobald

    I cannot create a link around a Drupal Media Image in content. When inserting an image, I have the link button in the insert media mini-window and it saves without complaint, but when rendered, the link is stripped out. I am running Drupal 9 and 10 with CKEditor 5. Not sure what I am missing, some module or the order of filters, which is:

    • Convert line breaks into HTML (i.e.
      and

      )

    • Linkit URL converter
    • Convert URLs into links
    • Align images
    • Caption images
    • Embed media
    • Display embedded entities
    • Apply responsive behavior to HTML tables.
    • Display UO Calendar Entities
    • Correct faulty and chopped off HTML
    • Advanced Insert View

    Advice wold be greatly appreciated.

  • 🇺🇸United States chuck_theobald

    The solution to my issue in #13 has been identified by caspervoogt (#57 in https://www.drupal.org/project/drupal/issues/3075527 🐛 Adding links around embedded media through CKEditor might lead to invalid/complex markup when rendered Active ) and works for my sites as well. Odd side-effect. Removing that filter does not appear to negatively affect the content manager experience.

Production build 0.71.5 2024