Block Editor API Changes to Support Multiple Admin Screens in WP 5.8


WordPress 5.8 is the first coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. release where the post editor is no longer the only adminadmin (and super admin) screen that uses the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor. The updated widgets editor screen will also support blocks.

During the development process, we found several WordPress hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. defined on the server depended on the $post object that is not present on the widgets screen. So, we decided to deprecate some of the existing filters and introduce context-aware replacements.

These updates enable us to iteratively bring the block-based paradigm to different screens. For example, the navigation editor screen can leverage the new WP_Block_Editor_Context class and will receive more capabilities over time. There are also new methods introduced that allow code reuse for the functionality that needs to be shared between the screen that uses the block editor.

Related TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticketticket Created for both bug reports and feature development on the bug tracker.#52920.

Class

WP_Block_Editor_Context

A class representing a current block editor context.

The expectation is that the block editor can have a different set of requirements on every screen where it is used. This class allows defining supporting settings that can be used with filters.

Example:

$post_editor_context = new WP_Block_Editor_Context( array( 'post' => get_post() ) );

Functions

get_default_block_categories

A new method that makes it possible to share default block categories.

Example:

print_r( get_default_block_categories() );

get_allowed_block_types

A new method to handle better the list of allowed block types depending on the editor context.

Example:

print_r( get_allowed_block_types( $post_editor_context ) );

get_default_block_editor_settings

Most of settings defined on the client in the @wordpress/block-editor package in store/defaults.js file are now available on the server with the new get_default_block_editor_settings method.

Example:

print_r( get_default_block_editor_settings() );

get_block_editor_settings

A new method ensures that the editor settings can differ depending on the editor’s context.

Example:

$post_editor_settings = array(
	'richEditingEnabled' => user_can_richedit(),
);

print_r( get_block_editor_settings( $post_editor_settings, $post_editor_context ) );

block_editor_rest_api_preload

The logic that preloads common data used with the block editor by processing an array of REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. paths got abstracted in a new method.

Example:

$preload_paths = array(
	'/',
	'/wp/v2/types?context=edit',
);

block_editor_rest_api_preload( $preload_paths, $post_editor_context ) );

Filters

Several existing block editor filters that depend on the $post object get deprecated:

  • allowed_block_types
  • block_categories
  • block_editor_preload_paths
  • block_editor_settings

New filters are introduced as their replacements that are context-aware.

allowed_block_types_all

Filters the allowed block types for all editor types, defaulting to true (all registered block types supported).

Note: Replaces the deprecated allowed_block_types 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..

Example:

function filter_allowed_block_types_when_post_provided( $allowed_block_types, $editor_context ) {
	if ( ! empty( $editor_context->post ) ) {
		return array( 'core/paragraph', 'core/heading' );
	}
	return $allowed_block_types;
}

add_filter( 'allowed_block_types_all', 'filter_allowed_block_types_when_post_provided', 10, 2 );

block_categories_all

Filters the default array of categories for block types.

Note: Replaces the deprecated block_categories filter.

Example:

function filter_block_categories_when_post_provided( $block_categories, $editor_context ) {
	if ( ! empty( $editor_context->post ) ) {
		array_push(
			$block_categories,
			array(
				'slug'  => 'custom-category',
				'title' => __( 'Custom Category', 'custom-plugin' ),
				'icon'  => null,
			)
		);
	}
	return $block_categories;
}

add_filter( 'block_categories_all', 'filter_block_categories_when_post_provided', 10, 2 );

block_editor_rest_api_preload_paths

Filters the array of REST API paths that will be used to preloaded common data to use with the block editor.

Note: Replaces the deprecated block_editor_preload_paths filter.

Example:

function filter_block_editor_rest_api_preload_paths_when_post_provided( $preload_paths, $editor_context ) {
	if ( ! empty( $editor_context->post ) ) {
		array_push( $preload_paths, array( '/wp/v2/blocks', 'OPTIONS' ) );
	}
	return $preload_paths;
}

add_filter( 'block_editor_rest_api_preload_paths', 'filter_block_editor_rest_api_preload_paths_when_post_provided', 10, 2 );

block_editor_settings_all

Filters the settings to pass to the block editor for all editor type.

Note: Replaces the deprecated block_editor_settings filter.

Example:

