Replacing the image in an image block resets its caption

[strarsis]

Description

When the image of an image block is replaced, the current caption of the block is reset to the title of the new image.

This happened multiple times now in the past and can be missed by the editor, resulting in missing text.
As this behavior is destructive, it would be nice if it can be changed to either keeping the custom caption text or by adding a toggle or prompting the user whether the caption should be replaced by the title of the new image.

Step-by-step reproduction instructions

1. Insert an image block with a selected image.
2. Add a custom caption to that image block.
3. Replace the image of that image block with another image.
   Note that the caption of that image block is now changed.

Screenshots, screen recording, code snippet

No response

Environment info

• WordPress 6.0.1
• Gutenberg Plugin 13.7.3
• Latest Chrome, Windows 10 x64

Please confirm that you have searched existing issues in the repo.

Yes

Please confirm that you have tested with all plugins deactivated except Gutenberg.

Yes

[talldan]

It looks like this regressed as there was a previous fix for it - #19636.

It would be good to add some automated testing next time this is solved to prevent future regressions.

[Mamaduka]

I think the editor only preserves a caption if the replacement image doesn't have one.

gutenberg/packages/block-library/src/image/edit.js

Lines 162 to 166 in 6d62fa9

	// If a caption text was meanwhile written by the user,
	// make sure the text is not overwritten by empty captions.
	if ( captionRef.current && ! get( mediaAttributes, [ 'caption' ] ) ) {
	mediaAttributes = omit( mediaAttributes, [ 'caption' ] );
	}

[ntsekouras]

I think the editor only preserves a caption if the replacement image doesn't have one.

@Mamaduka is right and personally it makes sense to me when we replace an image. I think a prompt for this use case would be a bit excessive but 🤷 . Maybe a toaster notification in that case could be less intrusive? --cc @jameskoster

[jameskoster]

Thanks for the ping.

Whether the caption should be retained really depends on the nature of the replacement.

If you're swapping between totally unrelated images then it makes sense to remove it. But if you're replacing the current image with a slightly different version, or updating something like a product image after a new release, then you'd likely want the caption to remain.

[strarsis]

The problem is that the image caption is replaced without warning. At least a notification should notify the user that it has been automatically changed.

The image caption is not a static field but a text input that the user can change. This conveys that the caption is customizable and shouldn't just change like a static field.

IMHO when the caption had been modified once, subsequent automatic changes should all be confirmed by the user.
What about a "Set current media title/alt text as caption" toolbar button?

[t-hamano]

There are two related issues:

• Image Block: Replacing Image can alter caption settings #66979: In this issue, it is suggested that the caption should not be updated when replacing an image with another one that has a caption.
• Image block: caption persists when replacing image #62468: In this issue, when replacing an image with one that doesn't have a caption, it is proposed to not render the caption, rather than keeping the caption from the previous image.

[MadtownLems]

Thanks for bringing attention to those other issues all in one place. I think this is a very interesting topic to discuss!

I think there are two main parts to this:

1. when (if ever) should replacing an image change the captions display setting?
2. when (if ever) should replacing an image change the caption text?

(but note that are intertwined.)

I believe the answer to (1) - when should the setting change - is never. Especially with the rise of Patterns that use Images, I think that not displaying the caption for an Image is largely an intentional choice. When a user simply wants to swap out one image for another, I think it's very unlikely that they suddenly want the caption displayed with the Image.

As for (2) - when the should the caption text change - my proposal would be only:
When the original image is already displaying a caption, and it is replaced by an image that already has a caption set (in the Media Library), then update the caption text to use that of the new Image.

