Allow setting custom image alt text in custom header image

[webmandesign]

Currently when using custom header feature and displaying an image in custom header, the ​get_header_image_tag() function sets the custom header image alt text to get_bloginfo( 'name' ) only.

It is not possible to override the alt text by setting a custom alt text for the image in Media Library.

To improve accessibility, this should be possible.

[webmandesign]

Patch fixing ticket #46124

[mukesh27]

Updated patch.

[webmandesign]

Hi @mukesh27,

Thank you for the patch. However, please note that $header->attachment_id is not always set and you are actually now removing the default get_bloginfo( 'name' ) alt text.

Please note that I have already added my own patch for the issue which is backwards compatible with get_bloginfo( 'name' ) alt text.

[mukesh27]

Hi @webmandesign,

If attached image don't have it's alt value than no need to add get_bloginfo( 'name' ) means it's not necessary to have bloginfo when alt it empty.

[webmandesign]

Hi @mukesh27,

Thank you. In that case, if there is no need for this backwards compatibility, your solution is much better. I think you don't even have to set $alt variable, you could just use 'alt' => (string) get_post_meta( $header->attachment_id, '_wp_attachment_image_alt', true );

However, please note that as it is possible to filter the image URL via get_header_image(), in my solution I also check if the image is actually the one that should have the alt text - see lines 1096 to 1101 in my patch.

Could someone from core team provide feedback if this is OK please?

[webmandesign]

By the way, if it is content image, which custom header in most cases is, the alt should be set to some value. So, it makes sense there is get_bloginfo( 'name' ) used as fallback now.

[audrasjb]

Hi,

The idea looks good at a glance. I think we should also add a fallback. Moving this to 5.2.

[webmandesign]

Hi @audrasjb,

Thank you for feedback and for accepting the fallback patch.

Could you please also provide some feedback on ticket #46134 as that is somehow related? Thanks!

[afercia]

Actually, in most of the cases the header image is purely decorative and in that case it would need an empty alt="" so it gets ignored by assistive technologies.

Only if the image adds some relevant information, the alt attribute would need to have some meaningful content to communicate the image purpose.

Can't recall off the top of my head why it is always populated with the site title. Worth reconsidering because the choice should be in the hands of the site owner but it should be made very clear that in most of the cases the alt attribute should be empty.

Also noting, as in the case of the logo image in #46127, the cropped header image is not listed in the grid view.

[webmandesign]

Hi @afercia,

Yes, you're right, all cropped images WordPress creates are affected by #46127.

In the case of empty alt text the fix could be as simple as setting it directly in $attr array as mentioned above.

But there is still an issue here as the custom header image URL could be different from attachment ID in get_header_image_tag(). That way the alt text is pulled from the attachment ID image, yet a different image could be actually displayed... (Look at the first 2 lines of the ​function code.)
My patch takes care of this issue, but the possibility of different image URL indeed complicates things here, which also relates to other ticket I've reported (#46134).

I think the alt text for the custom header image should be pulled from the actual image if possible and not overwritten or set empty by default. That way user can decide what to do.

As an example, ​in my theme on single post I'm overriding the custom header image with post featured image. And there is not an easy way of setting correct image alt text for this image now for me if I am using native WordPress functionality only. (I will solve this in my themes with a custom code eventually, but dealing with the issue I've spotted this discrepancy in WP core code.)

[audrasjb]

Hi,

The ticket is still relevant but will need some further work and/or feedback.

That would be great to get some feedback from Media component maintainers and from the Theme Team as well.

I'm moving the ticket to the next release because it's too late for 5.2, but I'll try to ask for feedbacks with the concerned people in the next couple of weeks to make sure the ticket can be handled in 5.3.

[webmandesign]

Thank you @audrasjb!

[anevins]

Mentioned in today's Media meeting and Mike's thoughts:

1) It’d be ideal if it core longer filled alt if it shouldn’t have an alt.
2) I wonder where the ideal place for this to be exposed to users, if at all, would be — whether alt of the parent image would be appropriate, or not at all, for instance.
3) I wonder if anyone is already working around this and how.

My thoughts:

Although @afercia mentions in most use cases the purpose of the header image is entirely decorative, I've found that most users in the wild actually put information inside header images - from my experience on the support forums.

I would like to see the alt text blank and make it the content editor's responsibility, but I'm happy with it prepopulated as long as it can be left empty too. Which ever is easier.

[kirasong]

I very poorly worded 2) in the chat. A bit of clarification:

