Docs: Fundamentals of Block Development - Registration of a block #56334

juanmaguitar · 2023-11-20T18:30:07Z

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 from Reference Guides > Block API > Metadata in block.json > Registration of a block to this new page that is part of a new section aimed to improve the onboarding of Block developers

The merge of this PR should also trigger the following redirections:

cc: @gziolo

…on-of-a-block

github-actions · 2023-11-21T11:36:42Z

Flaky tests detected in e436065.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/6943045213
📝 Reported issues:

[Flaky Test] should partially select with shift + click (@webkit) #53524 in /test/e2e/specs/editor/various/multi-block-selection.spec.js

gziolo · 2023-11-24T08:35:27Z

docs/getting-started/fundamentals-block-development/registration-of-a-block.md

+
+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. 


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?

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!

Excellent feedback André. Much appreciate inviting other implementers to share more context 🙇🏻

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.

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:

https://github.com/WordPress/gutenberg/blob/trunk/packages/style-engine/docs/using-the-style-engine-with-block-supports.md

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!

ramonjd

I left mostly very pedantic suggestions :) Thanks!

docs/getting-started/fundamentals-block-development/registration-of-a-block.md

…on-of-a-block.md Co-authored-by: Ramon <ramonjd@users.noreply.github.com>

juanmaguitar · 2023-11-26T10:01:27Z

I left mostly very pedantic suggestions :) Thanks!

@ramonjd Thanks a lot for your suggestions. 🙏
I think they made the texts better. I have accepted them.

gziolo · 2023-11-27T11:19:24Z

There are some JS unit test failures, but they seem unrelated. It might help to rebase with the trunk.

gziolo · 2023-11-27T11:25:34Z

docs/reference-guides/block-api/block-metadata.md

@@ -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


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.

…-of-a-block

gziolo

Thank you for working on this new page. It's going to be very helpful in explaining the importance of the server-side registration with WordPress.

gziolo · 2023-11-27T12:49:02Z

docs/getting-started/fundamentals-block-development/registration-of-a-block.md

@@ -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.


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.

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.

…-of-a-block

…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 <ramonjd@users.noreply.github.com> * Update docs/getting-started/fundamentals-block-development/registration-of-a-block.md Co-authored-by: Ramon <ramonjd@users.noreply.github.com> * Update docs/getting-started/fundamentals-block-development/registration-of-a-block.md Co-authored-by: Ramon <ramonjd@users.noreply.github.com> * Update docs/getting-started/fundamentals-block-development/registration-of-a-block.md Co-authored-by: Ramon <ramonjd@users.noreply.github.com> * Update docs/getting-started/fundamentals-block-development/registration-of-a-block.md Co-authored-by: Ramon <ramonjd@users.noreply.github.com> * Update docs/getting-started/fundamentals-block-development/registration-of-a-block.md Co-authored-by: Ramon <ramonjd@users.noreply.github.com> * 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 <ramonjd@users.noreply.github.com>

juanmaguitar added 5 commits November 20, 2023 12:42

Add block registration documentation

6355ef2

Update block registration process

d6277a6

Update block registration in client code

ff1cef8

updated doc

413fbbf

Update block registration settings

7dd94ea

juanmaguitar requested review from ajitbohra, ryanwelcher, fabiankaegy and ndiego as code owners November 20, 2023 18:30

juanmaguitar added the [Type] Developer Documentation Documentation for developers label Nov 20, 2023

juanmaguitar changed the title ~~Fundamentals block development/registration of a block~~ Docs: Fundamentals block development - Registration of a block Nov 20, 2023

juanmaguitar changed the title ~~Docs: Fundamentals block development - Registration of a block~~ Docs: Fundamentals of Block development - Registration of a block Nov 20, 2023

juanmaguitar changed the title ~~Docs: Fundamentals of Block development - Registration of a block~~ Docs: Fundamentals of Block Development - Registration of a block Nov 20, 2023

juanmaguitar requested a review from gziolo November 21, 2023 08:36

juanmaguitar and others added 4 commits November 21, 2023 10:20

Grammar check

83f4fdb

Moved Registration of A block to fundamentals of block development

e436065

Added maarkdown extension

6450388

Delete docs/getting-started/fundamentals-block-development/registrati…

af24db7

…on-of-a-block

juanmaguitar added 3 commits November 21, 2023 11:51

Removed "key"

64f131f

clarification path block.json

a2b7d0a

Fix block.json registration path

454ccd7

juanmaguitar added the Developer Experience Ideas about improving block and theme developer experience label Nov 22, 2023

gziolo reviewed Nov 24, 2023

View reviewed changes

server-side features require block server registration

b5ecd9a

juanmaguitar requested review from gziolo and oandregal November 24, 2023 20:20

server-side features require block server registration