function filter_block_editor_settings_when_post_provided( $editor_settings, $editor_context ) {
	if ( ! empty( $editor_context->post ) ) {
		$editor_settings['maxUploadFileSize'] = 12345;
	}
	return $editor_settings;
}

add_filter( 'block_editor_settings_all', 'filter_block_editor_settings_when_post_provided', 10, 2 );

#5-8, #dev-notes, #gutenberg

Introducing the template editor in WordPress 5.8

One of the first Full Site Editing tools introduced in WordPress 5.8 is the template editor. The template editor is a special mode available in the post editor that allows you to create, assign, and edit blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. templates to specific posts and pages.

Template Editor in action

Theme blocks

Block Templates take over the whole page allowing you to layout and design the entire page in the editor. Note, this does mean your theme’s provided PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher template won’t be used when rendering a post or page using a block template.

When creating a block template, you can use any of the blocks you’re already familiar with in the post editor.

Additionally a new set of theme blocks are introduced in WP 5.8 that can be useful when building templates. These theme blocks are:

  • Site Logo
  • Site Tagline
  • Site Title
  • Query LoopLoop The Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. https://codex.wordpress.org/The_Loop.
  • Post Title
  • Post Content
  • Post Date
  • Post ExcerptExcerpt An excerpt is the description of the blog post or page that will by default show on the blog archive page, in search results (SERPs), and on social media. With an SEO plugin, the excerpt may also be in that plugin’s metabox. 
  • Post Featured ImageFeatured image A featured image is the main image used on your blog archive page and is pulled when the post or page is shared on social media. The image can be used to display in widget areas on your site or in a summary list of posts.
  • Post Categories
  • Post Tags
  • Login/out
  • Page List

Architecture

The templates are saved as a Custom Post TypeCustom Post Type WordPress can hold and display many different types of content. A single item of such a content is generally called a post, although post is also a specific post type. Custom Post Types gives your site the ability to have templated posts, to simplify the concept. named wp_template. A REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. end point is also available to fetch these templates.

Theme Support

By default, the template editor is enabled for all themes, but themes can opt-out of this feature using

remove_theme_support( 'block-templates' );

#5-8, #dev-notes, #gutenberg

Bootstrap/Load Changes in 5.8

WordPress 5.8 brings some small changes to the Boostrap/Load component.

  • timer_float is a new function that can be used to reliably determine the total time from the start of php execution. See #39163
  • Inline comments were updated to make it clearer in wp-config-sample.php where custom configuration variables should go and wp-load.php to help improve the understanding of error level reporting. See #37199 and #41902
  • Fatal error recovery was updated to not say an email was sent when it was impossible to send the email. See #52560
  • enable_loading_object_cache_dropin is a new 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. to allow disabling of the object cache dropin. See #53322

Thank you to all of the people who contributed to the Bootstrap/Load component in 5.8.

Props to @desrosj for review and edits.

#5-8, #bootstrap-load, #dev-notes

WordPress 5.8 adds WebP support

WebP is a modern image format that provides improved lossless and lossy compression for images on the web. WebP images are around 30% smaller on average than their JPEG or PNG equivalents, resulting in sites that are faster and use less bandwidth. WebP is supported in all modern browsers according to caniuse.

From WordPress version 5.8 forward, you can upload and use WebP images in WordPress like you would a JPEG or PNG image today (as long as your hosting service supports WebP). Switching to the WebP format for your images will improve your site’s performance and your site visitor’s experience. 

How WebP Helps You

WebP images are significantly smaller than their JPEG equivalents, so visitors to your site will see the complete page loaded more quickly. Smaller images take less bandwidth to transmit, and your images still get all of the responsive benefits of srcset and lazy loading by default. Finally, WebP is supported in all major browsers, so most sites can start using them today.

Creating WebP images

Image editing tools support exporting in WebP, or you can also use command line conversion tools or web based tools like Squoosh. Once you save your images as WebP, upload them to WordPress and use them like you would any other image. 

Using WebP images

WebP images work like any other image in WordPress with some small caveats. 

WebP images support lossy and lossless compression, as well as an animated format and support for transparent images. In WordPress, the lossless WebP format is only supported when the hosting server uses Imagick (the PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher library) until LibGD adds support. In addition, animated and alpha formats are not yet supported for resized images (lossy images are created instead when you upload in these formats).