• I think users should be able to set the header alt somehow, but am uncertain of the optimal UX for that.
• We could search for/retrieve the alt of the parent image, but that alt might not be correct for the cropped header.

[karmatosed]

This was discussed in this week's design triage. Just to get a few confirmations, you can right now edit alt text on custom headers. This is why having a UI for this seemed to already exist. In this ticket is that being recommended to go?

[afercia]

Not sure there's an UI to edit the custom header image alt text.

Testing with Twenty Seventeen

• customiser > Header Media > Add new image
• the media modal dialog "Choose Image" opens
• select an image
• I can edit the alt text in the right sidebar > Attachment details
• however, once inserted, the header image has always the site name as alt text, in my case: alt="WordPress develop"

@nrqsnchz checking the discussion on Slack > design I see you mentioned you successfully set the alt text, can you please share more details?

Worth also mentioning that even if this worked, editing the alt text from the media modal dialog isn't ideal because it changes the alt text "globally". There should be a UI to edit the alt text only in for the Header context.

[nrqsnchz]

I think you're right @afercia and I was not thorough when testing. While I was able to set an alt text to the image:

the alt text does not appear on the actual HTML:

[afercia]

Discussed during today's accessibility bug-scrub. Agreed the UI is misleading users because:

• when inserting the header image, the UI shows the alt text field with the text set by the user
• but then, the alt text that is actually printed out in the markup is the site name

Considered two options:

• just let the header image take the alt text from the media library: no need for a new UI
• the above + a new UI to override the alt text from the Media Library so that users have the ability to set a custom alt text without changing the “global” one

The first option would be a good first step and doesn't need design.

The second option could be implemented at a later stage and would need design for a new UI. Will split in a separate ticket so going to remove the needs-design-feedback keyword.

Also, users should be allowed to set an empty alt text alt="". Not sure there should be a fallback to the site name.

[audrasjb]

The above sound nice to me. I'm all in favor of using the alt text of the existing image in the media library.
However, I tested the last patch from @mukesh27 and it's not working for cropped images since once cropped, the alt text doesn't exists anymore.

[webmandesign]

@audrasjb As far as I know, you should be able to set the cropped image alt text (and other options) in ​list view of media library. Cropped images are available only there, but I actually logged a ticket for this behavior too.

[afercia]

Discussed during today's accessibility bug scrub. Agreed to change this ticket from "enhancement" to "bug" as anything related to the image alt attribute is of fundamental importance for accessibility.

[audrasjb]

This ticket still needs some work and improvements. Moving it to the future release.

[sabernhardt]

possible first step

[sabernhardt]

In 46124.2.patch, a conditional statement searches for either of these two items:

1. a customized header "alt_text" value (using a filter not yet available - see tickets #38942 and #46134)
2. an uploaded image's "attachment_id" to take its alt text, if provided (it's possible but not easy to set this yet - see ticket:46127)

Then if neither is found, the alt text is simply empty.

[ilovewpcom]

#49503 was marked as a duplicate.

[SergeyBiryukov]

#53662 was marked as a duplicate.

[sabernhardt]

I'd like to revisit this in the upcoming cycle.

[sabernhardt]

The patch is revised to prefer user-defined alt text and fall back to the empty attribute.

In #21389, the site name was chosen to avoid empty links because Twenty Sixteen had a linked header image. However, this function does not affect Twenty Sixteen; it would continue to include the site name as alt text.

​Four of these 76 themes have an option to link the image, using the get_header_image_tag filter.

Looking at dozens of themes under the following searches, I did not notice any others that would create an empty link with this change.
​the_custom_header_markup
​get_custom_header_markup
​get_header_image
​get_custom_header

If the site name is still a safer fallback, the patch could be updated again.

[joedolson]

While choosing a fallback to an empty alt attribute means that some themes could create empty links on the header images, it sounds like that's uncommon. The site owners are *able* to create correct alt text, and that's realistically the best we can do.

I'd prefer an empty alt attribute to an incorrect alt attribute; and using the site name will almost certainly repeat text already in the title element, the logo, the site title, and other contexts.

[sabernhardt]

Notes about the conditional statement in 46124.3.patch​:

1. It needs to check whether the header object has an attachment_id to avoid errors when using a theme's suggested headers.
2. I don't remember why the second condition was important. It might be a remnant from another iteration, involving the site name as a fallback. Unless that condition is clearly unnecessary with the empty alt attribute fallback, though, I recommend keeping it (in case I stumbled upon an error I can't find again).

[joedolson]

