Block API: Extend the block registration API technical proposal

[gziolo]

Continues the work toward server-side awareness of block types: #2751 and follow-up for #13693.

Development Roadmap

This highly related to core blocks and the way they integrate with WordPress.

• Use inline JSON babel plugin as the first step with one block (Block library: Try to use Babel plugins to inline block.json metadata #14551)
• Standardize file structure of core blocks for icon and edit fields (Block library: Standardize file structure of core blocks #14743)
• Refactor client-side blocks to define name, category and attributes in block.json (Block library: Introduce block.json metadata for all client side blocks #14770, Refactor File block to use block.json metadata #14862, Refactor Tabel block to use block.json metadata #14863)
• Extract translatable strings from block.json files (Extract translatable strings from block.json files wp-cli/i18n-command#163)
• Move transforms and save fields to their own files (Refactor File block to use block.json metadata #14862, Refactor Tabel block to use block.json metadata #14863, Refactor core blocks to have save and transforms in their own files (part 1) #14882, Refactor core blocks to have save and transforms in their own files (part 2) #14899, Refactor core blocks to have save and transforms in their own files (part 3) #14902, Refactor core blocks to have save and transforms in their own files (part 4) #14903)
• Move all remaining fields like merge or deprecated to their own files (Refactor core blocks to have deprecated extracted to their own files (p.1) #14979, Block library: Extract deprecated field to their own files #15057, Block library: Extract deprecated field to their own files (p.2) #15071)
• Add new utility to register block types from metadata in PHP (Block API: Add new utility to register block types from metadata in PHP #20794)
• Figure out the way to register all static blocks on the server with some custom Gutenberg specific loader based on the block.json (reuse code from Introduce block metadata files for dynamic blocks #14238)
• Make it possible to integrate all asset-based fields into block.json to make them work with both PHP and JavaScript (Block API: Extend register_block_type_from_metadata to handle assets #22519)
• Convert Block Registration RFC to the Block Metadata document (Docs: Convert Block Registration RFC to the Block Metadata document #23832)
• Refactor registerBlockType and register_block_type_from_metadata to autowrap translatable fields from block.json with _x (Block API: Add i18n support to block.json metadata file #23636, Blocks: Introduce registerBlockTypeFromMetadata API #30293)
• Move translatable fields (title, description, keywords, styles.label) to block.json (Block Library: Move translatable fields to block.json files for core blocks #23792)
• Refactor Embed block to use block.json and block variations (Block Library: Refactor Embed block to use block.json and block variations #22660)
• Create standalone JSON schema for block type definition to make it possible to validate block.json files and annotate translatable fields (https://core.trac.wordpress.org/ticket/50615, Blocks: Introduce registerBlockTypeFromMetadata API #30293)

Proposals

There are some items that weren't included in the initial proposal which should be processed and included based on the further discussion. Many of the items discussed are very WordPress specific and therefore we need to find a good way to make it explicit what is truly platform agnostic and what is meant to be work only when using it with WordPress.

New screenshot property

From @perandre in #13693 (comment)

Implementing a standard for block screenshot would be valuable. Size, format, what it should contain and not contain.

This seems like a good addition in the context of the block discovery when it isn't installed.

Auto-discover of block.json metadata file

The original discussion sparked by a comment from @moorscode in #13693 (comment).

WordPress automatically discovers all the block.json files in the plugin/core blocks folder and registers the corresponding block types. These block types are made available through the block registry PHP class and the blocks scripts and styles are added as dependencies to the wp-block-library script and style handles.

This is WordPress specific and that's why it wasn't included in the first version. We definitely want to have it implemented but this might be added after some code exploration which will make it easier to solidify.

Client-side properties referenced as files

This was removed from the initial proposal (see this commit: 5ec9cd9) as noted in #13693 (comment):

I removed the following properties from this document:

• save
• edit
• transforms
• deprecated

The idea was to keep them referenced from block.json file but this seemed to be a bit confusing in relation to the assets you would normally enqueue in WordPress. This is something we will revisit later as it doesn't seem to be essential for the Block Directory project.

I think we should continue exploring this idea as this could give us some ways to optimize the size of assets loaded by deferring the moment when those files are loaded on the page. In particular deprecated and edit fields loaded only when they are actually used could bring some performance optimizations in case of blocks heavy loaded with JavaScript logic.

Extend flexibility of parent property

Also filed in #30679 by @priethor.

See comment from @aduth in #13693 (comment):

• If and when Enables Block Grouping/UnGrouping using core/group #14908, there will be precedent for wildcards in block transforms (source), and it certainly seems like an equivalent behavior could be implemented for parent.

We should create a follow-on issue for this. That said, it's not directly mentioned as being possible in this RFC. Which begs the question: Should it be, if we're saying it ought to be possible?

Consider adding renderTemplate property

See comment from @spacedmonkey in #13693 (comment):

Current the render callback is a function call. How would it work as a file? Why not make it renderTemplate but still allow for renderCallback. Function calls, should be a method in a class or be namespaced, which wouldn't really work in a another file.

ACF blocks, has a rendercallback / render template in it's block definitions.

There is also another thread started by @spacedmonkey in #13693 (comment) which expands on this topic.

[paaljoachim]

Should this issue be closed, Greg @gziolo ?

[gziolo]

No, there are open tasks.

[gziolo]

Consider adding renderTemplate property

@ryelle, I was thinking about this proposal again and it might be a great fit for extending what Block Directory can support. If we would ensure that the file you reference outputs the HTML for the block on the frontend and it can only use the same attributes that render_callback accepts. In general, render_template would work as a more limited version of render_callback.

[gziolo]

I consider all items from to-do list as done. Let's close this issue and continue working on individual enhancements separately:

• Extend the block.json specification to be able to restrict blocks to particular templates (Extend the Block.json specification to be able to restrict blocks to particular templates #30679).
• Create standalone JSON schema for block type definition to make it possible to validate block.json files and annotate translatable field (https://core.trac.wordpress.org/ticket/50615)
• Enqueue script and style assets only for blocks present on the page (https://core.trac.wordpress.org/ticket/50328)
• Consider adding renderTemplate property for block types (https://core.trac.wordpress.org/ticket/53148)
• Consider using block.json file as an entry point for blocks from Block Directory (https://core.trac.wordpress.org/ticket/53149)

[mtias]

Nice work driving these @gziolo