Block Editor Keyboard Shortcuts in WordPress 5.4

In WordPress 5.4 a new package called @wordpress/keyboard-shortcuts has been introduced to centralize the registration/removal and documentation of the available keyboard shortcuts in the block editor screen.

Registering shortcuts

Registration of keyboard shortcuts should happen when first loading the screen/plugin. This can be achieved by calling the registerShortcut action.

wp.data.dispatch( 'core/keyboard-shortcuts' ).registerShortcut( {
	// Shortcut name (identifier)
	name: 'plugin/shortcut-name',

 	// Catergory (global, block or selection)
	category: 'block',

	// Description 
	description: 'Short description of your shortcut.',

	// The key combination used to trigger the shortcut
	// Could be just a single character or a character with
	// a modifier.
	keyCombination: {
		modifier: 'primaryAlt',
		character: 't',
	},

	// Some shortcuts can be triggered using several 
	// key combination, the aliases array is used to define
	// the alternative combinations
	aliases: [
		{
			modifier: 'primary',
			character: 'i',
		},
	],
} );

Registering a shortcut automatically add it to the keyboard shortcuts help modal to ensure its discoverability.

Implementing the keyboard shortcut behavior

The @wordpress/keyboard-shortcuts package also provides the useShortcut React hook to define the behavior triggered by the keyboard shortcuts.

import { useShortcut } from '@wordpress/keyboard-shortcuts';
import { useCallback } from '@wordpress/element';

const MyComponent = () => {
	useShortcut(
		// Shortcut name
		'plugin/shortcut-name',

		// Shortcut callback
		useCallback(
			( event ) => {
				// Do something when the keyboard 
				// shortcut is triggered
			},
			[]
		)
	);
}

Using this React hook instead of a custom implementation comes with a few advantages:

  • If the shortcut is unregistered by a third-party plugin, the callback is just ignored.
  • The shortcut key combination can be modified at runtime and the callback will still be called properly.

Removing existing shortcuts

Registered shortcuts can also be unregistered (and potentially replaced) by third-party plugins

wp.data.dispatch( 'core/keyboard-shortcuts' ).unregisterShortcut(
	'plugin/shortcut-name'
);

Next steps

In the next releases, this package will also allow offering a centralized UI to modify the keyboard shortcuts per user.

#5-4, #accessibility, #block-editor, #dev-notes

Enhancements to favicon handling in WordPress 5.4

WordPress 3.0 introduced wp_favicon_request() to avoid the performance hit that comes from serving a full 404 page on every favicon request. While that function works as intended, it doesn’t offer enough flexibility.

As of WordPress 5.4, theme and plugin authors can manage favicon requests much more flexibly, with the following logic:

  • If there is a Site Icon set in Customizer, redirect /favicon.ico requests to that icon.
  • Otherwise, use the WordPress logo as a default icon.
  • If a physical /favicon.ico file exists, do nothing and let the server handle the request.

This logic will only work if WordPress is installed in the root directory.

With these changes, /favicon.ico handling is now more consistent with /robots.txt requests.

New functions & hooks

WordPress 5.4 introduces a bunch of new functions and hooks for favicon handling:

  • is_favicon() conditional tag to complement is_robots().
  • do_favicon action to complement do_robots and use it in template loader. This hook will be fired when the template loader determines a favicon request.
  • do_favicon() function, hooked to the above action by default, to complement do_robots().
  • do_faviconico action to complement do_robotstxt, for plugins and themes to override the default behavior. This hook will be fired when displaying the favicon file.

With the above logic, do_favicon redirects to the Site Icon if it exists, or to WordPress logo as a default icon, using the following code:

function do_favicon() {
    /**
     * Fires when serving the favicon.ico file.
     *
     * @since 5.4.0
     */
    do_action( 'do_faviconico' );

    wp_redirect( get_site_icon_url( 32, admin_url( 'images/w-logo-blue.png' ) ) );
    exit;
}

Themes and plugins developers can use do_faviconico action to override the default behavior.

Deprecations

  • wp_favicon_request() is now deprecated in favor of do_favicon().

For reference, see the related ticket on WordPress Core Trac: #47398

#5-4, #dev-notes, #favicon

WordPress 5.4 introduces apply_shortcodes() as an alias for do_shortcode()

WordPress 5.4 introduces a new function – apply_shortcodes(). It’s an alias for the current do_shortcode() function.

The semantics of do_* implies the function displays the result of the shortcode. But that’s not actually the case. In fact, do_shortcode() needs to be echoed to display its result.

Here is the current implementation:

echo do_shortcode( '[wporg]My Text[/wporg]' );
// Displays the result of the shortcode

Semantically, we should be able to do this:

do_shortcode( '[wporg]My Text[/wporg]' );
// but it doesn’t display anything…

