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