Introducing theme.json in WordPress 5.8

WordPress 5.8 comes with a new mechanism to configure the editor that enables a finer-grained control and introduces the first step in managing styles for future WordPress releases.

Controlling settings globally and per 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.

The introduction of blocks has increased the number of settings agencies and developers may need control over. Having a central point of configuration aims to provide a more consistent and complete experience.

By creating a theme.json file in the theme’s top-level directory, themes can configure the existing editor settings (the font sizes preset, whether custom colors are enabled, etc.) as well as the new ones as they are introduced (the duotone preset, whether margin and padding controls are enabled, etc.).

This new mechanism aims to take over and consolidate all the various add_theme_support calls that were previously required for controlling the editor.

The example below shows how to disable custom colors for all blocks:

{
    "version": 1,
    "settings": {
        "color": {
            "custom": false
        }
    }
}

The addition of the theme.json file also provides a way for theme authors to control these settings on a per-block basis ― something that wasn’t possible before. The example below shows how to disable custom colors for all blocks but enable them for the paragraph block:

{
    "version": 1,
    "settings": {
        "color": {
            "custom": false
        },
        "blocks": {
            "core/paragraph": {
                "color": {
                    "custom": true
                }
            }
        }
    }
}

Top-level settings will apply to all blocks that support the relevant setting. However, block-level settings can also override the top-level settings for a specific block. Blocks are addressed by their block name and settings can be added for coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. as well as third-party blocks.

Note: to retain backward compatibility, the existing add_theme_support declarations from the theme are retrofitted in the proper categories for the top-level section. For example, if a theme uses add_theme_support('disable-custom-colors'), the result will be the same as setting settings.color.custom to false. If a setting is declared in theme.json that setting will take precedence over the values declared via add_theme_support.

See the specification document for a complete list of features and backcompatibility with add_theme_support.

Blocks can access theme settings with useSetting

Core blocks have been updated to respect the new settings coming from a theme via theme.json. For example, if a block supports a UIUI User interface margin control but the theme has disabled margin across the board, the UI control will not be displayed in the editor.

Third-party blocks can also tap into this mechanism by using the useSetting ReactReact React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. https://reactjs.org/. hook in its edit function:

import { useSetting } from '@wordpress/block-editor';
// Somewhere in the block's edit function.

const isEnabled = useSetting( 'spacing.margin' );

if ( ! isEnabled ) {
    return null;
} else {
    return <ToggleControl ... />
}

See the API docs for useSetting.

CSSCSS Cascading Style Sheets. classes for presets are automatically created and enqueued

Previously, themes had to declare presets for the editor and also enqueue the corresponding classes separately.

In the functions.php file, they’d do:

add_theme_support(
  'editor-color-palette',
  array(  /* define color presets, including translations */
) );

And then, in the style.css:

.has-<value>-color { /* ... */ }
.has-<value>-background-color { /* ... */ }
/* etc */

By using a theme.json, the theme only has to declare their presets. The engine will set up the translations and will take care of creating and enqueuing the corresponding styles to both the editor and the front-end:

{
    "version": 1,
    "settings": {
        "color": {
            "palette": [
                {
                    "name": "Color name",
                    "slug": "color-slug",
                    "color": "<color-value>"
                },
                {
                    "name": "...",
                    "slug": "...",
                    "color": "..."
                }
            ]
        }
    }
}

See the specification document for a list of classes generated by preset.

CSS Custom Properties

By phasing out IE11 support, many CSS features become available. One of these now available features is CSS Custom Properties. When a theme adds presets via theme.json, the engine will enqueue both classes and CSS Custom Properties for them.

The example below:

{
    "version": 1,
    "settings": {
        "color": {
            "palette": [
                {
                    "name": "Black",
                    "slug": "black",
                    "color": "#000000"
                },
                {
                    "name": "White",
                    "slug": "white",
                    "color": "#ffffff"
                }
            ]
        }
    }
}

will create this output in CSS:

/* One CSS Custom Property per preset value. */
body {
  --wp--preset--color--black: #000000;
  --wp--preset--color--white: #ffffff;
}

/* The corresponding classes for each preset value. */

.has-black-color { color: var(--wp--preset--color--black) !important; }
.has-black-background-color { background-color: var(--wp--preset--color--black) !important;  }

.has-white-color { color: var(--wp--preset--color--white) !important; }
.has-white-background-color { background-color: var(--wp--preset--color--white) !important;  }

See the specification document for more examples, how to add and use custom properties unrelated to presets, etc.

Managed styles for improved coordination

One of the struggles theme authors face is the conflicts that appear in an environment with core, theme, and user styles as well as the wide design area that comes with multiple blocks that can be combined indefinitely.

The theme.json file absorbs most of the common use cases for styling blocks with the goal of reducing the amount of CSS shipped to the browser, mitigating specificity wars, and providing current style info in the UI controls for users. This is the first step in having a mechanism that consolidates all the three origins of styles (core, theme, user) and that will become more important once users can provide global styles in later phases of the project.

In the example below, a theme provides styles for the top-level and a couple of blocks:

{
    "version": 1,
    "styles": {
        "color": {
            "text": "var(--wp--preset--color--primary)"
        },
        "blocks": {
            "core/paragraph": {
                "color": {
                    "text": "var(--wp--preset--color--secondary)"
                }
            },
            "core/group": {
                "color": {
                    "text": "var(--wp--preset--color--tertiary)"
                }
            }
        }
    }
}

It results in the following CSS output:

/* Top-level styles resolve to the body selector. */
body {
  color: var(--wp--preset--color--primary);
}

/* Block styles resolve to the block selector. */
p {
  color: var(--wp--preset--color--secondary);
}
.wp-block-group {
  color: var(--wp--preset--color-tertiary);
}

Any block, both core and third-party, can be targeted by its name.

See the specification document for a complete list of supported styles.

Access to other features

There are some features that are enabled or disabled when a theme has support for a theme.json file:

  • The template editor is enabled.
  • The default layout and margin styles for themes are not enqueued and the new layout options are enabled instead (see related dev note for layout).
  • The inner div for the group block (wp-block-group__inner-container) is removed.
  • The default font-family styles for the editor are not enqueued.

#5-8 #dev-notes #gutenberg

Block API Enhancements in WordPress 5.8

Starting in WordPress 5.8 release, we encourage using the block.json metadata file as the canonical way to register 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. types. The Block Metadata specification has been implemented and iterated over the last few major WordPress releases, and we have reached the point where all planned features are in place.

Example File

Here is an example block.json file that would define the metadata for a 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 create a notice block.

notice/block.json

{
	"apiVersion": 2,
	"name": "my-plugin/notice",
	"title": "Notice",
	"category": "text",
	"parent": [ "core/group" ],
	"icon": "star",
	"description": "Shows warning, error or success notices…",
	"keywords": [ "alert", "message" ],
	"textdomain": "my-plugin",
	"attributes": {
		"message": {
			"type": "string",
			"source": "html",
			"selector": ".message"
		}
	},
	"providesContext": {
		"my-plugin/message": "message"
	},
	"usesContext": [ "groupId" ],
	"supports": {
		"align": true
	},
	"styles": [
		{ "name": "default", "label": "Default", "isDefault": true },
		{ "name": "other", "label": "Other" }
	],
	"example": {
		"attributes": {
			"message": "This is a notice!"
		}
	},
	"editorScript": "file:./build/index.js",
	"script": "file:./build/script.js",
	"editorStyle": "file:./build/index.css",
	"style": "file:./build/style.css"
}

Benefits using the metadata file

The block definition allows code sharing between 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/., PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher, and other languages when processing block types stored as 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., and registering blocks with the block.json metadata file provides multiple benefits on top of it.

From a performance perspective, when themes support lazy loading assets, blocks registered with block.json will have their asset enqueuing optimized out of the box. The frontend CSSCSS Cascading Style Sheets. and JavaScript assets listed in the style or script properties will only be enqueued when the block is present on the page, resulting in reduced page sizes.