WebP support in the media library requires that your web server’s image processing library (WordPress supports both Imagick and LibGD) supports the WebP format. Fortunately these libraries have supported WebP for quite a while so support is widely available. If your web server does not support WebP, you will see an error message when you try to upload a WebP image.

If your audience includes a significant number of users on an unsupported browser (IE11 for example), either avoid using WebP images, or  enqueue a browser polyfill.

Plans for the future

The media component team is also exploring the option of having WordPress perform the image format conversion on uploaded images – using WebP as the default output format for sub-sized images. You can track progress and test this feature on the trac ticket. We are also keeping our eyes on even more modern formats like AVIF and JPEGXL that will both improve compression and further reduce resources required for compression.

FAQ

How can I fine tune the compression quality setting used for WebP images?

Developers or plugins can use the wp_editor_set_quality 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. to set the quality setting. The passed mime type enables setting by type, for example:

// Use a quality setting of 75 for WebP images.
function filter_webp_quality( $quality, $mime_type ) {
  if ( 'image/webp' === $mime_type ) {
     return 75;
  }
  return $quality;
}
add_filter( 'wp_editor_set_quality', 'filter_webp_quality', 10, 2 );

What happens if I enable the filter to use WebP sub-sizes, but upload JPEG? Do the sub-sizes have to match the original?

By default, WordPres creates the sub-sized images of the same type as the uploaded file, so uploaded WebP files to get WebP files on your site. If you want to experiment with uploading JPEG and having WordPress auto-convert these to WebP for your sub-sized images, check out this plugin (related trac ticket).

If I use WordPress multisitemultisite Used to describe a WordPress installation with a network of multiple blogs, grouped by sites. This installation type has shared users tables, and creates separate database tables for each blog (wp_posts becomes wp_0_posts). See also network, blog, site, will all my sites work with WebP images?

No. Multisite stores the file types that users are allowed to upload when a site is created. We are working on improving this in #53167. In the meantime, to ensure all existing sites on a networknetwork (versus site, blog) allow WebP files, you can use the site_option filter in a network mu-pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party to add webp to the allowed file types for all network sites:

// Ensure all network sites include WebP support.
add_filter(
  'site_option_upload_filetypes',
  function ( $filetypes ) {
    $filetypes = explode( ' ', $filetypes );
    if ( ! in_array( 'webp', $filetypes, true ) ) {
      $filetypes[] = 'webp';
      $filetypes   = implode( ' ', $filetypes );
    }

    return $filetypes;
  }
);

#5-8, #core-images, #dev-notes, #images

Changes to block editor components and blocks

URLInput component

In previous versions the URLInput component available on the @wordpress/components package and script had the autoFocus prop set to true by default. The main reason for this was that the component was used as the first input in different modals/popovers (link, inserter) but most third-party usage had to explicitly disable that behavior (in blocks for instance). In WordPress 5.6, that prop is false by default. It’s a better choice for most use-cases as auto-focus is often an accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority., but consider checking your components if you previously relied on this behavior.

Written by @youknowriad.

BlockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. supports

Following the initial work done for WordPress 5.6 to automatically support style properties for blocks and expose UIUI User interface controls for users, in WordPress 5.7 this mechanism has been expanded to new blocks. Themes may want to review if their styles need to adjust their specificity to accommodate the user choices.

User have now the ability to update the font size of the following blocks via the inspector panel:  core/codecore/listcore/preformattedcore/verse.

Written by @nosolosw.

Empty paragraph changes

In #27995 the default behavior of a published empty paragraph (<p></p>) changed. Before, the 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.) would collapse to zero width and zero height, and be inconsistent with what users saw in the editor. Now an invisible space character is output in empty paragraphs, ensuring linebreaks in the editor correspond to linebreaks on the frontend.
There is a chance of empty paragraphs accidentally published, which will now take up space. If that is the case, it is easily fixed by deleting the empty paragraphs.

Written by @joen.

Cover Block

As of #25171, the cover block now uses an img element instead of using CSSCSS Cascading Style Sheets. background-image for images that are not using fixed or repeated backgrounds. This means that, when rendering the post, a srcset attribute will be applied with the various generated image sizes, saving bandwidth by loading smaller images when possible.

Written by @ajlende.

Button block

The buttons block now provides justification options for its inner button blocks (Justify items left, Justify items center, Justify items right, Space between items).

To implement this feature, the block’s <div> element is now a flexbox container (display: flex)—previously it was display: block. It’s recommended that theme developers check that the buttons block still displays correctly for users for the various alignment and justification options it now provides.

