Stephen Bernhardt 10:53 pm on July 28, 2020
Tags: ,   

Themes: changes related to get_custom_logo() in WordPress 5.5

Update (August 7): Removing the link from the homepage logo will be optional for WordPress 5.5, and a description of how to implement that in themes is now included below. The CSSCSS Cascading Style Sheets. selector change is still recommended for some themes.

Unlinking the custom logo on the homepage

A new unlink-homepage-logo parameter is added for the custom-logo theme support option. By default, unlink-homepage-logo is set to false, and theme authors can opt-in for the change by setting it to true. This would be the array for Twenty Twenty:

add_theme_support(
	'custom-logo',
	array(
		'height'               => $logo_height,
		'width'                => $logo_width,
		'flex-height'          => true,
		'flex-width'           => true,
		'unlink-homepage-logo' => true, // Add Here!
	)
);

If the unlink-homepage-logo parameter is set to true, logo images inserted using get_custom_logo() or the_custom_logo() will no longer link to the homepage when visitors are on that page. In an effort to maintain the styling given to the linked image, the unlinked logo image is inside a span tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.) with the same “custom-logo-link” class.

Many themes include both a logo and a site title, and then the logo is decoration alongside the site title. Because decorative images do not need their purpose to be described, the unlinked logo’s alt attribute would be empty. In cases where the site title is not present, the logo alt text may require custom handling. See code examples below for ways to override the default behavior.

Theme authors who use the a tag as a CSS selector instead of the .custom-logo-link class are encouraged to duplicate their selector to also select the span tag, or to directly select the .custom-logo-link class. A theme directory search found 183 themes that use a.custom-logo-link for styling.

Please verify whether this change makes the logo display any differently on the homepage, as well as whether the empty alt text should be appropriate.

For more details about the homepage logo link, see the related ticketticket Created for both bug reports and feature development on the bug tracker. on TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress.: #37011

New logo image attributes filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output.

Themes can use the get_custom_logo_image_attributes filter to override default attributes for the logo image or to set additional attributes.

For example, if a theme combines the logo image plus the site title (as actual text) within a link and/or heading tag, then having the site title as the logo’s alt text would be redundant. In that case, this is one way to empty the alt text so screen readers only announce the actual text:

add_filter( 'get_custom_logo_image_attributes', 'my_logo_remove_alt_text', 10, 1 );
function my_logo_remove_alt_text( $custom_logo_attr ) {
	$custom_logo_attr["alt"] = "";
	return $custom_logo_attr;
}

To check whether a user has customized the alt text before emptying it, the filter could be similar to this:

add_filter( 'get_custom_logo_image_attributes', 'my_logo_alt_custom_or_empty', 10, 2 );
function my_logo_alt_custom_or_empty( $custom_logo_attr, $custom_logo_id ) {
	$logo_alt = get_post_meta( $custom_logo_id, '_wp_attachment_image_alt', true );
	if ( empty( $logo_alt ) ) {
		$custom_logo_attr["alt"] = "";
	}
	return $custom_logo_attr;
}

If a user has customized the alt text value, this can restore it on the homepage:

add_filter( 'get_custom_logo_image_attributes', 'my_logo_homepage_maybe_alt', 10, 2 );
function my_logo_homepage_maybe_alt( $custom_logo_attr, $custom_logo_id ) {
	$logo_alt = get_post_meta( $custom_logo_id, '_wp_attachment_image_alt', true );
	if ( ! empty ( $logo_alt ) && is_front_page() ) {
		$custom_logo_attr["alt"] = $logo_alt;
	}
	return $custom_logo_attr;
}

If the site title is appropriate as a fallback on the homepage in a certain theme, a filter like this could be used:

add_filter( 'get_custom_logo_image_attributes', 'my_logo_homepage_restore_alt', 10, 2 );
function my_logo_homepage_restore_alt( $custom_logo_attr, $custom_logo_id ) {
	$logo_alt = get_post_meta( $custom_logo_id, '_wp_attachment_image_alt', true );
	if ( is_front_page() ) {
		if ( ! empty ( $logo_alt ) ) {
			$custom_logo_attr["alt"] = $logo_alt;
		} else {
			$custom_logo_attr["alt"] = get_bloginfo( 'name', 'display' );
		}
	}
	return $custom_logo_attr;
}

For more details about the filter, see the related ticket on Trac: #36640

Props: @joedolson for adding to the explanation and for review; also @audrasjb, @desrosj, @williampatton, and @poena for review

#5-5, #dev-notes