Furthermore, because the Block Type REST API Endpoint can only list blocks registered on the server, registering blocks server-side is recommended; using the block.json file simplifies this registration.

Last, but not least, the WordPress Plugins Directory can detect block.json files, highlight blocks included in plugins, and extract their metadata. If you wish to submit your block(s) to the Block Directory, all blocks contained in your plugin must have a block.json file for the Block Directory to recognize them.

Block registration

PHP

The register_block_type function that aims to simplify the block type registration on the server, can read now metadata stored in the block.json file.

The function takes two params relevant in this context ($block_type accepts more types and variants):

  • $block_type (string) – path to the folder where the block.json file is located or full path to the metadata file if named differently.
  • $args (array) – an optional array of block type arguments. Default value: []. Any arguments may be defined.

It returns the registered block type (WP_Block_Type) on success or false on failure.

Example:

notice/notice.php

<?php

register_block_type(
	__DIR__,
	array(
		'render_callback' => 'render_block_core_notice',
	)
);

Note: We decided to consolidate the pre-existing functionality available with register_block_type_from_metadata method into register_block_type to avoid some confusion that it created. It’s still possible to use both functions, but we plan to use only the shorter version in the official documents and tools from now on.

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.#53233.

JavaScript

When the block is registered on the server, you only need to register the client-side settings on the client using the same block’s name.

Example:

notice/index.js

registerBlockType( 'my-plugin/notice', {
	edit: Edit,
	// ...other client-side settings
} );

Although registering the block also on the server with PHP is still recommended for the reasons above, if you want to register it only client-side you can now use registerBlockType method from @wordpress/blocks package to register a block type using the metadata loaded from block.json file.

The function takes two params:

  • $blockNameOrMetadata (string|Object) – block type name (supported previously) or the metadata object loaded from the block.json file with a bundler (e.g., webpack) or a custom Babel plugin.
  • $settings (Object) – client-side block settings.

It returns the registered block type (WPBlock) on success or undefined on failure.

Example:

notice/index.js

import { registerBlockType } from '@wordpress/blocks';
import Edit from './edit';
import metadata from './block.json';

registerBlockType( metadata, {
	edit: Edit,
	// ...other client-side settings
} );

Related PR: WordPress/gutenberg#32030.

Internationalization support in block.json

WordPress string discovery system can now automatically translate fields marked as translatable in Block Metadata document. First, in the block.json file that provides block metadata, you need to set the textdomain property and fields that should be translated.

Example:

fantastic-block/block.json

{
	"name": "my-plugin/fantastic-block",
	"title": "My block",
	"description": "My block is fantastic",
	"keywords": [ "fantastic" ],
	"textdomain": "fantastic-block"
}

PHP

In PHP, localized properties will be automatically wrapped in _x function calls on the backend of WordPress when executing register_block_type function. These translations get added as an inline script to the plugin’s script handle or to the wp-block-library script handle in WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress..

The way register_block_type processes translatable values is roughly equivalent to the following code snippet:

<?php
$metadata = array(
	'title'       => _x( 'My block', 'block title', 'fantastic-block' ),
	'description' => _x( 'My block is fantastic!', 'block description', 'fantastic-block' ),
	'keywords'    => array( _x( 'fantastic', 'block keyword', 'fantastic-block' ) ),
);

Implementation follows the existing get_plugin_data function which parses the plugin contents to retrieve the plugin’s metadata, and it applies translations dynamically.

Related Trac ticket: #52301.

JavaScript

You can also now use registerBlockType method from @wordpress/blocks package to register a block type that uses translatable metadata stored in block.json file. All localized properties get automatically wrapped in _x function calls (from @wordpress/i18n package) similar to how it works in PHP with register_block_type. The only requirement is to set the textdomain property in the block.json file.

Example:

fantastic-block/index.js

import { registerBlockType } from '@wordpress/blocks';
import Edit from './edit';
import metadata from './block.json';