The left and right alignment options for the buttons block have now been deprecated. Users can achieve the same results using a combination of a full alignment and left or right justification. Any buttons blocks that were already added to posts with left and right alignment will be migrated (via the block deprecation system) to use justification in this way when a post is loaded—users should see no change in the visual appearance of buttons.

Written by @talldanwp.

#5-7, #block-editor, #dev-notes

WordPress 5.7 Field Guide

WordPress 5.7 brings you the best features and enhancements to help start 2021 on a positive note! A small and experienced release squad lead the development of new features and resolved defects that benefit users and developers alike.

As a user, you’ll see a refined blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor UIUI User interface, lazy-loading iframes, streamlined migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. from HTTPHTTP HTTP is an acronym for Hyper Text Transfer Protocol. HTTP is the underlying protocol used by the World Wide Web and this protocol defines how messages are formatted and transmitted, and what actions Web servers and browsers should take in response to various commands. to HTTPSHTTPS HTTPS is an acronym for Hyper Text Transfer Protocol Secure. HTTPS is the secure version of HTTP, the protocol over which data is sent between your browser and the website that you are connected to. The 'S' at the end of HTTPS stands for 'Secure'. It means all communications between your browser and the website are encrypted. This is especially helpful for protecting sensitive data like banking information., standardized colors in WP Adminadmin (and super admin) to a single palette, and a new Robots APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. and media search engine visibility setting. As a developer, you’ll see 66 enhancements and feature requests, 127 bug fixes, and more! Of particular interest for developers will be the ongoing cleanup after the update to jQuery 3.5.1 as step 3 on our upgrade process of eventually removing jQuery Migrate.

In this Field GuideField guide The field guide is a type of blogpost published on Make/Core during the release candidate phase of the WordPress release cycle. The field guide generally lists all the dev notes published during the beta cycle. This guide is linked in the about page of the corresponding version of WordPress, in the release post and in the HelpHub version page., you’ll notice what’s relevant to you and your users among the many improvements coming in 5.7.

Administration

Block Editor

The block editor continues its rapid iteration. GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ version 9.9 is bundled with WordPress 5.7; that’s seven Gutenberg releases (versions 9.3, 9.4, 9.5, 9.6, 9.7, 9.8, and 9.9) all bundled into this release (and as noted in the related Gutenberg handbook page)! Bug fixes and performance improvements from Gutenberg versions 10.0 and 10.1 are also part of 5.7.

The WordPress 5.7 Beta 1 post highlights many new features and improvements to the block editor. There is drag and drop from the inserter into the post canvas, full height alignment for blocks to fill the entire viewport, block variations shown in the block inspector, enhancements to the usability and stability of reusable blocks, vertical alignments and width percentages for buttons block, ability to change size of icons in the Social Icons block, and ability to change the font size in the List and Code blocks.

Included below are details on the new dynamic hook (render_block_{$this->name}) to 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. the content of a single block,

Import/Export

Media

Users

REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/.

Robots API

Security

Other Developer Updates

There are even more goodies in 5.7! Read through the dev notesdev note Each important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include: a description of the change; the decision that led to this change a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase. below to see details on additional changes coming in 5.7 within Login and Registration, and Post Types.

But Wait, There is More!

