Docs: Fundamentals of Block Development - The block wrapper (#56596)

* Add The Block Wrapper * Refactor block wrapper and add useBlockProps hook * Update block wrapper in the Block Editor * Update block markup and wrappers * Update block markup and wrapper attributes * Update block wrapper attributes and add documentation * Content added * Fix server-side render definition for block wrapper * Refactor block wrapper markup * Update docs/getting-started/fundamentals-block-development/the-block-wrapper.md Co-authored-by: Ryan Welcher <me@ryanwelcher.com> * Update docs/getting-started/fundamentals-block-development/the-block-wrapper.md Co-authored-by: Ryan Welcher <me@ryanwelcher.com> * Update docs/getting-started/fundamentals-block-development/the-block-wrapper.md Co-authored-by: Ryan Welcher <me@ryanwelcher.com> * Update docs/getting-started/fundamentals-block-development/the-block-wrapper.md Co-authored-by: Ryan Welcher <me@ryanwelcher.com> * Update docs/getting-started/fundamentals-block-development/the-block-wrapper.md Co-authored-by: Ryan Welcher <me@ryanwelcher.com> * Fix save function in block wrapper * Refactor block wrapper markup to add attributes * update folder name * Add block-wrapper.md to toc.json * Add link create-block * fixed link Metadata in block.json --------- Co-authored-by: Ryan Welcher <me@ryanwelcher.com>
WordPress · Nov 29, 2023 · a2ebf0b · a2ebf0b
1 parent 6e368d5
commit a2ebf0b
Show file tree

Hide file tree

Showing 6 changed files with 129 additions and 10 deletions.
diff --git a/docs/getting-started/fundamentals/README.md b/docs/getting-started/fundamentals/README.md
@@ -7,4 +7,5 @@ In this section, you will learn:
 1. [**File structure of a block**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/file-structure-of-a-block) - The purpose of each one of the types of files available for a block, the relationships between them, and their role in the output of the block.
 1. [**`block.json`**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-json) - How a block is defined using its `block.json` metadata and some relevant properties of this file.
 1. [**Registration of a block**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block) - How a block is registered in both the server and the client.
+1. [**Block wrapper**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block) - How to set proper attributes to the block's markup wrapper.
 1. [**Javascript in the Block Editor**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/javascript-in-the-block-editor) - How to work with Javascript for the Block Editor.
diff --git a/docs/getting-started/fundamentals/block-json.md b/docs/getting-started/fundamentals/block-json.md
@@ -1,4 +1,4 @@
-# `block.json`
+# block.json
 
 The `block.json` file simplifies the processs of defining and registering a block by using the same block's definition in JSON format to register the block in both the server and the client.
 
@@ -10,7 +10,7 @@ Click <a href="https://github.com/WordPress/block-development-examples/tree/trun
 
 Besides simplifying a block's registration, using a `block.json` has [several benefits](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#benefits-using-the-metadata-file), including improved performance and development.
 
-At [**Metadata in block.json**](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#benefits-using-the-metadata-file) you can find a detailed explanation of all the properties you can set in a `block.json` for a block. With these properties you can define things such as:
+At [**Metadata in block.json**](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/) you can find a detailed explanation of all the properties you can set in a `block.json` for a block. With these properties you can define things such as:
 
 - Basic metadata of the block
 - Files for the block's behavior, style, or output
@@ -60,11 +60,6 @@ _Example: Attributes as defined in block.json_
 	}
 },
 ```
-
-<div class="callout callout-info">
-Check the <a href="https://developer.wordpress.org/redesign-test/block-editor/reference-guides/block-api/block-attributes/"> <code>attributes</code> </a> reference page for full info about the Attributes API. 
-</div>
-
 By default `attributes` are serialized and stored in the block's delimiter but this [can be configured](https://developer.wordpress.org/news/2023/09/understanding-block-attributes/).
 
 _Example: Atributes stored in the Markup representation of the block_

diff --git a/docs/getting-started/fundamentals/block-wrapper.md b/docs/getting-started/fundamentals/block-wrapper.md
@@ -0,0 +1,114 @@
+# The block wrapper
+
+Each block's markup is wrapped by a container HTML tag that needs to have the proper attributes to fully work in the Block Editor and to reflect the proper block's style settings when rendered in the Block Editor and the front end. As developers, we have full control over the block's markup, and WordPress provides the tools to add the attributes that need to exist on the wrapper to our block's markup.
+
+Ensuring proper attributes to the block wrapper is especially important when using custom styling or features like `supports`. 
+
+<div class="callout callout-info">
+The use of <code>supports</code> generates a set of properties that need to be manually added to the wrapping element of the block so they're properly stored as part of the block data
+</div>
+
+A block can have three sets of markup defined, each one of them with a specific target and purpose:
+
+- The one for the **Block Editor**, defined through a `edit` React component passed to `registerBlockType` when registering the block in the client. 
+- The one used to **save the block in the DB**, defined through a `save` function passed to `registerBlockType` when registering the block in the client. 
+    - This markup will be returned to the front end on request if no dynamic render has been defined for the block.
+- The one used to **dynamically render the markup of the block** returned to the front end on request, defined through the `render_callback` on `register_block_type` or the `render` PHP file in `block.json`
+    - If defined, this server-side generated markup will be returned to the front end, ignoring the markup stored in DB.
+
+For the React component `edit` and the `save` function, the block wrapper element should be a native DOM element (like `<div>`) or a React component that forwards any additional props to native DOM elements. Using a <Fragment> or <ServerSideRender> component, for instance, would be invalid.
+
+
+## The Edit component's markup
+
+The `useBlockProps()` hook available on the `@wordpress/block-editor` allows passing the required attributes for the Block Editor to the `edit` block's outer wrapper. 
+
+Among other things, the `useBlockProps()` hook takes care of including in this wrapper:
+- An `id` for the block's markup 
+- Some accesibility and `data-` attributes
+- Classes and inline styles reflecting custom settings, which include by default:
+    - The `wp-block` class 
+    - A class that contains the name of the block with its namespace
+
+For example, for the following piece of code of a block's registration in the client...
+
+```js
+const Edit = () => <p { ...useBlockProps() }>Hello World - Block Editor</p>;
+
+registerBlockType( ..., {
+	edit: Edit
+} );
+```
+_(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))_
+
+...the markup of the block in the Block Editor could look like this:
+```html
+<p 
+    tabindex="0" 
+    id="block-4462939a-b918-44bb-9b7c-35a0db5ab8fe" 
+    role="document" 
+    aria-label="Block: Minimal Gutenberg Block ca6eda" 
+    data-block="4462939a-b918-44bb-9b7c-35a0db5ab8fe" 
+    data-type="block-development-examples/minimal-block-ca6eda" 
+    data-title="Minimal Gutenberg Block ca6eda" 
+    class="
+        block-editor-block-list__block 
+        wp-block 
+        is-selected 
+        wp-block-block-development-examples-minimal-block-ca6eda
+    "
+>Hello World - Block Editor</p>
+```
+
+Any additional classes and attributes for the `Edit` component of the block should be passed as an argument of `useBlockProps` (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/stylesheets-79a4c3/src/edit.js)). When you add `support` for any feature, they get added to the object returned by the `useBlockProps` hook.
+
+
+## The Save component's markup
+
+When saving the markup in the DB, it’s important to add the block props returned by `useBlockProps.save()` to the wrapper element of your block. `useBlockProps.save()` ensures that the block class name is rendered properly in addition to any HTML attribute injected by the block supports API.
+
+For example, for the following piece of code of a block's registration in the client that defines the markup desired for the DB (and returned to the front end by default)...
+
+```js
+const Edit = () => <p { ...useBlockProps() }>Hello World - Block Editor</p>;
+const save = () => <p { ...useBlockProps.save() }>Hello World - Frontend</p>;
+
+registerBlockType( ..., {
+	edit: Edit,
+	save,
+} );
+```
+
+_(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))_
+
+
+...the markup of the block in the front end could look like this:
+```html
+<p class="wp-block-block-development-examples-minimal-block-ca6eda">Hello World – Frontend</p>
+```
+
+Any additional classes and attributes for the `save` function of the block should be passed as an argument of `useBlockProps.save()` (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/stylesheets-79a4c3/src/save.js)). 
+
+When you add `support` for any feature, the proper classes get added to the object returned by the `useBlockProps.save()` hook.
+
+```html
+<p class="
+    wp-block-block-development-examples-block-supports-6aa4dd 
+    has-accent-4-color 
+    has-contrast-background-color 
+    has-text-color 
+    has-background
+">Hello World</p>
+```
+
+_(check the [example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/block-supports-6aa4dd) that generated the HTML above in the front end)_
+
+## The server-side render markup
+
+Any markup in the server-side render definition for the block can use the [`get_block_wrapper_attributes()`](https://developer.wordpress.org/reference/functions/get_block_wrapper_attributes/) to generate the string of attributes required to reflect the block settings. function (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/render.php#L31)). 
+
+```php
+<p <?php echo get_block_wrapper_attributes(); ?>>
+	<?php esc_html_e( 'Block with Dynamic Rendering – hello!!!', '01-block-dynamic' ); ?>
+</p>
+```
diff --git a/docs/getting-started/fundamentals/file-structure-of-a-block.md b/docs/getting-started/fundamentals/file-structure-of-a-block.md
@@ -1,8 +1,8 @@
 # File structure of a block
 
-It is recommended to **register blocks within plugins** to ensure they stay available when a theme gets switched. With the `create-block` tool you can quickly scaffold the structure of the files required to create a plugin that registers a block. 
+It is recommended to **register blocks within plugins** to ensure they stay available when a theme gets switched. With the [`create-block` tool](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/) you can quickly scaffold the structure of the files required to create a plugin that registers a block. 
 
-The files generated by this tool are a good reference of the files that can be involved in the definition and registration of a block.
+The files generated by `create-block` are a good reference of the files that can be involved in the definition and registration of a block.
 
 [![Open File Structure of a Block Diagram in excalidraw](https://developer.wordpress.org/files/2023/11/file-structure-block.png)](https://excalidraw.com/#json=YYpeR-kY1ZMhFKVZxGhMi,mVZewfwNAh_oL-7bj4gmdw "Open File Structure of a Block Diagram in excalidraw")
 

diff --git a/docs/manifest.json b/docs/manifest.json
@@ -108,7 +108,7 @@
 		"parent": "fundamentals"
 	},
 	{
-		"title": "`block.json`",
+		"title": "block.json",
 		"slug": "block-json",
 		"markdown_source": "../docs/getting-started/fundamentals/block-json.md",
 		"parent": "fundamentals"
@@ -119,6 +119,12 @@
 		"markdown_source": "../docs/getting-started/fundamentals/registration-of-a-block.md",
 		"parent": "fundamentals"
 	},
+	{
+		"title": "The block wrapper",
+		"slug": "block-wrapper",
+		"markdown_source": "../docs/getting-started/fundamentals/block-wrapper.md",
+		"parent": "fundamentals"
+	},
 	{
 		"title": "Working with Javascript for the Block Editor",
 		"slug": "javascript-in-the-block-editor",

diff --git a/docs/toc.json b/docs/toc.json
@@ -57,6 +57,9 @@
 					{
 						"docs/getting-started/fundamentals/registration-of-a-block.md": []
 					},
+					{
+						"docs/getting-started/fundamentals/block-wrapper.md": []
+					},
 					{
 						"docs/getting-started/fundamentals/javascript-in-the-block-editor.md": []
 					}