New block variation APIs in 5.7

New isActive property

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. variation settings can now include a new isActive property. This optional property is a function that is used by the block editor to determine what variation a given block is. This means that block editor UIUI User interface such as BlockCard can display the block variation’s title and description instead of the block’s title and description.

We need this function to be explicitly implemented by block/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 authors, because in many cases it doesn’t make sense to try to find a match by checking dynamically all block properties. An example is the embed block where we might have changed the responsive attribute, so a match would not be found.

Example in a single block variation:

const variations = [
	{
		name: 'wordpress',
		title: 'WordPress',
		keywords: [ __( 'post' ), __( 'blog' ) ],
		description: __( 'Embed a WordPress post.' ),
		attributes: { providerNameSlug: 'wordpress' },
		isActive: ( blockAttributes, variationAttributes ) =>
			blockAttributes.providerNameSlug ===
			variationAttributes.providerNameSlug,
	},
];

Example when all variations use the same matching function:

const variations = [
	{
		name: 'twitter',
		title: 'Twitter',
		icon: embedTwitterIcon,
		keywords: [ 'tweet', __( 'social' ) ],
		description: __( 'Embed a tweet.' ),
		patterns: [ /^https?:\/\/(www\.)?twitter\.com\/.+/i ],
		attributes: { providerNameSlug: 'twitter', responsive: true },
	},
	{
		name: 'wordpress',
		title: 'WordPress',
		icon: embedWordPressIcon,
		keywords: [ __( 'post' ), __( 'blog' ) ],
		description: __( 'Embed a WordPress post.' ),
		attributes: { providerNameSlug: 'wordpress' },
	},
];

variations.forEach( ( variation ) => {
	if ( variation.isActive ) return;
	variation.isActive = ( blockAttributes, variationAttributes ) =>
		blockAttributes.providerNameSlug ===
		variationAttributes.providerNameSlug;
} );
export default variations;

New useBlockDisplayInformation hook

useBlockDisplayInformation is a new hook that returns display information about a block. It takes into account the isActive property of the each block variation. It returns the block variation or block’s titleicon and description.

If a block variation match cannot be found, the returned information will come from the block type. If no block type is found, then null is returned.

Example usage:

import { useBlockDisplayInformation, BlockIcon } from '@wordpress/block-editor';
function myBlockInformation( clientId ) {
	const blockInformation = useBlockDisplayInformation( clientId );
	if ( ! blockInformation ) return null;
	const { title, icon, description } = blockInformation;
	return (
		<div>
			<BlockIcon icon={ icon } />
			<h2 className="block-title">{ title }</h2>
			<p>{ description }</p>
		</div>
	);
}

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