New filter for header image tag attributes

[junaidbhura]

There is currently no way to filter the attributes of the header image tag before it is used to build the header image tag HTML in the get_header_image_tag() function.

I've attached a diff to solve this problem by adding a new 'get_header_image_tag_attributes' filter.

[obenland]

I'm not sure a filter is really needed here since the function accepts an array of attributes that override any defaults. Am I missing something?

[junaidbhura]

Replying to obenland:

I'm not sure a filter is really needed here since the function accepts an array of attributes that override any defaults. Am I missing something?

The idea is to have this work similar to wp_get_attachment_image_attributes . There is currently no way to modify the header image's attributes like a normal attachment image.

There is a get_header_image_tag filter, but that is applied after the image's HTML has already been built.

[sabernhardt]

Related/duplicate: #46134

[sabernhardt]

Related/duplicate: #34644

[sabernhardt]

#34644 was marked as a duplicate.

[sabernhardt]

With 34644.patch, @sebastian.pisula made another version of this filter to add a class or similar attribute. However, I like how 38942.diff​ includes the $header argument.

I tried these two implementations:

function edit_header_alt_with_url( $attr, $header ) {
	if ( '.jpg' === substr( $header->url, -4 ) ) {
		$attr['alt'] = 'new alt';
	}
	return $attr;
}
add_filter( 'get_header_image_tag_attributes', 'edit_header_alt_with_url', 10, 2 );

function header_image_add_class( $attr ) {
	if ( isset( $attr['class'] ) ) {
		$attr['class'] .= ' special classes';
	} else {
		$attr['class'] = 'special classes';
	}
	return $attr;
}
add_filter( 'get_header_image_tag_attributes', 'header_image_add_class', 10, 1 );

[audrasjb]

Themes: Introduce get_header_image_tag_attributes hook to filter the list of header image attributes.

[audrasjb]

Patch refreshed against trunk + refreshed docblock

[chaion07]

Hi @junaidbhura! Thank you for reporting this. This ticket was discussed during a recent ​Bug-scrub session. Based on the feedback received we're adding the commit keyword. Having Unit Test would also be a good idea. Thanks!

Props to @costdev & @audrasjb

[johnjamesjacoby]

In 51978:

Themes: Introduce get_header_image_tag_attributes hook.

This change adds a filter inside of the get_header_image_tag() function allowing developers to filter the attributes of the header image HTML tag before they are escaped, concatenated, and returned.

Before this change, it was not possible to externally and preemptively intercept this array of attributes. After this change, these attributes can now be easily filtered, matching it nicely to the wp_get_attachment_image_attributes hook.

Props audrasjb, chaion07, junaidbhura, sabernhardt.

Fixes #38942.

[johnbillion]

In 52034:

Docs: Fix some docblock syntax errors and add a missing canonical reference.

See #53399, #52867, #38942, #53668

[sabernhardt]

Dev note published:
​Theme-focused changes: Custom header image attributes