Gutenberg Server Registry Specification

[jasonbahl]

Problem

Gutenberg (The WordPress Block Editor) doesn't have a proper server registry for blocks. This makes it difficult for decoupled applications to interact with blocks in any meaningful way.

This issue was created to start conversation around what a specification for Server Side Registry for Gutenberg blocks might look like.

Goals

This is a WIP, but some goals off the top of my head:

• Allow Gutenberg blocks to be registered in PHP, enabling the WordPress application layer to know what blocks are, and allow APIs such as the WP REST API, WP CLI and WPGraphQL to interact with blocks
• Allow Introspection for blocks (REST API, CLI, WPGraphQL)
• Introspection should include full description of blocks, so that any remote client can render a block from the description (i.e. Inner Block support needs to be described on the client)
• Enable server validation of blocks (currently Gutenberg only has client validation)
• Blocks should be registered globally (much like registering scripts or registering post types) but should be able to be associated with different editorial contexts such as different post types (much like enqueueing scripts or setting a post_type to show in the REST API, or the admin).
• Block attributes, fields, meta need to be strongly typed. No "object" or "array" Types.
• Gutenberg blocks should store a unique ID in the database along with the block data. This likely needs to happen in Gutenberg core, not as a spec definition, but it will allow Blocks to be interacted one at a time. Features like block-locking and collaborative editing can be enabled, but only if each block can be uniquely identified by multiple clients.

Prior Art

• Gutenberg Fields Middleware
• ACF Blocks
• Genesis Custom Blocks

[mtias]

Would love to see some participation and help on the registration API work (there's a lot that got done there already) and the PHP APIs! Have you reviewed recently the register_block_type_from_metadata and related functions around block.json? Any further systematic construction of block attributes would need to account for save definitions in the context of non-decoupled systems.

Features like block-locking and collaborative editing can be enabled, but only if each block can be uniquely identified by multiple clients.

Just want to raise that this is not necessary. Client IDs are established in editing sessions but don't need to be persisted. You can see it working just fine in the collaboration prototype at #23129. There is also real-time collaboration implemented in https://asblocks.com/

[karamgaby]

I am ready to contribute; I would need some guidance on Graphql as that I am still new to Graphql.

I am currently working on a fork for the https://github.com/wp-graphql/wp-graphql-block-editor repo; I returned the Gutenberg blocks inside a post but still testing on how I could get the block fields and configurations.

The fork is available here https://github.com/wp-graphql/wp-graphql-block-editor.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[wilrevehl]

+1 Up vote! The thought occurred to me, now that ACF is under the WP Engine umbrella, maybe they would have the means to pitch in on this? Seeing as they're already saving a schema to expose to REST and make available to your plugin AND they are all-in on headless, this seems like a topic they could provide valuable insight on from the front lines.

[gziolo]

Would love to see some participation and help on the WordPress/gutenberg#16209 (there's a lot that got done there already) and WordPress/gutenberg#8352!

I wanted to share an update that we now have a living document that tracks all planned tasks related to improving Block API: WordPress/gutenberg#41236.

I thought it would be a good idea to discuss what progress have been made since the issue was opened.

Allow Gutenberg blocks to be registered in PHP, enabling the WordPress application layer to know what blocks are, and allow APIs such as the WP REST API, WP CLI and WPGraphQL to interact with blocks

All core blocks are registered with PHP. The requirement for the Block Directory is to have the block registered on the server. In fact, I expect all new blocks to use register_block_type and block.json block metadata format. WordPress 5.8 was the first release where we officially recommended using this approach and all the recent development in the block editor assumes that blocks get registered on the server so they can get all benefits from the integrations with other systems like Global Styles.

Allow Introspection for blocks (REST API, CLI, WPGraphQL)

Registered on the server block types can be discovered through the REST API endpoint: https://developer.wordpress.org/rest-api/reference/block-types/.

Introspection should include full description of blocks, so that any remote client can render a block from the description (i.e. Inner Block support needs to be described on the client)

I don’t think any block author explicitly mention that a given block supports inner blocks. It’s all based on the save implementation that uses <InnerBlocks.Content /> component. Although, I see some block attributes that are getting popular in that context like allowedBlocks or templateLock

Enable server validation of blocks (currently Gutenberg only has client validation)

We still don’t run server validation of blocks. The validation on the client is very strict and it's also tied to block deprecation that is JavaScript base. How do you envision it would work on the server?

Blocks should be registered globally (much like registering scripts or registering post types) but should be able to be associated with different editorial contexts such as different post types (much like enqueueing scripts or setting a post_type to show in the REST API, or the admin).

Blocks are registered globally, but we can use only allowed_block_types_all filter to control the context where they are filtered out. We should invest more time in that area to make it more flexible. There were some discussions to extend Block API to define more rules of when the block type should be present.

Block attributes, fields, meta need to be strongly typed. No "object" or "array" Types.

That's would be great to bring more structure to object and array types. Unfortunatelly, we didn't invest any time in improving that. There are a few occurrences where we liberally use general “object” or “array” types even for core blocks.

Gutenberg blocks should store a unique ID in the database along with the block data. This likely needs to happen in Gutenberg core, not as a spec definition, but it will allow Blocks to be interacted one at a time. Features like block-locking and collaborative editing can be enabled, but only if each block can be uniquely identified by multiple clients.

We still don’t store a unique ID in the database along with the block data. It’s something that might also be necessary for interactive blocks on the front end explored in https://github.com/WordPress/block-hydration-experiments. There is also an open proposal for adding A new system for simply and reliably updating HTML attributes to WordPress core that could be good enough for some to the use cases.

[justlevine]

Now that we got stalebot to behave, I'm marking this issue as stale?.
We still need to support blocks in core, but the discussion and implementation plan should take inspiration from the multiple WPGraphQL extensions experimenting with block support.

[drewbaker]

I was discussing this with @jasonbahl last week. Will post a few things on some progress.

So currently there are a few different approaches to using blocks in a headless fashion. The main plugins seem to be:

1. https://github.com/Automattic/vip-block-data-api
2. https://github.com/wpengine/wp-graphql-content-blocks
3. https://github.com/pristas-peter/wp-graphql-gutenberg
4. ... and our Funkhaus fork: https://github.com/funkhaus/wp-gql-gutenberg

So there is some significant work being done in the space. Currently, I'd say none of these solutions are "correct", but there is a lot to learn from them all.

I want to highlight this plugin that I found, useful for updating old blocks: https://github.com/pwkip/bulk-update-blocks

[drewbaker]

Gutenberg blocks should store a unique ID in the database along with the block data. This likely needs to happen in Gutenberg core, not as a spec definition, but it will allow Blocks to be interacted one at a time. Features like block-locking and collaborative editing can be enabled, but only if each block can be uniquely identified by multiple clients.

It seems to me, this can now be done with a filter: https://developer.wordpress.org/block-editor/reference-guides/filters/block-filters/#blocks-getsavecontent-extraprops

Something like this in JS:

function addBlockId( props ) {
    return {
        ...props,
        id: `block-${uuid()}`,
    };
}

wp.hooks.addFilter(
    'blocks.getSaveContent.extraProps',
    'wp-graphql/add-block-id,
    addBlockId
);

And it seems the same can be done server side with: https://developer.wordpress.org/reference/hooks/render_block/

So the ideal way would be to add post:$post->id,block:$uuid,type:$blockType as a hash for the id of each block. This would then allow for a way to query a specific block for a given post, or even all blocks of a certain type on a given post.