Docs: Fundamentals of Block Development - Registration of a block #56334
Conversation
juanmaguitar
requested review from
ajitbohra,
ryanwelcher,
fabiankaegy and
ndiego
as code owners
juanmaguitar
added
the
[Type] Developer Documentation
juanmaguitar
changed the title
juanmaguitar
changed the title
juanmaguitar
changed the title
|
Flaky tests detected in e436065. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/6943045213
|
juanmaguitar
added
the
Developer Experience
|
|
||
| A block is usually registered through a plugin in both the server and the client using its `block.json` metadata. | ||
|
|
||
| Although technically, blocks could be registered only on the client, **registering blocks in both the server and the client is a general recommendation**, as some features like Dynamic Rendering, Block Hooks, or Block style variations won't work properly without a server registration of the block. |
There was a problem hiding this comment.
I would say that the one very important aspect is missing - it's the entire Style Engine. @oandregal, what would be the way to describe it so it's obvious that registration on the server for block supports is essential for CSS styles to be generated for blocks?
There was a problem hiding this comment.
I haven't reviewed everything, but the existing text sounds about right.
I don't know how deep you want to go into this, or if you rather link to existing documents. What I could add is that "global styles" (styles generated from theme.json) require blocks to be registered in the server – otherwise, it's like they don't exist, and any styles assigned to them in theme.json will be ignored. This only matters if the block aims to be styled via theme.json, of course.
I presume the same would be true for all features that generate styles in the server (block supports, layout, style engine, etc.). @aaronrobertshaw @ramonjd @andrewserong @tellthemachines have implemented most of it. They know more than I do on this topic!
There was a problem hiding this comment.
Excellent feedback André. Much appreciate inviting other implementers to share more context 🙇🏻
There was a problem hiding this comment.
Thanks @gziolo @oandregal for the feedback!
I've updated the PR taking this feedback into account.
Let me know your thoughts.
I don't know how deep you want to go into this, or if you rather link to existing documents.
The purpose of this "Getting Started > Fundamentals of Block Development" is to introduce key ideas to help developers have a better "onboarding" experience for block development. Links to other parts of the Handbook will be used for more details, but in some specific cases, the content will be directly "moved" to this section.
There was a problem hiding this comment.
Hi folks, thanks for the ping, and great work on the docs.
In relation to the style engine, along with the general README/usage docs there is some block-supports-specific documentation written here:
And there's the handbook entry for block supports.
As @juanmaguitar suggests, maybe it's enough to refer and link to the relevant docs as appropriate should folks wish to enable block supports features to their newly-registered block?
P.S., Going over this stuff made me realize I need to update the style engine block supports docs so I have a PR to do that 😆 So thank you!
docs/getting-started/fundamentals-block-development/registration-of-a-block.md
Outdated
Show resolved
Hide resolved
docs/getting-started/fundamentals-block-development/registration-of-a-block.md
Outdated
Show resolved
Hide resolved
docs/getting-started/fundamentals-block-development/registration-of-a-block.md
Outdated
Show resolved
Hide resolved
docs/getting-started/fundamentals-block-development/registration-of-a-block.md
Outdated
Show resolved
Hide resolved
docs/getting-started/fundamentals-block-development/registration-of-a-block.md
Outdated
Show resolved
Hide resolved
docs/getting-started/fundamentals-block-development/registration-of-a-block.md
Outdated
Show resolved
Hide resolved
…on-of-a-block.md Co-authored-by: Ramon <[email protected]>
…on-of-a-block.md Co-authored-by: Ramon <[email protected]>
…on-of-a-block.md Co-authored-by: Ramon <[email protected]>
…on-of-a-block.md Co-authored-by: Ramon <[email protected]>
…on-of-a-block.md Co-authored-by: Ramon <[email protected]>
…on-of-a-block.md Co-authored-by: Ramon <[email protected]>
@ramonjd Thanks a lot for your suggestions. 🙏 |
|
There are some JS unit test failures, but they seem unrelated. It might help to rebase with the |
| @@ -77,66 +77,6 @@ Development is improved by using a defined schema definition file. Supported edi | |||
| "$schema": "https://schemas.wp.org/trunk/block.json" | |||
| ``` | |||
|
|
|||
| ## Block registration | |||
There was a problem hiding this comment.
It would be valuable to link the newly created documentation page, so it's clear that block.json still needs to be wired with PHP and can be used in JavaScript if folks needs access to the same properties.
| @@ -61,14 +61,13 @@ Although registering the block also on the server with PHP is still recommended | |||
|
|
|||
| The function takes two params: | |||
|
|
|||
| - `$blockNameOrMetadata` (`string`|`Object`) – block type name (supported previously) or the metadata object loaded from the `block.json` file with a bundler (e.g., webpack) or a custom Babel plugin. | |||
| - `$blockNameOrMetadata` (`string`|`Object`) – block type name (if previously registered on the server) or the metadata object loaded from the `block.json` file with a bundler (e.g., webpack) or a custom Babel plugin. | |||
There was a problem hiding this comment.
The block can be registered only on the client, so I'm not sure whether the rephrased part fits in that case. Otherwise, it's valid.
There was a problem hiding this comment.
The text in parenthesis (if previously registered on the server) meant to clarify that registering a block in the client only using block type name only works when the block's metadata has been previously registered on the server.
I'm not sure what (supported previously) is referring to.
But I think I can remove this clarification as this is already explained at the beginning of the Registration of the block with JavaScript (client-side) section
When the block is registered on the server, you only need to register the client-side settings on the client using the same block’s name.
juanmaguitar
deleted the
fundamentals-block-development/registration-of-a-block
branch
…6334) * Add block registration documentation * Update block registration process * Update block registration in client code * updated doc * Update block registration settings * Grammar check * Moved Registration of A block to fundamentals of block development * Added maarkdown extension * Delete docs/getting-started/fundamentals-block-development/registration-of-a-block * Removed "key" * clarification path block.json * Fix block.json registration path * server-side features require block server registration * server-side features require block server registration * Update docs/getting-started/fundamentals-block-development/registration-of-a-block.md Co-authored-by: Ramon <[email protected]> * Update docs/getting-started/fundamentals-block-development/registration-of-a-block.md Co-authored-by: Ramon <[email protected]> * Update docs/getting-started/fundamentals-block-development/registration-of-a-block.md Co-authored-by: Ramon <[email protected]> * Update docs/getting-started/fundamentals-block-development/registration-of-a-block.md Co-authored-by: Ramon <[email protected]> * Update docs/getting-started/fundamentals-block-development/registration-of-a-block.md Co-authored-by: Ramon <[email protected]> * Update docs/getting-started/fundamentals-block-development/registration-of-a-block.md Co-authored-by: Ramon <[email protected]> * Fix formatting in registration-of-a-block.md * Added link to new page and some text adjustments * Update block registration function and build process reference --------- Co-authored-by: Ramon <[email protected]>
Surfaces documentation for registering a block
This PR closes the issue #55943
This PR proposes surfacing the info about how to register a block to an earlier step in the learning journey (
Getting Started > Fundamentals of Block Development > Registration of a block). In order to do this, in this PR the info about how to register a block has been moved fromReference Guides > Block API > Metadata in block.json > Registration of a blockto this new page that is part of a new section aimed to improve the onboarding of Block developersThe merge of this PR should also trigger the following redirections:
cc: @gziolo