The second condition doesn't seem important; if the alt attribute was empty, it would just be the same as the else condition, effectively. I'm inclined to omit it, and see if anything gets chased out during RC, since neither of us can think of any reason it would be there.

[sabernhardt]

OK, there is a precedent for checking empty alt and then assigning an empty string in the get_attachment_fields_to_edit function. So get_post_meta might return something other than either the user-defined text or an empty string (or, at least, there was a concern when adding that code in r12055).

(Thanks @webzunft for bringing my attention to the media.php file today.)

[joedolson]

OK. In get_attachment_fields_to_edit it's about ensuring that the value is a string, I think; but this patch isn't doing that. This patch will use it as long as it's any non-empty value; which would include non-string values. This looks like it would assign the alt attribute as an empty array if that's what the function returned.

[sabernhardt]

@joedolson Would checking is_string be a good replacement for that, or do you still prefer removing the second condition?

[joedolson]

I think there's a reasonable argument for ensuring the value is a string; it just needs to be updated to ensure that's actually happening. is_string() would probably do the job respectably.

[Boniu91]

@sabernhardt would you mind sharing the testing steps or acceptance criteria? We'll test the patch during the Test Scrub then.

[sabernhardt]

Testing

1. Before applying patch, activate Twenty Seventeen or another theme that uses either the_custom_header_markup or get_custom_header_markup.
2. Go to Appearance -> Customize and then Header Media (or directly to Appearance -> Header).
3. Select the "Randomize suggested headers" option and click Publish.
4. Visit the site and either inspect the image element or view the full page source. Verify that the header image has the site title in the alt attribute.
5. Return to the Customizer and click the "Add new image" button.
6. Upload a new image and set special alternative text.
7. Click the "Select and crop" button, then click either "Crop image" or "Skip cropping" to set the header image, and click Publish. If you chose to crop the image, you need to go to the Media Library to set alternative text for the cropped image.
8. Visit the site and verify that the header image again has the site title in the alt attribute instead of the text you assigned.
9. Apply the patch.
10. Go to the Header Media section of the Customizer.
11. Select the "Randomize suggested headers" option and click Publish.
12. Visit the site and verify that the random header image now has an empty alt="" attribute.
13. Return to the Customizer and click the "Add new image" button.
14. Select the same image you uploaded earlier and click Publish.
15. Visit the site and verify that the header image now has the alt text you assigned to it.
16. Return to the Customizer, upload a new image, and set different alternative text.
17. Visit the site and verify that this header image has the different alt text you assigned.
18. (Try any other scenario you might find.)

[Boniu91]

@sabernhardt I was just testing the patch and I think there's a UX problem, please find my TR below:

Test Report

Env

• WordPress 5.8.2
• Chrome 96.0.4664.45
• Windows 10
• Theme: Twenty Seventeen

Steps to test

1. Patch is applied
2. Go to the Customizer and Header section
3. Add new image
4. Add alt text
5. Crop the image
6. Publish the changes
7. Check the source, alt is empty

Cropped image doesn't inherit alt text from the orginal one!

Before applying the patch, we'd have header image with site description alt. After patch, it'll be empty in this scenario, which in my opinion could be happening often. Is this behaviour expected?

[sabernhardt]

@Boniu91 Thanks for catching my mistake in the instructions. Setting the cropped image's alt text still requires going to the Media Library. (#46127 enabled setting the text in media's grid view, not when cropping.) #37750 is a separate ticket for retaining the properties in a cropped image.

[audrasjb]

Before patch

[audrasjb]

After patch: alt text is correctly applied to the image

[audrasjb]

Thank you for the updated testing info @sabernhardt. I was able to reproduce the issue then to fix it with the proposed patch.

Marking this for commit.

Trac ticket: https://core.trac.wordpress.org/ticket/46124

[audrasjb]

Tests are passing. Committing right now.

[audrasjb]

In 52256:

Media: Allow setting custom image alt text in custom header image.

This change applies the alternative text assigned to the custom header image, if available. Otherwise, it leaves it empty. It fixes an issue where the alternative text was always the site title, which is not relevant in most use cases.

Props webmandesign, mukesh27, afercia, anevins, mikeschroder, nrqsnchz, audrasjb, sabernhardt, joedolson, Boniu91.
Fixes #46124.

Committed via https://core.trac.wordpress.org/changeset/52256.

[sabernhardt]

Dev notes published:

• ​Theme-focused changes: Custom header image attributes
• ​Note for Twenty Seventeen users