I also believe that if an Image is already displaying a caption, and is replaced by an Image that does NOT contain a caption, then no caption should be displayed. My reasoning for this is that the caption was intended for the original image - not this newly introduced one. While technically this could be considered changing the setting (going against what I said for (1), I see it more as using the new image's caption - which in this case is null.

[afercia]

I'd like to report a couple considerations from the related (now closed) #62468.

Specifically from this comment: #62468 (comment)

• As a user, when I replace an image with a new one that has its own caption, I expect the [new] caption to be there.
• Also, comparing the behavior with the one that always existed in WordPress and now it's in the Classic editor, this is a change in the expected behavior that should have been considered a little more deeply IMHO.

[Mamaduka]

As a user, when I replace an image with a new one that has its own caption, I expect the [new] caption to be there.

I thought the caption was (can be) relative to the post content and not necessarily related to media content. Am I missing something?

Also, comparing the behavior with the one that always existed in WordPress and now it's in the Classic editor, this is a change in the expected behavior that should have been considered a little more deeply IMHO.

I should politely disagree here. The Block editor isn't a drop-in replacement for Classic. If the latter is used to handle things in a certain way, it doesn't mean that the Block editor should do the same or that Classic was handling it correctly.

The best option here would be to fix this in a way that's intuitive for most users - 80/20.

[afercia]

I thought the caption was (can be) relative to the post content and not necessarily related to media content. Am I missing something?

The caption is meant to be a description of the figure element that, in this case, contains the media.
https://html.spec.whatwg.org/multipage/grouping-content.html#the-figcaption-element

The figcaption element represents a caption or legend for the rest of the contents of the figcaption element's parent figure element, if any.

The Block editor isn't a drop-in replacement for Classic.

Absolutely. But, when a behavior that has been in place for ages changes. that should be 1. user tested 2. communicated as a breaking change in the behavior.

[t-hamano]

We may need more feedback on what behavior makes sense for most users.

cc @WordPress/outreach

[markhowellsmead]

IMO the default behaviour should be for a existing caption to remain as-is. Swapping out an image editorially is rarely done because of a need for completely different content: it's most often because the user has a better image to show for the same information.

As a user, I'd prefer to see the editor requesting of me, “Remove existing image caption?” with a “yes/no” choice. In my experience with training clients, toast messages in the corner of the screen are often missed. A blocker element (modal) would make the most sense to me.

[carolinan]

Different users have different needs. A person who is creating a new post and inserting an existing pattern that they want to edit will have a different workflow than the one described above. So will a person who is editing locked content, who may be able to replace an image but not the caption.

[Mamaduka]

So will a person who is editing locked content, who may be able to replace an image but not the caption.

The caption attribute is marked as content, so it's editable and will be treated as any other editable attribute.

I think there would be as many expectations for this workflow as WP has users. The point here is to agree on something that feels intuitive and update the current behavior. Otherwise, this is going to turn into one of those evergreen issues.

[MadtownLems]

Agreed that there are lots of different workflows, and also lots of different ways that people use captions. Some use it as additional alt text, some use it to provide metadata about the image (source/attribution), some use it for just general information related to the image ("There are lots of water activities at our camp!").

To me, the most important bit is not having a caption appear where there wasn't one before, ESPECIALLY in the context of patterns. That's what originally raised the caption behavior for me: we have lots of block patterns that feature images as elements of design, and I noticed that some of our content providers ended up with captions awkwardly presented because they switched images and likely didn't even realize that they caption suddenly became visible.

[t-hamano]

I don't have a strong opinion on what the behavior should be, but I think it's better to keep the logic as simple as possible. Personally, I would prefer to either always replace the caption with a new image or never replace it, whatever the scenario.

I think that the more context-specific logic we add to cover as many scenarios as possible, the harder it becomes for users to understand why something is happening.

[MadtownLems]

Personally, I would prefer to either always replace the caption with a new image or never replace it, whatever the scenario.

Given this, my suggestion would be to ALWAYS replace the caption. I think it has the least chance of a caption accidentally being just totally wrong (eg referring to the wrong image).

If you never replace the caption, you risk situations like a photo of a duck enjoying a lovely swim, with the caption "Duck enjoying a swim at Lake Something, photo by Peter Photographer" - swap out the image to something other than a duck, at a different location, taken by a different photographer - but the caption doesn't update, and now the caption is all kinds of wrong.

But I maintain that possibly the single most important part here is to ensure that the Caption doesn't suddenly become displayed where it was not previously. So if I have an Image Block with no caption showing (whether the Image doesn't even have a caption in the Media Library at all OR it does but was not currently being shown), and switching to an Image that DOES have a caption set in the media library should NOT start showing the caption automatically. That should have to be opted into manually by clicking the caption setting in the block toolbar.

[markhowellsmead]

If you never replace the caption, you risk situations like a photo of a duck enjoying a lovely swim, with the caption "Duck enjoying a swim at Lake Something, photo by Peter Photographer" - swap out the image to something other than a duck, at a different location, taken by a different photographer - but the caption doesn't update, and now the caption is all kinds of wrong.

Isn't this getting a little obtuse and over-engineered?

If a user swaps out an image, surely they have the wit to see the caption which appears right next to the image and change it if necessary. What if the caption remains valid with a different picture of a duck? The user would then have to re-enter the same caption. That would be very annoying. I still don't think that it's necessary to enforce a behaviour on users against their wishes. If this is really necessary, then a prompt should ask the user whether they want the pre-existing caption to be removed or not.

[markhowellsmead]

I think that the more context-specific logic we add to cover as many scenarios as possible, the harder it becomes for users to understand why something is happening.

YES; automatic changes to content which can't be explained to or understood by the user should be decreasing, not increasing. Content management is complex enough for lay-people, without us making decisions for them without explaining the reasoning.

[strarsis]

So is the caption intrinsically linked to the media, or is it independent from it?
Going one step further: What about making the caption "custom"/independent/unlinked in the moment where the user changes the caption from its value that was prepoluated by the inserted media caption.

[markhowellsmead]

So is the caption intrinsically linked to the media, or is it independent from it? Going one step further: What about making the caption "custom"/independent/unlinked in the moment where the user changes the caption from its value that was prepoluated by the inserted media caption.

The caption can be defined on the media entry, but once the media item has been inserted into the content, then it's freely modifiable and no longer technically connected to the caption in the media library.

[strarsis]

When the caption was changed after media insertion, it is then unlinked from the original media.
Well, then the caption should not change when the media is replaced, as it does not represent a media caption anymore.

[strarsis]

I am not sure whether I have seen such an UI pattern already in Gutenberg:
A sync-option next to the caption, which disables the caption input and shows the media caption when enabled.
When the sync-option is disabled, the caption becomes editable, pre-populated with the media caption.
This appears to be the best solution as it does not have any compromises - except for this sync-option UI pattern.