33a8ea8

ramonjd reviewed Nov 26, 2023

View reviewed changes

Update docs/getting-started/fundamentals-block-development/registrati…

4f6fb44

…on-of-a-block.md Co-authored-by: Ramon <ramonjd@users.noreply.github.com>

juanmaguitar and others added 5 commits November 26, 2023 10:59

Update docs/getting-started/fundamentals-block-development/registrati…

41e9101

…on-of-a-block.md Co-authored-by: Ramon <ramonjd@users.noreply.github.com>

Update docs/getting-started/fundamentals-block-development/registrati…

66ff132

…on-of-a-block.md Co-authored-by: Ramon <ramonjd@users.noreply.github.com>

Update docs/getting-started/fundamentals-block-development/registrati…

0245933

…on-of-a-block.md Co-authored-by: Ramon <ramonjd@users.noreply.github.com>

Update docs/getting-started/fundamentals-block-development/registrati…

e0954ec

…on-of-a-block.md Co-authored-by: Ramon <ramonjd@users.noreply.github.com>

Update docs/getting-started/fundamentals-block-development/registrati…

4ee9abc

…on-of-a-block.md Co-authored-by: Ramon <ramonjd@users.noreply.github.com>

juanmaguitar requested a review from ramonjd November 26, 2023 10:01

Fix formatting in registration-of-a-block.md

45ef201

gziolo reviewed Nov 27, 2023

View reviewed changes

juanmaguitar added 2 commits November 27, 2023 12:06

Merge branch 'trunk' into fundamentals-block-development/registration…

965aa74

…-of-a-block

Added link to new page and some text adjustments

7e152a3

gziolo approved these changes Nov 27, 2023

View reviewed changes

juanmaguitar added 3 commits November 27, 2023 13:15

Update block registration function and build process reference

f56a645

Merge branch 'trunk' into fundamentals-block-development/registration…

de5bb8a

…-of-a-block

Merge branch 'trunk' into fundamentals-block-development/registration…

9bcd5ba

…-of-a-block

juanmaguitar merged commit 26033ae into trunk Nov 28, 2023
51 checks passed

juanmaguitar deleted the fundamentals-block-development/registration-of-a-block branch November 28, 2023 05:16

github-actions bot added this to the Gutenberg 17.2 milestone Nov 28, 2023

This was referenced Nov 28, 2023

Fundamentals block development - landing and first pages #56584

Merged

Getting Started > Fundamentals of Block Development > Registration of a block #55943

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: Fundamentals of Block Development - Registration of a block #56334

Docs: Fundamentals of Block Development - Registration of a block #56334

juanmaguitar commented Nov 20, 2023 •

edited

Loading

github-actions bot commented Nov 21, 2023

gziolo Nov 24, 2023 •

edited

Loading

oandregal Nov 24, 2023

gziolo Nov 24, 2023 •

edited

Loading

juanmaguitar Nov 24, 2023 •

edited

Loading

ramonjd Nov 26, 2023 •

edited

Loading

ramonjd left a comment

juanmaguitar commented Nov 26, 2023

gziolo commented Nov 27, 2023

gziolo Nov 27, 2023

gziolo left a comment

gziolo Nov 27, 2023

juanmaguitar Nov 27, 2023 •

edited

Loading


		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.

Docs: Fundamentals of Block Development - Registration of a block #56334

Docs: Fundamentals of Block Development - Registration of a block #56334

Conversation

juanmaguitar commented Nov 20, 2023 • edited Loading

github-actions bot commented Nov 21, 2023

gziolo Nov 24, 2023 • edited Loading

Choose a reason for hiding this comment

oandregal Nov 24, 2023

Choose a reason for hiding this comment

gziolo Nov 24, 2023 • edited Loading

Choose a reason for hiding this comment

juanmaguitar Nov 24, 2023 • edited Loading

Choose a reason for hiding this comment

ramonjd Nov 26, 2023 • edited Loading

Choose a reason for hiding this comment

ramonjd left a comment

Choose a reason for hiding this comment

juanmaguitar commented Nov 26, 2023

gziolo commented Nov 27, 2023

gziolo Nov 27, 2023

Choose a reason for hiding this comment

gziolo left a comment

Choose a reason for hiding this comment

gziolo Nov 27, 2023

Choose a reason for hiding this comment

juanmaguitar Nov 27, 2023 • edited Loading

Choose a reason for hiding this comment

juanmaguitar commented Nov 20, 2023 •

edited

Loading

gziolo Nov 24, 2023 •

edited

Loading

gziolo Nov 24, 2023 •

edited

Loading

juanmaguitar Nov 24, 2023 •

edited

Loading

ramonjd Nov 26, 2023 •

edited

Loading

juanmaguitar Nov 27, 2023 •

edited

Loading