Block API changes in WordPress 6.1

WordPress 6.1 introduces several new 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. 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. features available via the block.json file.

As a recap, the block.json file was introduced in WordPress 5.5 and has been encouraged as the canonical way of registering block types since the WordPress 5.8 release. Many of the recent Block API features, including the ones in this post, depend on block.json being available on the server.

PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher templates for rendering blocks

Before WordPress 6.1, the main output of a block would often be generated in either a 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. save function, or in a PHP render_callback function.

WordPress 6.1 adds a third way: a separate PHP template file. The path can be specified via the render property of block.json:

    "render": "file:./render.php"

If you don’t have a render_callback setting specified, then the template is used instead. It behaves similarly, but feels much more like traditional WordPress template handling.

The template path is prefixed with file: and relative to the location of the block.json file, following the npm specification.

The render.php template could look like this:

<p <?php echo get_block_wrapper_attributes(); ?>>
    <?php esc_html_e( 'Hello from a dynamic block!', 'my-plugin' ); ?>

Note: The entire file is used as a template, so there’s no need to define additional wrapping functions.

The following variables are available inside the template:

  • $attributes (array): The block attributes.
  • $content (string): The block default content.
  • $block (WP_Block): The block instance.

Use multiple scripts per block

The WordPress 6.1 version enables defining multiple script files in all relevant block.json entries: editScript, script, and viewScript. (Trac #56408) It’s now possible to pass a script handle registered with the wp_register_script function, a path to a JavaScript file relative to the block.json file, or an array with a mix of both:

    "editorScript": "file:./index.js",
    "script": "file:./script.js",
    "viewScript": [ "file:./view.js", "example-shared-view-script" ]

WordPress maintains a degree of backwards compatibility by passing along only the first (string) item to any existing code working with these values.

Note: Processing a single string requires a different code than processing an array of strings. Therefore, the WP_Block_Type class and the /wp/v2/block-types 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”) endpoint deprecate accessing string values through their old names: editor_script, script, view_script, editor_style, and style.

The full array of scripts can be accessed via the following new properties of the WP_Block_Type class and the /wp/v2/block-types REST API endpoint:

  • editor_script_handles,
  • script_handles,
  • view_script_handles,
  • editor_style_handles, and
  • style_handles.

Furthermore, the scripts and styles registered in block.json will automatically be loaded for static and dynamic blocks in WordPress 6.1. Previously, the dynamic blocks were expected to register their assets.

Combined with the support for multiple stylesheets per block shipped with WordPress 5.9, this change enables developers to use multiple entries for all supported asset types.

Import individual coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. blocks from @wordpress/block-library

The import of individual core blocks (Pull request #42258) from the @wordpress/block-library npm package was enabled to help developers reduce the bundle size of their applications. Prior to this change, the use of a single core block required pulling in the entire set.

Individual core blocks can be imported in three different ways:

// You can import and automatically register the block:
import '@wordpress/block-library/build-module/verse/init';

// Or you can automatically register the block and reuse the reference:
import verseBlock from '@wordpress/block-library/build-module/verse/init';

// Or you can import the init function without registering the block…
import { init } from '@wordpress/block-library/build-module/verse';

// …and then register the block when needed:
const verseBlock = init();

Props to @gziolo, and @revgeorge for technical review, to @bph and @webcommsat for final review.

#6-1, #dev-notes, #dev-notes-6-1, #developer-documentation