Block API: Extend register_block_type_from_metadata to handle assets

[gziolo]

Description

The changes in this PR follow the solution proposed in Block Registration RFC:

https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#assets

Assets

WPDefinedAsset

The WPDefinedAsset type is a subtype of string, where the value represents a path to a JavaScript or CSS file relative to where block.json file is located. The path provided must be prefixed with file:. This approach is based on how npm handles local paths for packages.

An alternative would be a script or style handle name referencing a registered asset using WordPress helpers.

Example:

In block.json:

{
	"editorScript": "file:./build/index.js",
	"editorStyle": "my-editor-style"
}

WordPress context

In the context of WordPress, when a block is registered with PHP, it will automatically register all scripts and styles that are found in the block.json file and use file paths rather than asset handles.

That's why, the WPDefinedAsset type has to offer a way to mirror also the shape of params necessary to register scripts and styles using wp_register_script and wp_register_style, and then assign these as handles associated with your block using the script, style, editor_script, and editor_style block type registration settings.

It's possible to provide an object which takes the following shape:

• handle (string) - the name of the script. If omitted, it will be auto-generated.
• dependencies (string[]) - an array of registered script handles this script depends on. Default value: [].
• version (string|false|null) - string specifying the script version number, if it has one, which is added to the URL as a query string for cache busting purposes. If the version is set to false, a version number is automatically added equal to current installed WordPress version. If set to null, no version is added. Default value: false.

The definition is stored inside separate PHP file which ends with .asset.php and is located next to the JS/CSS file listed in block.json. WordPress will automatically detect this file through pattern matching. This option is the preferred one as it is expected it will become an option to auto-generate those asset files with @wordpress/scripts package.

Example:

build/
├─ index.js
└─ index.asset.php

In block.json:

{ "editorScript": "file:./build/index.js" }

In build/index.asset.php:

<?php
return array(
	'dependencies' => array(
		'wp-blocks',
		'wp-element',
		'wp-i18n',
	),
	'version'      => '3be55b05081a63d8f9d0ecb466c42cfd',
);

Motivation

npm init @wordpress/block creates a lot of boilerplate code in PHP file to load a single block. This is a way to simplify it to a single function call in the init hook:

function create_block_esnext_example_block_init() {
	register_block_type_from_metadata( __DIR__ );
}
add_action( 'init', 'create_block_esnext_example_block_init' );

In the future, it should make it possible to use block.json as an entry point for blocks crafted to be included in Block Directory!

Testing

I personally did the following steps to test this PR. I executed Create Block to have a block to play with all the defaults:

npx wp-create-block esnext-example

I moved then this folder to lib folder to make it simple to include.

I added the following block.json file inside lib/esnext-example

{
    "name": "create-block/esnext-example",
    "editorScript": "file:./build/index.js",
    "editorStyle": "file:./editor.css",
    "style": "file:./style.css"
}

I replaced lib/esnext-example/esnext-example.php with:

<?php

function create_block_esnext_example_block_init() {
	register_block_type_from_metadata( __DIR__ );
}
add_action( 'init', 'create_block_esnext_example_block_init' );

And I made sure it's required in lib/load.php.

I made sure that I can insert this block and inspected source code to confirm it properly generates in the codebase the HTML tags for assets like:

<link rel="stylesheet" id="create-block-esnext-example-style-css"  href="http://localhost:8888/wp-content/plugins/gutenberg/lib/esnext-example/style.css?ver=1590053988" media="all" />
<link rel="stylesheet" id="create-block-esnext-example-editor-style-css"  href="http://localhost:8888/wp-content/plugins/gutenberg/lib/esnext-example/editor.css?ver=1590053988" media="all" />
<script src="http://localhost:8888/wp-content/plugins/gutenberg/lib/esnext-example/build/index.js?ver=c2283d6c83cb6f4b35398b803ac62056"></script>

Follow up tasks

• Improve the way version is generated for CSS files as noted by @aduth in Block API: Extend register_block_type_from_metadata to handle assets #22519 (comment)

Checklist:

• My code is tested.
• My code follows the WordPress code style.
• [N/A] My code follows the accessibility standards.
• My code has proper inline documentation.
• I've included developer documentation if appropriate.
• [N/A] I've updated all React Native files affected by any refactorings/renamings in this PR.

[github-actions]

Size Change: 0 B

Total Size: 1.12 MB

ℹ️ View Unchanged