As you may know, do_shortcode() is used in countless plugins and themes. So there is currently no option to deprecate it. But if the community can start building a consensus around the alias, apply_shortcodes(), then deprecation may eventually become a real option in the future.

There is a precedent for making this move. It’s the same process the core team followed with get_permalink() and get_the_permalink().

apply_shortcodes is meant to get better semantics: instead of performing an action and outputting to the current buffer, the idea is to apply filters to the input and return a result. The process is simpler, cleaner and more maintainable – not to mention easier to teach new developers.

apply_shortcodes() can be used the same way do_shortcode() is currently used:

echo apply_shortcodes( '[wporg]My Text[/wporg]' );
// Displays the result of the shortcode

Themes/Plugins authors and WordPress developers are invited to start using apply_shortcodes() instead of do_shortcode().

To be clear, there is no plan for deprecating the former function right now. But the sooner developers can all switch to the much more semantic apply_shortcodes(), the sooner the core team can plan to deprecate the old function. With WordPress 5.4, apply_shortcodes() is now the recommended way to display the result of a shortcode.


For reference, see the related Trac ticket: #37422

Copy review: @marybaum

#5-4, #dev-notes, #shortcodes

An updated Button component in WordPress 5.4

As the @wordpress/components package becomes the vehicle that implements more and more of the WordPress design system, and as that system matures, its components get more consistent and more coherent.

WordPress 5.4 adds a number of changes and enhancements to the Button component.

Button sizes

In keeping with the overall design direction of the project, the button default height is now 36px. So you no longer need to use the previous isLarge prop variation.

The Button still supports the isSmall variation.

import { Button } from '@wordpress/components';

const regularButton = <Button>My Button</Button>;
const smallButton = <Button isSmall>My Button</Button>;

To keep all the button variations consistent, their styles now declare specific heights.

If you’ve been relying on the previous buttons’ dynamic heights to make them adapt to their content, you’ll want to override the new fixed heights. Make sure you add the rule below:

height: auto;

Icon support

In previous versions, the components package offered a Button component for regular buttons and an IconButton for buttons with icons.

WordPress 5.4 merges those components. To show buttons with icons, pass an extra icon prop to the regular Button component. You can also mix text and icons.

import { Button } from '@wordpress/components';

const myIcon = (
  <svg xmlns="http://www.w3.org/2000/svg" viewport="0 0 20 20">
    <path r="M5 4l10 6-10 6V4z" />
  </svg>
);

const SimpleIconButton = <Button icon={ myIcon } label="Button label" />;

const IconAndTextButton = (
  <Button icon={ myIcon }>
    Button Text
  </Button>
);

Note: the IconButton is still available, but it’s officially deprecated.

Classname changes

In previous versions, icon buttons relied internally on the components-icon-button. With the merger of the Button and IconButton components, WordPress removes this class name and replaces it with .components-button.has-icon.

Recommendation: Don’t rely on any internal className a component might use. If you want to target a specific component, prefer adding your own className prop and use that instead.

Going further

Try out the Button component or the other wordpress/components. Check out the components Storybook.

#5-4, #block-editor, #components, #dev-notes

Changes related to Calendar Widget markup in WordPress 5.4

The HTML 5 specification permits the <tfoot> to precede the <tbody> element. That changed in HTML 5.1 and now <tfoot> must follow <tbody>.

Historically, the Calendar Core Widget used the <tfoot> element to display the calendar’s navigation links. But since the HTML 5.1 spec has changed, WordPress 5.4 moves the navigation links to a <nav> HTML element that comes right after the <table> element.

Moving navigation links outside of the <table> element offers better accessibility, with clearer distinction between elements. And a <nav> element is the semantically correct element for any navigation system, in any context.

Here’s a sample of the Calendar Widget’s former HTML markup:

<div id="calendar_wrap" class="calendar_wrap">
	<table id="wp-calendar">
		<caption>February 2020</caption>
		<thead>
			<tr>
				<!-- Day Names -->
			</tr>
		</thead>
		<tfoot>
			<tr>
				<td colspan="3" id="prev"><a href="https://example.com/2020/01/">« Jan</a></td>
				<td class="pad"> </td>
				<td colspan="3" id="next" class="pad"> </td>
			</tr>
		</tfoot>
		<tbody>
			<!-- Calendar Grid -->
		</tbody>
	</table>
</div>

And here’s a sample of the Calendar Widget’s new HTML markup:

<div id="calendar_wrap" class="calendar_wrap">
	<table id="wp-calendar">
		<caption>February 2020</caption>
		<thead>
			<tr>
				<!-- Day Names -->
			</tr>
		</thead>
		<tbody>
			<!-- Calendar Grid -->
		</tbody>
	</table>
	<nav aria-label="Previous and next months">
		<span id="prev"><a href="https://example.com/2020/01/">« Jan</a></span>
		<span class="pad"> </span>
		<span id="next" class="pad"> </span>
	</nav>