registerBlockType( metadata, {
	edit: Edit,
	// ...other client-side settings
} );

Related PR: WordPress/gutenberg#30293.

Extracting translations

The ongoing effort to improve the internationalization of client-side JavaScript code made necessary by moving to the block-based editor has led to several improvements to the i18n make-pot command from WP-CLI as of v2.5.0 release. It now also parses the block.json file as it is defined in the Block Metadata document.

Related PR: wp-cli/i18n-command#210.

New filters

There are two new 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. that can be used when block types get registered with register_block_type function using the metadata loaded from the block.json file.

block_type_metadata

Filters the raw metadata loaded from the block.json file when registering a block type. It allows applying modifications before the metadata gets processed.

The 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. takes one param:

  • $metadata (array) – metadata loaded from block.json for registering a block type.

Example:

<?php

function filter_metadata_registration( $metadata ) {
	$metadata['apiVersion'] = 1;
	return $metadata;
};
add_filter( 'block_type_metadata', 'filter_metadata_registration', 10, 2 );

register_block_type( __DIR__ );

block_type_metadata_settings

Filters the settings determined from the processed block type metadata. It makes it possible to apply custom modifications using the block metadata that isn’t handled by default.

The filter takes two params:

  • $settings (array) – Array of determined settings for registering a block type.
  • $metadata (array) – Metadata loaded from the block.json file.

Example:

function filter_metadata_registration( $settings, $metadata ) {
	$settings['api_version'] = $metadata['apiVersion'] + 1;
	return $settings;
};
add_filter( 'block_type_metadata_settings', 'filter_metadata_registration', 10, 2 );
		
register_block_type( __DIR__ );

Props to @priethor and @audrasjb for help with compiling 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, and 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..

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

Extending the Site Health interface in WordPress 5.8

