Docs: Fundamentals of Block Development - Registration of a block

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

@@ -0,0 +1,95 @@
+# Registration of a block
+
+A block is usually registered through a plugin on both the server and client-side using its `block.json` metadata. 
+
+Although technically, blocks could be registered only in the client, **registering blocks on both the server and in the client is a strong recommendation**. Some server-side features like Dynamic Rendering, Block Supports, Block Hooks, or Block style variations require the block to "exist" on the server, and they won't work properly without server registration of the block.
+
+For example, to allow a block [to be styled via `theme.json`](https://developer.wordpress.org/themes/global-settings-and-styles/settings/blocks/), it needs to be registered on the server, otherwise, any styles assigned to it in `theme.json` will be ignored. 
+
+[![Open Block Registration diagram in excalidraw](https://developer.wordpress.org/files/2023/11/block-registration-e1700493399839.png)](https://excalidraw.com/#json=PUQu7jpvbKsUHYfpHWn7s,61QnhpZtjykp3s44lbUN_g "Open Block Registration diagram in excalidraw")
+
+### Registration of the block with PHP (server-side)
+
+Block registration on the server usually takes place in the main plugin PHP file with the `register_block_type` function called on the [init hook](https://developer.wordpress.org/reference/hooks/init/).
+
+The [`register_block_type`](https://developer.wordpress.org/reference/functions/register_block_type/) function aims to simplify block type registration on the server by reading metadata stored in the `block.json` file.
+
+This function takes two params relevant in this context (`$block_type` accepts more types and variants):
+
+-   `$block_type` (`string`) – path to the folder where the `block.json` file is located or full path to the metadata file if named differently.
+-   `$args` (`array`) – an optional array of block type arguments. Default value: `[]`. Any arguments may be defined. However, the one described below is supported by default:
+    -   `$render_callback` (`callable`) – callback used to render blocks of this block type, it's an alternative to the `render` field in `block.json`.
+
+As part of the build process, the `block.json` file is usually copied from the `src` folder to the `build` folder, so the path to the `block.json` of your registered block should refer to the `build` folder.
+
+`register_block_type` returns the registered block type (`WP_Block_Type`) on success or `false` on failure.
+
+**Example:**
+```php
+register_block_type(
+	__DIR__ . '/notice',
+	array(
+		'render_callback' => 'render_block_core_notice',
+	)
+);
+```
+
+**Example:**
+```php
+function minimal_block_ca6eda___register_block() {
+	register_block_type( __DIR__ . '/build' );
+}
+
+add_action( 'init', 'minimal_block_ca6eda___register_block' );
+```
+_See the [full block example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/minimal-block-ca6eda) of the  [code above](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/minimal-block-ca6eda/index.php)_
+
+### Registration of the block with JavaScript (client-side)
+
+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.
+
+**Example:**
+
+```js
+registerBlockType( 'my-plugin/notice', {
+	edit: Edit,
+	// ...other client-side settings
+} );
+```
+
+Although registering the block also on the server with PHP is still recommended for the reasons mentioned at ["Benefits using the metadata file"](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#benefits-using-the-metadata-file), if you want to register it only client-side you can use [`registerBlockType`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-blocks/#registerblocktype) method from `@wordpress/blocks` package to register a block type using the metadata loaded from `block.json` file.
+
+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.
+-   `$settings` (`Object`) – client-side block settings.
+
+The client-side block settings object passed as a second parameter include two properties that are especially relevant:
+- `edit`: The React component that gets used in the editor for our block.
+- `save`: The React component that generates the static HTML markup that gets saved to the Database. 
+
+
+`registerBlockType` returns the registered block type (`WPBlock`) on success or `undefined` on failure.
+
+**Example:**
+
+```js
+import { registerBlockType } from '@wordpress/blocks';
+import metadata from './block.json';
+
+registerBlockType( metadata.name, {
+	edit() {
+		return <p>Hello World - Block Editor</p>;
+	},
+	save() {
+		return <p>Hello World - Frontend</p>;
+	},
+} );
+```
+_See the [code above](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/minimal-block-ca6eda/src/index.js) in [an example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/minimal-block-ca6eda)_
+
+## Additional resources
+
+- [`register_block_type` PHP function](https://developer.wordpress.org/reference/functions/register_block_type/)
+- [`registerBlockType` JS function](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-blocks/#registerblocktype)
+- [Why a block needs to be registered in both the server and the client?](https://github.com/WordPress/gutenberg/discussions/55884) | GitHub Discussion

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
-
-### PHP (server-side)
-
-The [`register_block_type`](https://developer.wordpress.org/reference/functions/register_block_type/) function that aims to simplify the block type registration on the server, can read metadata stored in the `block.json` file.
-
-This function takes two params relevant in this context (`$block_type` accepts more types and variants):
-
--   `$block_type` (`string`) – path to the folder where the `block.json` file is located or full path to the metadata file if named differently.
--   `$args` (`array`) – an optional array of block type arguments. Default value: `[]`. Any arguments may be defined. However, the one described below is supported by default:
-    -   `$render_callback` (`callable`) – callback used to render blocks of this block type, it's an alternative to the `render` field in `block.json`.
-
-It returns the registered block type (`WP_Block_Type`) on success or `false` on failure.
-
-**Example:**
-
-```php
-register_block_type(
-	__DIR__ . '/notice',
-	array(
-		'render_callback' => 'render_block_core_notice',
-	)
-);
-```
-
-### JavaScript (client-side)
-
-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.
-
-**Example:**
-
-```js
-registerBlockType( 'my-plugin/notice', {
-	edit: Edit,
-	// ...other client-side settings
-} );
-```
-
-Although registering the block also on the server with PHP is still recommended for the reasons above, if you want to register it only client-side you can now use `registerBlockType` method from `@wordpress/blocks` package to register a block type using the metadata loaded from `block.json` file.
-
-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.
--   `$settings` (`Object`) – client-side block settings.
-
-It returns the registered block type (`WPBlock`) on success or `undefined` on failure.
-
-**Example:**
-
-```js
-import { registerBlockType } from '@wordpress/blocks';
-import Edit from './edit';
-import metadata from './block.json';
-
-registerBlockType( metadata, {
-	edit: Edit,
-	// ...other client-side settings
-} );
-```
-
 ## Block API
 
 This section describes all the properties that can be added to the `block.json` file to define the behavior and metadata of block types.