</div>

If you’re a site owner, and especially if you’re a Theme author, you are invited to test this change thoroughly. You may need to make some CSS adjustments.

For example, here are the visual differences for Twenty Twenty, the current Bundled Theme.

Before this change:

After this change:


For full details, see the related ticket on Trac: #39763

#5-4, #dev-notes, #widgets

Formal deprecation of some unused Customizer classes in WordPress 5.4

WordPress 4.9 deprecated the WP_Customize_New_Menu_Control and WP_Customize_New_Menu_Section PHP classes and wp.customize.Menus.NewMenuControl JavaScript class. The Core Team initially planned to remove them entirely in WordPress 5.0.

Deprecated items

Given how much time has elapsed since then, WordPress 5.4 leaves in place WP_Customize_New_Menu_Control and WP_Customize_New_Menu_Section to prevent potential backwards compatibility issues. 5.4 also formally deprecates them using _deprecated_file() and _deprecated_function() calls.

As a reminder:

_deprecated_file() is used to mark a file as deprecated and inform when it has been used. There is a deprecated_file_included hook that can be used to get the backtrace up to what file and function called the deprecated function. The behavior is to trigger an error if WP_DEBUG is true.

_deprecated_function() is used to mark a function as deprecated and inform when it has been used. There is a deprecated_function_run hook that can be used to get the backtrace up to what file and function called the deprecated function. The behavior is to trigger an error if WP_DEBUG is true.

Removed item

WordPress 5.4 removes the wp.customize.Menus.NewMenuControl JS class completely. This JS class can’t be used anymore starting with WP 5.4.


For reference, see the related Trac ticket: #42364

#5-4, #dev-notes

Media Upload Request Flow in WordPress 5.3

After a couple of questions from hosting companies about how to detect how well uploads are working at the server/request level, I thought further documentation would help.

Here is a walkthrough of the request flow for media uploads, both before and after WordPress 5.3. Hopefully this will help with troubleshooting and debugging uploads on your infrastructure or sites!

Before WordPress 5.3

Before WordPress 5.3, uploads had to complete during a single HTTP POST request to .../wp-admin/async-upload.php or to the REST API with the media endpoint (.../wp-json/wp/v2/media/).

The block editor uses the REST API to upload, while any uploads outside the block editor (or using the popup Media Modal) use async-upload.php.

When uploads failed, they would return whatever HTTP error the server is set up to give (usually in the 5xx range). This is usually due to timeout or resource exhaustion (like running out of memory) reasons.

WordPress 5.3+

In WordPress 5.3+, uploads have been decoupled from a single request to allow for resuming. Now, when an upload returns a 5xx error, there can be up to 5 followup requests.

This is accomplished differently depending on whether async-upload.php or the REST API are used.

Legacy Uploads

Outside of the REST API, the upload happens first with a request to async-upload.php, just like before 5.3.

If it fails, a request is made to admin-ajax.php with form-data containing action: media-create-image-subsizes and attachment_id: #### to attempt to complete the action.

If all retry attempts fail, the last request to admin-ajax.php has _wp_upload_failed_cleanup: true in form-data and attempts a cleanup. This deletes the the attachment post, the uploaded file, and any intermediate sizes that were created. Then, an error message is shown to users advising them to scale down the image and try uploading again.

REST API Uploads

When using the REST API, the initial request is to .../wp-json/wp/v2/media?_locale=user, and retry requests are to .../wp-json/wp/v2/media/####/post-process?_locale=user (where #### is the attachment post ID).

If all attempts to resume post-processing fail with HTTP 5xx errors, the last is a standard “delete attachment” request, sent to .../wp-json/wp/v2/media/####?force=true&_locale=user with X-HTTP-Method-Override: DELETE header. It performs the same cleanup as described for the admin-ajax.php upload method.

Hopefully this helps in understanding how uploads work! If you have any questions, please ask in the comments for clarification.

Thanks to @azaozz for helping write this post!

+make.wordpress.org/hosting

#5-3, #dev-notes, #media

Admin form controls height and alignment standardization in WordPress 5.3.1

WordPress 5.3 introduced some notable Admin CSS changes to improve administration accessibility and consistency with the block editor.

These changes made more obvious that form controls heights and alignments were not consistent across WP Admin.

Before WordPress 5.3, there were already some inconsistencies between form controls. For reference, WordPress 5.2 form controls various alignments and heights are grouped in the screenshot below:

Form controls alignment and height inconsistencies in WordPress 5.2

WordPress 5.3 Admin CSS changes brought more attention to those general inconsistencies on form controls. And several users and contributors reported these inconsistencies as regressions from 5.3.

Example of form controls inconsistencies in WordPress 5.3