With WordPress 5.8, the feature requestfeature request A feature request should generally begin the process in the ideas forum, on a mailing list, as a plugin, or brought to the attention of the core team, such as through scope meetings held for each major release. Unsolicited tickets of this variety are typically, therefore, discouraged. to allow developers to extend what Site Health tabs are available (#47225) has been implemented.

This will allow developers to add their own interfaces to the Site Health area of coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., with accompanying tab navigation in the Site Health 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., or even extend another interface.

Site Health screen showing 4 navigation items

Registering your tab navigation

If you are adding a brand new interface, you will want to introduce a navigation element, so that users may access your interface. This is done using the new site_health_navigation_tabs 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., which is an associated array of tab keys, and their label.

<?php
function wp_example_site_health_navigation_tabs( $tabs ) {
	// translators: Tab heading for Site Health navigation.
	$tabs['example-site-health-tab'] = esc_html_x( 'My New Tab', 'Site Health', 'text-domain' );

	return $tabs;
}
add_filter( 'site_health_navigation_tabs', 'wp_example_site_health_navigation_tabs' );

The above example will add the identifier example-site-health-tab with the label My New Tab to the header navigation i Site Health pages.

It is also possible to re-order what tabs are displayed first using this filter, or even remove tabs. By default core has two tabs, the Status and Info screens. The Status screen is the default, and therefore has no slug.

To not overburden the navigation area, if there are more than 4 items added, only the first three will be displayed directly, with the remaining items being wrapped inside a sub-navigation. This is based on usage testing in the Health Check 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, where 4 items have shown to be enough to cover most use cases, but not so many as to become confusing.

Displaying, or extending, an interface

When a user visits a Site Health tab, other than the default screen, the site_health_tab_content action triggers. This action includes a single argument being the slug, as defined by the tab navigation in the previous filter, to help you identify which page is being requested.

The action fires after the header itself has been loaded, but does not include any wrappers. This gives you as a developer the full width of the screen (not counting the adminadmin (and super admin) menu) to work with.

<?php
function wp_example_site_health_tab_content( $tab ) {
	// Do nothing if this is not our tab.
	if ( 'example-site-health-tab' !== $tab ) {
		return;
	}

	// Include the interface, kept in a separate file just to differentiate code from views.
	include trailingslashit( plugin_dir_path( __FILE__ ) ) . 'views/site-health-tab.php';
}
add_action( 'site_health_tab_content', 'wp_example_site_health_tab' );

The above example loads in a file with your tab content from your plugin, but only if the tab matches the tab key (or slug if you will) which was defined in the previous example.

It is possible to provide output on any tab this way, or on another tab not your own, for example if they interact with each other.

One such example might be to extend the default Info tab, which has the slug debug, and add a button to copy some information specific to only your plugin or theme.

Props @afragen for review and edits.

#5-8, #dev-notes, #site-health

Bundled themes changes in WordPress 5.8

Since 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. patterns were introduced in WordPress 5.5, older default themes received some block patterns love in 5.8. 

Twenty Fifteen

Twenty Fifteen now has: 

  • Gallery and Description
  • Contact area
  • Two Columns with Images, and 
  • Columns with a List block patterns. 

They can be found under the Twenty Fifteen block pattern categoryCategory The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging..

Related ticketticket Created for both bug reports and feature development on the bug tracker.: #51102 

Twenty Fourteen

Twenty Fourteen has following block patterns:

  • About,
  • List,
  • Summary, and
  • Contact.

These patterns can be found under the Twenty Fourteen block pattern category.

Related ticket: #51103 

Twenty Thirteen

Twenty Thirteen is decorated with:

  • Decorative Gallery,
  • Informational Section,
  • Decorative Columns,
  • Callout Quote,
  • Big Quote, and
  • Informational List block patterns.

All of these are registered under the Twenty Thirteen block pattern category.

Related ticket: #51104 

Twenty Twelve

Twenty Twelve has:

  • Floating Images Gallery,
  • Left-aligned Large Quote, and
  • Left-aligned Image and Paragraph block patterns.

These patterns are registered under the, you guessed it, Twenty Twelve block pattern category.

Related ticket: #51105 

Twenty Eleven

Twenty Eleven patterns:

  • Image and Text Columns,
  • Inline Quote,
  • Follow Blogblog (versus network, site),
  • About Me, and
  • Two Columns of Lists.

Patterns can be found under the Twenty Eleven block pattern category.

Related ticket: #51106 

Twenty Ten

Twenty Ten theme got three block patterns:

  • Introduction,
  • Highlighted Quote, and
  • Alternating Images.

Patterns are registered under the Twenty Ten block patterns category.

Related ticket: #51107 

These new block patterns will be very helpful for end users, especially combined with a new template editor introduced in WordPress 5.8, as well as new theme blocks. 

#5-8, #dev-notes

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 );

Supporting older versions of WordPress

In the case when you want to support older versions of WordPress you might need a way to detect which filter should be used – the deprecated one vs the new one. The recommended way to proceed is to check if the WP_Block_Editor_Context class exists.

Example:

if ( class_exists( 'WP_Block_Editor_Context' ) ) {
	add_filter( 'block_editor_settings_all', 'filter_block_editor_settings_compat', 10, 2 );
} else {
	add_filter( 'block_editor_settings', 'filter_block_editor_settings_compat', 10, 2 );
}

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

Introducing the template editor in WordPress 5.8

Update on 23/06/2021:

  • Added the default template section.
  • The template editor is now opt-in instead of opt-out for classic themes.

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.

Default Template

When users create new custom templates, a default template containing the site title, post title and post content is used but theme authors can choose to provide their own styled default custom templates by hooking into the editor settings and providing a `defaultBlockTemplate` as an HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. string or by using a dedicated HTML file.

add_filter( 'block_editor_settings_all', function( $settings ) {
     $settings['defaultBlockTemplate'] = file_get_contents( get_theme_file_path( 'block-template-default.html' ) );
     return $settings;
});

Theme Support

By default, the template editor is disabled for themes, but themes can choose to enable it with the following line added to their functions.php file.

add_theme_support( 'block-templates' );

Note, that if themes decide to use the newly introduced theme.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. file config, they are automatically opted-in into the template editor.

#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