Cancel

Justin Tadlock

Preparing for WordPress 5.4: Changes Theme and Plugin Developers Should Know About

With the release of WordPress 5.4 looming, it is time for plugin and theme developers to begin testing their extensions and making sure there are no issues. There are also new APIs for upcoming features. Yesterday, the core team released the first release candidate for 5.4. The official release is planned for March 31.

This post will serve as a quick guide with links to several important changes that developers need to keep in mind in the coming weeks. Be sure to test your plugins and themes.

Theme Developers

Screenshot of the new social icons block in use via the block editor.
New social icons block.

There are several changes that theme authors will want to test against. WordPress 5.4 has a few extra theme features. It also has several markup-related changes that could break theme designs on the front end and in the block editor. Unfortunately, for theme authors who want to support multiple versions of WordPress, some of these changes may mean a little extra CSS bloat.

Social Icons and Buttons Blocks

WordPress 5.4 introduces two new blocks: social icons and buttons. The social icons block allows users to insert icons/links for up to 40 different social networks. The buttons block lets users group multiple button blocks together. Theme authors who are rolling out custom block editor styles need to account for these new blocks to make sure they are output correctly.

Create Custom Gradient Presets

The new Gradients API allows theme authors to define custom gradient presets for users to use with either the group or button blocks. Theme authors will need to do some legwork to improve on the eyesore that is the default gradient presets. With a little work, gradients can be a useful tool at the user’s disposal. Theme authors can also disable gradients altogether if they prefer not to support them.

Block Editor Markup and Style Changes

Theme authors who have directly targeted specific editor classes, will need to check their block editor styles. Many classes with the editor- prefix have been changed to use the block-editor- prefix. The wrapper element with the .edit-post-layout__content class has been removed altogether. Several wrapper elements were removed from blocks and the rich text component. Core’s built-in padding and negative margins on blocks have been refactored, which is a welcome addition. Perhaps theme authors will no longer have to fight against multiple nested selectors to provide a basic, working layout that matches the front end.

These changes have already broken several themes I have seen. There is a good chance many theme authors will need to update their block editor styles.

At a time when the Theme Review Team is asking for more theme authors to submit themes with custom editor styles, these types of changes to classes and markup are not a boost of confidence. Theme developers can easily feel like they are fighting a losing battle. However, work is moving forward to make the editor markup closer to a one-to-one match with the front end. At some point, theme authors can only hope they will no longer need to deal with these kinds of changes while supporting users across multiple versions of WordPress. For now, they are in a somewhat messy transitional phase.

Calendar Markup and Class Changes

The core team changed the markup of the get_calendar() function, which also affects the Calendar widget. The calendar output no longer has a <tfoot> element. Instead, the previous and next month links were moved to a <nav> element below the <table> element.

The calendar output also adds or changes multiple IDs and classes:

  • .wp-calendar-table added to the wrapper element.
  • .wp-calendar-nav added to the navigation wrapper element.
  • .wp-calendar-nav-next replaces the #next ID on the next month link.
  • .wp-calendar-nav-prev replaces the #prev ID on the previous month link.

These are breaking changes. Any custom CSS that targeted the old HTML or IDs will need to be updated.

Block Developers

Screenshot of a code editor that showcases the initial code for creating a block plugin.
Initial JavaScript file created by the block scaffolding script.

For plugin developers who are creating custom blocks, WordPress 5.4 introduces several new APIs and tools for working with the block system.

Block Scaffolding

Developers have a new NPM package for quickly creating a block plugin. With a single command of npm init @wordpress/block <plugin-name> the script will create a new directory and build out the appropriate PHP, CSS, and JavaScript files necessary for building a block plugin. Developers can use modern JavaScript tooling by default or optionally choose to use an ES5 version.

The intention of the block scaffolding package is for plugin authors to build single-block plugins that will eventually make their way into the official block directory.

Block Collections API

The Block Collections API works similarly to categories. However, they are based on namespace. When a plugin developer registers a custom collection, any blocks that share the collection namespace will appear under a custom section in the block inserter. This seems to be a smarter way to organize blocks. It will certainly come in handy for plugins that create libraries of blocks, providing an automatic way to group them together.

Block Variations API

The new Block Variations API allows block developers to essentially create copies of block with a variation. Each registered variation will appear as a separate block in the block inserter for users to choose from.

A good example of this feature is the new social icons block. It is a single block with 40 variations for the various social networks.

Other Developer-Related Changes

There are a couple of other changes of note that cross into both plugin and theme development territory.

New Nav Menu Hooks

After waiting and waiting and waiting, developers are finally getting some oft-requested hooks for adding custom fields to the nav menu admin screen and customizer. At least one ticket goes back 9 years, but it is better late than never. In the past, developers would need to use a custom walker class to make some of the necessary customizations. However, only a single walker class could be used at a time, which meant that multiple plugins that made changes would not work together.

The core team added the new wp_nav_menu_item_custom_fields hook on the nav menus admin screen, which appears before the “move” buttons for individual menu items. For parity with the admin, nav menu items have a new wp_nav_menu_item_custom_fields_customize_template in the customizer. These hooks will allow developers to add custom form fields necessary for adding custom data to nav menu items.