5.7 offers so much more! Over 127 bugs, 66 enhancements and feature requests, and 29 blessed tasks have been marked as fixed in WordPress 5.7. Here are a few that haven’t been highlighted in the dev notes above:

  • Editor: Support filtering arguments in block type registration from metadata (#52138).
  • Menus: Add sticky footer to avoid duplicate save buttons (#51631).
  • Upgrade/Install: Display version number in update-core.php Re-install Now button (#51774).
  • Upgrade/Install: Add development as accepted value for WP_AUTO_UPDATE_CORE (#51978).

Please, test your code. Fixing issues that your code has with WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. helps you and millions of WordPress sites.

Props to @audrasjb, @jeffpaul for contributing to this guide.

#5-7, #dev-notes, #field-guide

New i18n filters & createI18n() changes

New i18ni18n Internationalization, or the act of writing and preparing code to be fully translatable into other languages. Also see localization. Often written with a lowercase i so it is not confused with a lowercase L or the numeral 1. Often an acquired skill. filters

The JavascriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. i18n functions (__()_x()_n() and _nx()) provide translations of strings for use in your code. The values returned by these functions are now filterable if you need to override them, using the following filters:

  • i18n.gettext
  • i18n.gettext_with_context
  • i18n.ngettext
  • i18n.ngettext_with_context

Note: Text domain-specific versions of these filters are also available, see below for more details.

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. Arguments

The filters are passed the following arguments, in line with their PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher equivalents.

i18n.gettext

function i18nGettextCallback( translation, text, domain ) {
	return translation;
}

i18n.gettext_with_context

function i18nGettextWithContextCallback( translation, text, context, domain ) {
	return translation;
}

i18n.ngettext

function i18nNgettextCallback( translation, single, plural, number, domain ) {
	return translation;
}

i18n.ngettext_with_context

function i18nNgettextWithContextCallback(
	translation,
	single,
	plural,
	number,
	context,
	domain
) {
	return translation;
}

Basic Example

Here is a simple example, using the i18n.gettext filter to override a specific translationtranslation The process (or result) of changing text, words, and display formatting to support another language. Also see localization, internationalization..

// Define our filter callback.
function myPluginGettextFilter( translation, text, domain ) {
	if ( text === 'Add to Reusable blocks' ) {
		return 'Save to MyOrg block library';
	}
	return translation;
}

// Adding the filter
wp.hooks.addFilter(
    'i18n.gettext',
    'my-plugin/override-add-to-reusable-blocks-label',
    myPluginGettextFilter
);

Using ‘text domain’-specific filters

Filters that are specific to the text domain you’re operating on are generally preferred for performance reasons (since your callback will only be run for strings in the relevant text domain).

To attach to a text domain-specific filter append an underscore and the text-domain to the standard filter name. For example, if filtering a string where the text domain is “woocommerce”, you would use one of the following filters:

  • i18n.gettext_woocommerce
  • i18n.gettext_with_context_woocommerce
  • i18n.ngettext_woocommerce
  • i18n.ngettext_with_context_woocommerce

For example:

// Define our filter callback.
function myPluginGettextFilter( translation, text, domain ) {
	if ( text === "You’ve fulfilled all your orders" ) {
		return 'All packed up and ready to go. Good job!';
	}
	return translation;
}

// Adding the filter
wp.hooks.addFilter(
	'i18n.gettext_woocommerce',
	'my-plugin/override-fulfilled-all-orders-text',
	myPluginGettextFilter
);

To apply a filter where the text-domain is undefined (for example WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. strings), then use “default” to construct the filter name.

  • i18n.gettext_default
  • i18n.gettext_with_context_default
  • i18n.ngettext_default
  • i18n.ngettext_with_context_default

Changes to createI18n()

In order to support the filtering of translated strings, the createI18n() method that creates an i18n instance now allows a @wordpress/hooks instance to be passed in.

If you are directly creating an i18n instance yourself by calling createi18n() and you wish to take advantage of filtering, then you will need to update your code to supply a suitable third argument.

Note: If you are using the existing translation functions provided by @wordpress/i18n then you do not need to do anything, the default i18n instance is already set up correctly.

Use standard wp.hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. instance when creating an i18n Instance

import { createI18n } from "@wordpress/i18n";
import "@wordpress/hooks";

const myI18n = createI18n( initialData, initialDomain, wp.hooks );

Use separate hooks instance when creating an i18n Instance

import { createI18n } from "@wordpress/i18n";
import { createHooks } from "@wordpress/hooks";

const myHooks = createHooks();
const myI18n  = createI18n( initialData, initialDomain, myHooks );

This dev notedev note Each important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include: a description of the change; the decision that led to this change a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase. was written by @leewillis77.

#5-7, #block-editor, #dev-notes

REST API Changes in WordPress 5.7

The following is a snapshot of some of the changes to the REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. in WordPress 5.7. For more details, see the full list of closed tickets.

Endpoint Changes

Posts Collection Tax Query Accepts include_children

Introduced in 50157, the REST API posts collection endpoints have been updated to allow a more complex syntax for specifying the tax_query used when querying posts. Each taxonomyTaxonomy A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format. https://codex.wordpress.org/Taxonomies#Default_Taxonomies.’s query parameters can now both accept a list of term ids or an object with a terms property. 

Hierarchical taxonomies support an include_children property alongside terms. By default it’s disabled, but if set to true the flag is enabled for the generated tax_query to enable searching for posts that have the given terms or terms that are children of the given terms.

import { addQueryArgs } from '@wordpress/url';
import apiFetch from '@wordpress/api-fetch';

const query = {
	categories: {
		terms: [ 3, 5, 7 ],
		include_children: true,
	},
};
apiFetch( { path: addQueryArgs( '/wp/v2/posts', query ) } );

See #39494 for more details.

Support modified_before and modified_after Query Parameters

Introduced in 50024 the REST API posts collection endpoints now accept modified_before and modified_after query parameters to query posts based on the post modified date instead of the post published date.

import { addQueryArgs } from '@wordpress/url';
import apiFetch from '@wordpress/api-fetch';

const query = {
	modified_after: '2020-12-01T00:00:00Z',
	modified_before: '2020-12-31T23:59:59Z',
};
apiFetch( { path: addQueryArgs( '/wp/v2/posts', query ) } );

As a result of this change, the posts controller now uses a date_query with a separate clause for each date related query parameter instead of a single clause with the before and after flags set.

See #50617 for more details.

Multiple MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. Values for a Key Can Be Deleted by Sending an Empty Array

Previously, to remove all values for a specific meta key, passing null as the value for that meta key was required. After 49966 an empty array can be passed instead.

register_post_meta( 'post', 'my_meta_key', array( 
	'type' => 'string',
	'show_in_rest' => true,
) );
import apiFetch from '@wordpress/api-fetch';

const data = {
	meta: {
		my_meta_key: [],
	}
};
apiFetch( { data, method: 'PUT', path: '/wp/v2/posts/1' } );

See #50790 for more details.

All Themes are Returned via the Themes Controller

As of 49925, the themes endpoint now returns all themes installed on the site, not just the active theme. By default, the endpoint returns both active and inactive themes, but the status query parameter can be used to limit the list to themes with the desired status.

Note, the theme_supports value is only exposed for the active theme. The field is omitted for inactive themes since declaring the supported theme features requires calls to add_theme_support which can only be done if the theme is active.

When querying solely for active themes, the only permission required is to be able to edit posts of any show_in_rest post type. However when querying for inactive themes the switch_themes or manage_network_themes capability is required.

In addition to the changes to the collection endpoint, a new single theme endpoint is available. For example, /wp/v2/themes/twentytwentyone will return information about Twenty Twenty One. For convenience, a link is also added to the currently active theme in the REST API Index if the current user has the requisite permissions. This is the recommended way for applications to discover the currently active theme.

{
  "name": "WordPress Develop",
  "_links": {
    "help": [
      {
        "href": "http://v2.wp-api.org/"
      }
    ],
    "wp:active-theme": [
      {
        "href": "https://wordpress.test/wp-json/wp/v2/themes/twentytwentyone"
      }
    ],
    "curies": [
      {
        "name": "wp",
        "href": "https://api.w.org/{rel}",
        "templated": true
      }
    ]
  }
}

Lastly, the pageper_pagesearch and context query parameters are no longer exposed in the index as they are not supported by this endpoint.

See #50152 for more details.

Image Editor Accepts a List of Modifiers

The /wp/v2/media/<id>/edit endpoint introduced in WordPress 5.5 came with a limited APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. that accepted top-level rotation and crop declarations. In 50124 this API was made more powerful and flexible by accepting an array of modifications in the new modifiers request parameter.

import apiFetch from '@wordpress/api-fetch';

const data = {
	modifiers: [
		{
			type: 'crop',
			args: {
				left  : 0,
				top   : 0,
				width : 80,
				height: 80
			}
		},
		{
			type: 'rotate',
			args: {
				angle: 90
			}
		}
	]
};
apiFetch( { data, method: 'POST', path: '/wp/v2/media/5/edit' } );

The previous query parameters have been marked as deprecated, but will continue to function as normal and do not currently issue deprecation warnings. Clients are encouraged to switch to the new syntax.

To alleviate server resources, whenever possible, clients should simplify redundant modifications before sending the request.

See #52192 for more details.

Parameter Validation

Non-String Enums

In 50010 support for type coercion was added to the enum JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. Schema keyword. Previously, the enum keyword was validated by perform a strict equality check. For string types this is generally ok, but it prevented using alternative types like number when rich type support isn’t available.

Now the same level of type coercion/sanitization is applied when validating enum as all other validation checks. This means that a value of "1" will be accepted for an enum of [ 0, 1 ]. Additionally, object types now properly ignore key order when checking for equality.

See #51911 for more details.

Validation Error Codes

As of 50007, the rest_validate_value_from_schema function now returns specific error codes for each validation failure instead of the generic rest_invalid_param. For instance, if more array items are given than allowed by maxItems, the rest_too_many_itemserror code will be returned.

See #52317 for more details.

Return Detailed Error Information from Request Validation

Previously when a parameter failed validation only the first error message specified in the WP_Error instance was returned to the user. Since 50150 the REST API will now return detailed error information as part of the details error data key.

{
  "code": "rest_invalid_param",
  "message": "Invalid parameter(s): enum_a, enum_b",
  "data": {
    "status": 400,
    "params": {
      "enum_a": "enum_a is not one of a, b, c.",
      "enum_b": "enum_b is not one of d, e, f."
    },
    "details": {
      "enum_a": {
        "code": "rest_not_in_enum",
        "message": "enum_a is not one of a, b, c.",
        "data": {
          "enum": ["a", "b", "c"]
        }
      },
      "enum_b": {
        "code": "rest_not_in_enum",
        "message": "enum_b is not one of d, e, f.",
        "data": {
          "enum": ["d", "e", "f"]
        }
      }
    }
  }
}

See #50617 for more details.

Application Passwords

Fine Grained Capabilities

When the Application Passwords REST API controllers were introduced, the edit_user meta capability was used for all permission checks. As of 50114, the REST API now uses specific meta capabilities for each action type.

  • create_app_password
  • list_app_passwords
  • read_app_password
  • edit_app_password
  • delete_app_password
  • delete_app_passwords

By default, these capabilities all map to edit_user however they can now be customized by using the map_meta_cap 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..

See #51703 for more details.

Introspection Endpoint

50065 introduces a new Application Passwords endpoint for introspecting the app password being currently used for authentication. This endpoint is accessible via /wp/v2/users/me/application-passwords/introspect and will return the same information as the other endpoints. This allows for an application to disambiguate between multiple installations of their application which would all share the same app_id.

Clients can use this information to provide UIUI User interface hints about how the user is authenticated, for instance by displaying the App Passwords’s label. Or when their application is uninstalled by the user, they can automatically clean up after themselves by deleting their App Password.

See #52275 for more details.

Unique Application Names

As of 50030 the Application Passwords API enforces that each App Password has a unique name that cannot consist solely of whitespace characters. Additionally, invalidinvalid A resolution on the bug tracker (and generally common in software development, sometimes also notabug) that indicates the ticket is not a bug, is a support request, or is generally invalid. characters are stripped from the provided application name.

See #51941 for more details.

Props to @flixos90, @desrosj for proofreading.

#5-7, #dev-notes, #rest-api

Inner Blocks API Changes

The majority of blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. authors prefer to keep the focus on the parent block upon insertion in the editor rather than move it to one of the child blocks. Prior to WordPress 5.7, the default behaviour is the latter. In WordPress 5.7, the default behaviour has been changed to be the former.

This simplifies the APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. and means that the behaviour of the following APIs has changed:

  • InnerBlock component
  • useInnerBlocksProps hook
  • replaceInnerBlocks action

InnerBlock component and useInnerBlocksProps hook

Both handle the focus on the blocks with templateInsertUpdatesSelection property. If you want to keep the focus on the parent you can omit this property.

If you want to move the focus to the first child block you have to set this property to true.

Example:

<InnerBlocks template={ [ [ 'core/heading' ] ] } templateInsertUpdatesSelection />

const innerBlocksProps = useInnerBlocksProps(
	{ className: 'wp-block-cover__inner-container' },
	{
		template: [ [ 'core/heading' ] ],
		templateInsertUpdatesSelection: true,
	}
);

replaceInnerBlocks action

Reference: https://developer.wordpress.org/block-editor/data/data-core-block-editor/#replaceInnerBlocks

This action handles focus with the third argument updateSelection. If you want to keep the focus on the parent you can skip this argument when calling replaceInnerBlocks.

If you want to move the focus to the first child block you have to pass this argument with true value. Examples:

replaceInnerBlocks( rootClientId, blocks, true )

This dev notedev note Each important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include: a description of the change; the decision that led to this change a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase. was written by @ntsekouras and edited by @noisysocks.

#5-7, #block-editor, #dev-notes

Introducing script attributes related functions in WordPress 5.7

WordPress 5.7 adds a handful of new functions that enables passing attributes, such as async or nonce, to both regular and inline script 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.) attributes. This creates a path forward for enabling a Content-Security-Policy (or CSP) in CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., plugins, and themes.

These new functions are:

  • wp_get_script_tag() – Formats <script> loader tags and automatically injects a type attribute (if needed).
  • wp_print_script_tag() – Prints a formatted <script> loader tag.
  • wp_print_inline_script_tag() – Prints inline JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. wrapped in a <script> tag.
  • wp_get_inline_script_tag() – Wraps inline JavaScript in a <script> tag.

All of these functions automatically inject the type attribute if the theme has not declared support for HTML5 script tags. Reminder: to declare HTML5 support for script tags, theme authors should use the following declaration in their functions.php file:

add_theme_support( 'html5', 'script' );

Examples

wp_get_inline_script_tag()

wp_get_inline_script_tag(
	'document.createElement("video");',
	array(
		'id'    => 'create-video-js',
		'async' => true,
	)
);

Returns:

<script id="create-video-js" async>document.createElement("video");</script>

wp_print_inline_script_tag()

Directly prints the value returned by wp_get_inline_script_tag().

wp_get_script_tag()

Setting the attributed value to true just add the attribute without any value. For example:

wp_get_script_tag(
	array(
		'src'      => 'RELATIVE_PATH/FILE.js',
		'nomodule' => true,
	)
);

Returns:

<script src="RELATIVE_PATH/FILE.js" nomodule></script>

Attributes values are automatically escaped using esc_attr but URLs have to be manually escaped using esc_url. For example:

wp_get_script_tag(
     array(
         'id'        => 'jquery-"js"-2.3.4',
         'integrity' => 'sha384-long_hash',
         'src'       => esc_url( 'https://domain.tld/jquery-2.3.4.min.js' ),
     )
 );

Returns:

<script id="jquery-"js"-2.3.4" integrity="sha384-long_hash" src="https://domain.tld/jquery-2.3.4.min.js"></script>

wp_print_script_tag()

Directly prints the value returned by wp_get_script_tag().

Plugins/Themes should not overwrite the nonce attribute of script tags if not specifically responsible for implementing CSP integration.

Filtering script tag attributes in WP 5.7

The wp_script_attributes hook can be used to 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. the attributes to be added in script tags. Attributes are provided in an array containing key-value pairs representing <script> tag attributes.

Please note that only the attribute name is added to the <script> tag for entries with a boolean value, if the value is true.

Attributes are sanitized by the new wp_sanitize_script_attributes function before being printed in the script tag.

Example of use

Adds a nonce attribute to every script tag generated by either wp_get_script_tag or wp_get_inline_script_tag:

function wporg_my_wp_script_attributes( $attr ) {
	if ( ! isset( $attr['nonce'] ) ) {
		$attr['nonce'] = get_my_custom_nonce(); // Random custom function
	}
	return $attr;
);
add_filter( 'wp_script_attributes', 'wporg_my_wp_script_attributes' );

What’s next?

This creates a path forward for enabling a Content-Security-Policy (or CSP) APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. in Core, plugins, and themes.

The next steps to get wp-admin to Strict CSP mode are:

  • Add nonces to all <script> elements. With strict CSP, every <script> element must have a nonce attribute which matches the value specified in the policy. Work started in ticketticket Created for both bug reports and feature development on the bug tracker. #39941.
  • Refactor inline event handlers and javascript: URIs. Inline event handlers (onclick="...", onerror="...") and <a href="javascript:..."> links can be used to run scripts, so an attacker who finds an XSS bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. could inject such HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. and execute malicious JavaScript. CSP requires refactoring those patterns into safer alternatives. Work started in ticket #51407.
  • Refactor calls to JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. APIs incompatible with CSP – includes things like document.write() used to load additional scripts and uses of eval().
  • Serve the Content-Security-Policy headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes.. This final step will be the reward at the end of the process, turning on Strict CSP.

A complete post will be published by @adamsilverstein and @enricocarraro on Make/Core to explain these next steps in details.


For reference, see ticket #39941.

Props @johnbillion, @adamsilverstein, @enricocarraro, and @desrosj for proofreading.

#5-7, #dev-notes