Although these inconsistencies cannot be considered as regressions from 5.3 since they existed before 5.3 Admin CSS changes, WordPress 5.3.1 introduces some fixes on heights and alignments.

5.3
5.3.1
5.3
5.3.1
5.3
5.3.1

WordPress 5.3.1 changes include:

  • Standardized height basis of 30px for all form controls
  • Consistent line height basis of 30px across the interface
  • 14px font size basis for select controls option text
  • Remove various top/bottom margin and padding

These changes are part of a continuous effort to improve styling and consistency of all form controls in the WordPress admin pages. In general, plugin authors and WordPress developers are encouraged to:

  • remove any fixed height: flexible heights are now the WordPress recommended standard to allow form controls to better scale with text zoom
  • remove any custom top and bottom padding values
  • remove any custom line-height value
  • remove any custom min-height value
  • update custom focus/hover styles on custom UI components to match the new WordPress focus/hover styles

For full details about these changes, see the related changeset on WordPress Trac. WordPress developers and plugin authors may also want to visit the related Trac ticket: #48420

#5-3-1, #core-css, #dev-notes

Alternate color schemes changes in WordPress 5.3.1

WordPress 5.3 added some noteworthy CSS changes to WordPress Admin. These changes also impacted alternate color schemes, especially concerning secondary buttons.

Indeed, secondary button borders unexpectedly inherited their scheme’s primary color, which resulted in arguable visual aspect and poor readability for most color schemes.

“Blue” alternate color scheme in WordPress 5.3
“Coffee” alternate color scheme in WordPress 5.3
“Midnight” alternate color scheme in WordPress 5.3

A bug also occurred on :active state, where the background color of the button was quite the same than the text color.

On the right: secondary button with :active state on “Blue” color scheme in WordPress 5.3
On the right: secondary button with :active state on “Midnight” color scheme in WordPress 5.3

WordPress 5.3.1 will fix these issues by unifying WP-Admin secondary buttons for all alternate color schemes.

Secondary button styles will be the same for all bundled alternate color schemes. This change also fixes the :active state CSS issue.

Please note this change also introduces some hardcoded colors for both gray borders and texts. Plugin authors who provide specific support for alternate color schemes can use these new hardcoded colors.

New secondary button CSS/Sass styles in WP 5.3.1:

.button {
	border-color: #7e8993;
	color: #32373c;
}

.button:hover {
	border-color: darken( #7e8993, 5% );
	color: darken( #32373c, 5% );
}

.button:focus {
	border-color: #7e8993;
	color: darken( #32373c, 5% );
	box-shadow: 0 0 0 1px #32373c;
}

See /wp-admin/css/colors/_admin.scss.

New CSS styles for secondary buttons in alternate color schemes:

Secondary buttons in WordPress 5.3.1
“Midnight” alternate color scheme in WP 5.3.1
“Coffee” alternate color scheme in WP 5.3.1

For reference, see the related Trac tickets: #48585 and #48598.

#5-3-1, #accessibility, #core-css, #dev-notes

Twenty Twenty: animated scroll changes in WordPress 5.3.1

In WordPress 5.3, Twenty Twenty new bundled theme added smooth scroll animations to anchor links. These animations were handled by native JavaScript and it caused several issues, mentioned in the following Trac tickets and GitHub issues:

  • #48763 – Twenty Twenty: SmoothScroll is broken
  • #48551 – Twenty Twenty: Replace JS-based smooth scroll with CSS
  • #48866 – TwentyTwenty: Paginated comments don’t work
  • GitHub issue 476 – Consider removing JS-based smooth scroll

Additionally to the multiple issues listed in the above tickets, JavaScript-based scroll animations add a bunch of relatively complex JS code, override natural anchor behavior and may interfere with how specific user agents handle in-page scrolling.

In WordPress 5.3.1, the current smooth scroll JavaScript implementation will be replaced with “scroll-behavior” CSS property.

This change fixes the issues encountered with the current JavaScript implementation, and also includes an accessibility enhancement by using prefers-reduced-motion: reduce media query property for users that have opted in to reduced motion in their browser settings.

For further explanation on this media query, see Mozilla Developer Network documentation.

Browsers that don’t support scroll-behavior CSS property will fallback to default HTML anchor behavior. For reference, see full browsers support for this CSS property on MDN.

New CSS scroll animation implementation in Twenty Twenty:

html {
    scroll-behavior: smooth;
}
@media (prefers-reduced-motion: reduce) {
    html {
        scroll-behavior: auto;
    }
}

Developers are able to remove scroll-behavior effect on specific elements by using a class CSS selector, as follows:

.disable-smooth-scrolling {
    scroll-behavior: auto;
}

For reference, see the related changeset in 5.3.1 branch.

#5-3-1, #accessibility, #bundled-theme, #core-css, #dev-notes, #twentytwenty