apply_shortcodes() Alias Function

WordPress 5.4 introduces a new apply_shortcodes() function. It is an alias for the do_shortcode() function. The new function provides a more semantically-correct function name. Generally, functions with a prefix of do_ expect output or some type of action. Functions with a prefix of apply_ expect data to be returned.

If you are creating a theme or plugin with shortcode-aware areas, you will want to make the switch to the new function. While the do_shortcode() function is not currently marked for deprecation, that should be the eventual goal.

Category:
27

27 responses to “Preparing for WordPress 5.4: Changes Theme and Plugin Developers Should Know About”

  2. This is what drives me nuts…designing themes for both the Classic editor and the block editor, only to later find out things were completely changed.

    Then there is the issue of trying to get the front-end styles into the block editor is an absolute nightmare (I often invent new swear words). For example, try changing the main content font size when the block editor is loading its own CSS in the footer area; overriding what you try to do.

    Styling for the classic editor is a breeze! If the dev team can find a way to make it as easy as the classic editor, I would be happy as can be!

    The dev team makes these changes that will affect millions of users who have themes (and plugins) which need updating constantly is taxing. I feel sorry for the theme authors/shops that have a LARGE portfolio of themes and plugins that were updated for GB compatibility. Luckily, I’m keeping mine limited…less overhead when it comes to constantly changing and updating themes.

    Create forum topic from comment

    • I’m working on a theme using TwentyTwenty as the foundation and have been doing it on WP 5.4 beta3 (now RC1). So far, I haven’t encountered anything of an issue; the exception was that they had the HTML tag as fixed on mobile view (not sure why) in beta2, but I posted it on GitHub (fixed now). Had to make an adjustment to the calendar widget though.

      Create forum topic from comment

  4. A tip concerning the new @wordpress/block package: it supports hot reloading! With it, whenever making a change in the block’s javascript file, the page is automatically refreshed, which greatly speeds up development.

    It doesn’t mention how to enable it in the package’s documentation, so here it goes: Add a script with src http://localhost:35729/livereload.js, like this:

    if (defined('ENABLE_HOT_RELOADING_FOR_DEV') && ENABLE_HOT_RELOADING_FOR_DEV) {
  wp_register_script('livereload', 'http://localhost:35729/livereload.js');
  wp_enqueue_script('livereload');
}

    And add define('ENABLE_HOT_RELOADING_FOR_DEV', true); to wp-config.php

    Create forum topic from comment

    • The only thing related to themes that don’t add block styles is the calendar widget.

      As for whether such development is dead, it is not completely. It really depends on whether you still want to add a custom stylesheet for the classic editor, and nothing has changed in that regard. At this point, you really should be creating styles for the block editor with themes for public release, even if still supporting classic.

      Create forum topic from comment

    • The loading speed on the front end depends on a number of factors. The first and most important is the theme that you use. The second most important factor is what plugins you are using. Many will load additional scripts and styles on the front end.

      This is a much larger topic, which is also specific to individual sites, than what we can realistically dive into here in the comments. There are many friendly volunteers who can help over at WordPress support.

      Create forum topic from comment

  9. What about releasing Gutenberg after it has been finished?

    These ongoing rolling updates in millions of live websites with breaking changes cause millions of hours mostly unpaid work for small agencies and help-a-friend webmasters. These guys will find out about these changes only after the websites is broken because probably very few of them read any announcements or development blogs or notes or issues or release candidate notes.

    Create forum topic from comment

  10. I think social icon block is really helpful for developers and we can simply add icons without the need for any additional plugin. But, Can someone confirm if we can add them to widgets or not? Or they can only be added to posts and pages?

    Create forum topic from comment

    • Widget support for blocks, such as social icons, is currently experimental. If you install and activate the Gutenberg plugin, it has an “Experiments” settings page that allows you to enable widget support. Eventually, it will be possible to add blocks pretty much anywhere, but core WordPress isn’t there yet.

      Create forum topic from comment

  12. actually I feel apply_shortcode not semantically correct either. If I “apply” something to an object I would rather consider it a state change but not necessarily expect something to be returned. Hope this makes sense.

    Create forum topic from comment

  15. And THIS is only one of many reasons why I hate having to update to the next major versions or sub-versions repeatedly. Nothing more unnerving than having to go back through tons of code and scripting, all to find out what was broken and when.

    I fondly remember the days when WordPress used to be much lighter weight, and loaded webpages very quickly. Now, it seems we get a lot of “gotchas” when it comes to more of these major changes. I sometimes wonder if some of the members of the development team really think about the effects of some of those changes sprung on the community?

    Create forum topic from comment

  16. You dropped one big change in WordPress 5.4. WordPress announced that WordPress 5.4 may feature image lazy-loading by default. This feature will enable the “loading” HTML attribute on all IMG elements. WordPress publishers will no longer need to use JavaScript or third party plugins for lazy-loading their images.

    Create forum topic from comment

You may also like

Newsletter

Subscribe Via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.