New Block APIs in WordPress 5.3

In addition to a number of improvements and features for the block editor, WordPress 5.3 comes with new Block-related APIs for developers.

Server-side block style variations API

It includes server-side helpers that simplify registering and unregistering block styles.

Previously, in order to register block styles, one was required to write a JavaScript script performing the registration and ensure that the script was enqueued properly. With WordPress 5.3, you can use the register_block_style and unregister_block_style PHP helpers for the whole process.

register_block_style

The register_block_style function receives the name of the block as the first argument and an array describing properties of the style as the second argument.

The properties of the style array must include name and label:

  • name: The identifier of the style used to compute a CSS class.
  • label: A human-readable label for the style.

Besides the two mandatory properties, the styles properties array should also include an inline_style or a style_handle property:

  • inline_style: Contains inline CSS code that registers the CSS class required for the style.
  • style_handle: Contains the handle to an already registered style that should be enqueued in places where block styles are needed.

The following code sample registers a style for the quote block named “Blue Quote”, and provides an inline style that makes quote blocks with the “Blue Quote” style have blue color:

register_block_style(
    'core/quote',
    array(
        'name'         => 'blue-quote',
        'label'        => __( 'Blue Quote' ),
        'inline_style' => '.wp-block-quote.is-style-blue-quote { color: blue; }',
    )
);

Alternatively, if a stylesheet was already registered containing the CSS for the style variation, it is possible to just pass the stylesheet’s handle so register_block_style function will make sure it is enqueued properly.

wp_register_style( 'myguten-style', get_template_directory_uri() . '/custom-style.css' );

register_block_style(
    'core/quote',
    array(
        'name'         => 'fancy-quote',
        'label'        => 'Fancy Quote',
        'style_handle' => 'myguten-style',
    )
);

unregister_block_style

unregister_block_style allows unregistering a block style previously registered on the server using register_block_style.

The function’s first argument is the registered name of the block, and the name of the style as the second argument.

The following code sample unregisteres the style named ‘fancy-quote’ from the quote block:

unregister_block_style( 'core/quote', 'fancy-quote' );

Important: The function unregister_block_style only unregisters styles that were registered on the server using register_block_style. The function does not unregister a style registered using client-side code.

Related PRs: 16356.

Block Example API

WordPress 5.3 also includes the ability to preview blocks from the library before inserting them. This can help users figure out at a glance which block they want to insert.

To support this feature in your custom blocks, make sure to define the example property in your block settings.

 const blockSettings = {
  // ... other settings

  example: {
      attributes: { 
          content: __( 'Content of the block' )
      },
      innerBlocks: []
  }

}

registerBlockType( name, settings );

Related PRs: 17124.

Props to @jorgefilipecosta for helping with this dev note.

#5-3, #core-editor, #dev-notes