Filename	Size	Change
build/a11y/index.js	1.14 kB	0 B
build/annotations/index.js	3.62 kB	0 B
build/api-fetch/index.js	3.4 kB	0 B
build/autop/index.js	2.83 kB	0 B
build/blob/index.js	620 B	0 B
build/block-directory/index.js	6.75 kB	0 B
build/block-directory/style-rtl.css	892 B	0 B
build/block-directory/style.css	892 B	0 B
build/block-editor/index.js	106 kB	0 B
build/block-editor/style-rtl.css	11.4 kB	0 B
build/block-editor/style.css	11.4 kB	0 B
build/block-library/editor-rtl.css	7.87 kB	0 B
build/block-library/editor.css	7.88 kB	0 B
build/block-library/index.js	126 kB	0 B
build/block-library/style-rtl.css	7.69 kB	0 B
build/block-library/style.css	7.68 kB	0 B
build/block-library/theme-rtl.css	684 B	0 B
build/block-library/theme.css	686 B	0 B
build/block-serialization-default-parser/index.js	1.88 kB	0 B
build/block-serialization-spec-parser/index.js	3.1 kB	0 B
build/blocks/index.js	48.2 kB	0 B
build/components/index.js	193 kB	0 B
build/components/style-rtl.css	19.5 kB	0 B
build/components/style.css	19.5 kB	0 B
build/compose/index.js	9.31 kB	0 B
build/core-data/index.js	11.4 kB	0 B
build/data-controls/index.js	1.29 kB	0 B
build/data/index.js	8.46 kB	0 B
build/date/index.js	5.47 kB	0 B
build/deprecated/index.js	771 B	0 B
build/dom-ready/index.js	568 B	0 B
build/dom/index.js	3.11 kB	0 B
build/edit-navigation/index.js	8.25 kB	0 B
build/edit-navigation/style-rtl.css	878 B	0 B
build/edit-navigation/style.css	876 B	0 B
build/edit-post/index.js	302 kB	0 B
build/edit-post/style-rtl.css	5.43 kB	0 B
build/edit-post/style.css	5.43 kB	0 B
build/edit-site/index.js	15 kB	0 B
build/edit-site/style-rtl.css	2.96 kB	0 B
build/edit-site/style.css	2.96 kB	0 B
build/edit-widgets/index.js	8.83 kB	0 B
build/edit-widgets/style-rtl.css	2.4 kB	0 B
build/edit-widgets/style.css	2.4 kB	0 B
build/editor/editor-styles-rtl.css	425 B	0 B
build/editor/editor-styles.css	428 B	0 B
build/editor/index.js	44.7 kB	0 B
build/editor/style-rtl.css	4.26 kB	0 B
build/editor/style.css	4.27 kB	0 B
build/element/index.js	4.65 kB	0 B
build/escape-html/index.js	733 B	0 B
build/format-library/index.js	7.72 kB	0 B
build/format-library/style-rtl.css	502 B	0 B
build/format-library/style.css	502 B	0 B
build/hooks/index.js	2.13 kB	0 B
build/html-entities/index.js	621 B	0 B
build/i18n/index.js	3.56 kB	0 B
build/is-shallow-equal/index.js	711 B	0 B
build/keyboard-shortcuts/index.js	2.52 kB	0 B
build/keycodes/index.js	1.94 kB	0 B
build/list-reusable-blocks/index.js	3.12 kB	0 B
build/list-reusable-blocks/style-rtl.css	226 B	0 B
build/list-reusable-blocks/style.css	226 B	0 B
build/media-utils/index.js	5.3 kB	0 B
build/notices/index.js	1.79 kB	0 B
build/nux/index.js	3.4 kB	0 B
build/nux/style-rtl.css	616 B	0 B
build/nux/style.css	613 B	0 B
build/plugins/index.js	2.56 kB	0 B
build/primitives/index.js	1.5 kB	0 B
build/priority-queue/index.js	789 B	0 B
build/redux-routine/index.js	2.85 kB	0 B
build/rich-text/index.js	14.8 kB	0 B
build/server-side-render/index.js	2.68 kB	0 B
build/shortcode/index.js	1.7 kB	0 B
build/token-list/index.js	1.28 kB	0 B
build/url/index.js	4.06 kB	0 B
build/viewport/index.js	1.85 kB	0 B
build/warning/index.js	1.14 kB	0 B
build/wordcount/index.js	1.17 kB	0 B

_{compressed-size-action}

[gziolo]

I think I added enough tests to ensure it works as expected. Let me know if there are any blockers that would prevent moving forward with this proposal.

[gziolo]

I don't see any more feedback, then let's proceed. We can iterate further later if there are some things discovered. We still need to add functionality that covers i18n handling for the metadata stored in block.json to make it work with the WP-CLI integration added by @swissspidy in wp-cli/i18n-command#210.

[noahtallen]

@gziolo I think this broke the post content block. Before this commit there is no issue, but after this commit, the post title and post content blocks do not work. It appears to be related to block context not being set properly 🤔 (Trying to see what would have changed that!)

[noahtallen]

see #23179

[noahtallen]

fix was just to add a property for context here. see #23180

[gziolo]

We also need to add providesContext there.