diff --git a/docs/getting-started/fundamentals/registration-of-a-block.md b/docs/getting-started/fundamentals/registration-of-a-block.md index 65cd85b0fa3e5b..d8d547912c7484 100644 --- a/docs/getting-started/fundamentals/registration-of-a-block.md +++ b/docs/getting-started/fundamentals/registration-of-a-block.md @@ -1,81 +1,79 @@ # Registration of a block -A block is usually registered through a plugin on both the server and client-side using its `block.json` metadata. +Blocks in WordPress are typically bundled in a plugin and registered on both the server and client-side using `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. +While it's possible to register blocks solely on the client-side, best practices strongly advise registering them on both the server and client. This dual registration is crucial for enabling server-side features such as Dynamic Rendering, Block Supports, Block Hooks, and Style Variations. Without server-side registration, these functionalities will not operate correctly. -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. +For instance, if you want a block [to be styled via `theme.json`](https://developer.wordpress.org/themes/global-settings-and-styles/settings/blocks/), it must be registered on the server. Otherwise, the block won't recognize or apply any styles assigned to it in `theme.json`. + +The following diagram details the registration process for a block. [![Open Block Registration diagram image](https://developer.wordpress.org/files/2023/11/block-registration-e1700493399839.png)](https://developer.wordpress.org/files/2023/11/block-registration-e1700493399839.png "Open Block Registration diagram image") -## Registration of the block with PHP (server-side) +## Registering a 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/). +Block registration on the server usually takes place in the main plugin PHP file with the [`register_block_type()`](https://developer.wordpress.org/reference/functions/register_block_type/) function called on the [`init`](https://developer.wordpress.org/reference/hooks/init/) hook. This function simplifies block type registration by reading metadata stored in a `block.json` file. -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 is designed to register block types and primarily uses two parameters in this context, although it can accommodate more variations: -This function takes two params relevant in this context (`$block_type` accepts more types and variants): +- **`$block_type` (`string`):** This can either be the path to the directory containing the `block.json` file or the complete path to the metadata file if it has a different name. This parameter tells WordPress where to find the block's configuration. -- `$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`. +- **`$args` (`array`):** This is an optional parameter where you can specify additional arguments for the block type. By default, this is an empty array, but it can include various options, one of which is the `$render_callback`. This callback is used to render blocks on the front end and is an alternative to the `render` property 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. +During the development process, the `block.json` file is typically moved from the `src` (source) directory to the `build` directory as part of compiling your code. Therefore, when registering your block, ensure the `$block_type` path points to the `block.json` file within the `build` directory. -`register_block_type` returns the registered block type (`WP_Block_Type`) on success or `false` on failure. +The `register_block_type()` function returns the registered block type (`WP_Block_Type`) on success or `false` on failure. Here is a simple example using the `render_callback`. -**Example:** ```php register_block_type( - __DIR__ . '/notice', + __DIR__ . '/build', array( 'render_callback' => 'render_block_core_notice', ) ); ``` -**Example:** +Here is a more complete example, including the `init` hook. + ```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) +_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)_ -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. +## Registering a block with JavaScript (client-side) -**Example:** +When the block has already been registered on the server, you only need to register the client-side settings in JavaScipt using the [`registerBlockType`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-blocks/#registerblocktype) method from the `@wordpress/blocks` package. You just need to make sure you use the same block name as defined in the block's `block.json` file. Here's an example: ```js +import { registerBlockType } from '@wordpress/blocks'; + 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. +While it's generally advised to register blocks on the server using PHP for the benefits outlined in the ["Benefits using the metadata file"](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#benefits-using-the-metadata-file) section, you can opt to register a block solely on the client-side. The `registerBlockType` method allows you to register a block type using metadata. -The function takes two params: +The function accepts two parameters: -- `$blockNameOrMetadata` (`string`|`Object`) – block type name or the metadata object loaded from the `block.json` -- `$settings` (`Object`) – client-side block settings. +- **`blockNameOrMetadata` (`string`|`Object`):** This can either be the block type's name as a string or an object containing the block's metadata, which is typically loaded from the `block.json` file. +- **`settings` (`Object`):** This is an object containing the block's client-side settings.
block.json
(or any other .json
file) can be imported directly into Javascript files when using a build process like the one available with wp-scripts
+ You can import the contents of the block.json
file (or any other .json
file) directly into your JavaScript files if you're using a build process, such as the one provided by wp-scripts
.