From 3037f59ab9d7303e577241c46dd2537b453e40c0 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Thu, 23 Nov 2023 21:53:14 +0100 Subject: [PATCH 01/20] Add The Block Wrapper --- .../fundamentals-block-development/the-block-wrapper.md | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 docs/getting-started/fundamentals-block-development/the-block-wrapper.md diff --git a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md new file mode 100644 index 00000000000000..f4c09fb99f1f42 --- /dev/null +++ b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md @@ -0,0 +1,2 @@ +# The Block Wrapper + From 74cb3ef41411ef068b2a8400e5c017236b7d6877 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Fri, 24 Nov 2023 11:58:04 +0100 Subject: [PATCH 02/20] Refactor block wrapper and add useBlockProps hook --- .../the-block-wrapper.md | 38 ++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md index f4c09fb99f1f42..d3daba282295d3 100644 --- a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md +++ b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md @@ -1,2 +1,38 @@ -# The Block Wrapper +# The Block wrapper +The Block Editor is a React Single Page Application (SPA) and every block in the editor is displayed through a React component. +changes in blocks --- update store --- update blocks + +To render the block element wrapper for the block’s edit implementation, the block author must use the `useBlockProps()` hook. + +The generated class names and styles are no longer added automatically to the saved markup for static blocks when save is processed. To include them, the block author must explicitly use `useBlockProps.save()` and add to their block wrapper. + + +The block wrapper element needs to include `props` from `useBlockProps` to include its classes and atributes properly: +- any custom attributes (like extra classes) should be passed as an argument of `useBlockProps` +- When you add `support` for any feature, they get added to the object returned by the `useBlockProps` hook. + +Like the edit function, when rendering static blocks, it’s important to add the block props returned by `useBlockProps.save()` to the wrapper element of your block. This ensures that the block class name is rendered properly in addition to any HTML attribute injected by the block supports API. + +The use of `supports` 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: +- in the `Edit` component via the `useBlockProps()` hook (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/edit.js#L106)) +- in the `Save` component via the `useBlockProps.save()` hook (see [example](https://github.com/WordPress/block-development-examples/blob/e804d8416775de94fccae27be6f26ae0ae75b3d9/plugins/copyright-date-block-09aac3/src/save.js#L40)) +- in any server-side render definition for the block via the `get_block_wrapper_attributes()` function (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/render.php#L31)). + + +…but in order for the Gutenberg editor to know how to manipulate the block, add any extra classNames that are needed for the block… the block wrapper element should apply props retrieved from the useBlockProps react hook call. The block wrapper element should be a native DOM element, like
and , or a React component that forwards any additional props to native DOM elements. Using a or component, for instance, would be invalid. + +If the element wrapper needs any extra custom HTML attributes, these need to be passed as an argument to the useBlockProps hook. + + +--- show classes generated + +``` +

Hello World!

+``` + +- My rendered h1 element in the Block Editor +- My rendered h1 element in the frontend + +Related resources: +- https://franky-arkon-digital.medium.com/gutenberg-tips-generate-your-blocks-class-name-using-useblockprops-aa77a98f4fd From 49c08aba632e55983a65b377dde35d03b79a7a9e Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Sun, 26 Nov 2023 11:03:36 +0100 Subject: [PATCH 03/20] Update block wrapper in the Block Editor --- .../the-block-wrapper.md | 26 +++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md index d3daba282295d3..0f2e47608b4e63 100644 --- a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md +++ b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md @@ -1,6 +1,8 @@ # The Block wrapper -The Block Editor is a React Single Page Application (SPA) and every block in the editor is displayed through a React component. +The Block Editor is a React Single Page Application (SPA) and every block in the editor is displayed through a React component. Besides this "edit" interface, every block decides how it's going to be rendered for the fromnted. s + + changes in blocks --- update store --- update blocks To render the block element wrapper for the block’s edit implementation, the block author must use the `useBlockProps()` hook. @@ -20,7 +22,7 @@ The use of `supports` generates a set of properties that need to be manually add - in any server-side render definition for the block via the `get_block_wrapper_attributes()` function (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/render.php#L31)). -…but in order for the Gutenberg editor to know how to manipulate the block, add any extra classNames that are needed for the block… the block wrapper element should apply props retrieved from the useBlockProps react hook call. The block wrapper element should be a native DOM element, like
and
, or a React component that forwards any additional props to native DOM elements. Using a or component, for instance, would be invalid. +…but in order for the Gutenberg editor to know how to manipulate the block, add any extra classNames that are needed for the block… the block wrapper element should apply props retrieved from the `useBlockProps` react hook call. The block wrapper element should be a native DOM element, like
and
, or a React component that forwards any additional props to native DOM elements. Using a or component, for instance, would be invalid. If the element wrapper needs any extra custom HTML attributes, these need to be passed as an argument to the useBlockProps hook. @@ -36,3 +38,23 @@ If the element wrapper needs any extra custom HTML attributes, these need to be Related resources: - https://franky-arkon-digital.medium.com/gutenberg-tips-generate-your-blocks-class-name-using-useblockprops-aa77a98f4fd + + +```html +

+© 2020–2023 +

+``` + +```html +

© 2020–2023

+``` From 1a8eeb77e5d7ba2a6a0069ad148706d03ee89e97 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Mon, 27 Nov 2023 12:05:06 +0000 Subject: [PATCH 04/20] Update block markup and wrappers --- .../the-block-wrapper.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md index 0f2e47608b4e63..793c9a6fb205c2 100644 --- a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md +++ b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md @@ -1,6 +1,21 @@ # The Block wrapper -The Block Editor is a React Single Page Application (SPA) and every block in the editor is displayed through a React component. Besides this "edit" interface, every block decides how it's going to be rendered for the fromnted. s +Each block's markup has its own markup wrapper that needs to be properly identified to fully work in the Block Editor and include any custom style settings when the block is rendered in the front end. + +There are three main markups involved in the lifecyle of a block: + +- Every block in the Block Editor (React SPA) is displayed through a React component (`edit` property passed to `registerBlockType`). +- Another React component can be defined for the Block to set the markup saved to the DB (`save` property passed to `registerBlockType`). ). +- The markup stored in the DB will be returned to the front end on request unless a specific server-side render way (`render_callback` on `register_block_type` or `render` in `block.json`) has been defined to return the markup of the block to the fron end. + +--- idea edit markup is defined separatedly than markup returned to the frontend - but the recommendation is that the edit markup should reflect the front end one ----- + + +When defined, these markups need to include the proper block's attributes in their wrappers. + +## The Edit component + +The markup of the `Edit` React component ` function is wrapped in a few other elements. The outer wrapper of each block has the wp-block class and a data-block attribute that contains the name of the block with its namespace – core/group for the group block, for example. changes in blocks --- update store --- update blocks From 48b510e897676028220f1c762e74bea85b2c3653 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Mon, 27 Nov 2023 14:43:59 +0000 Subject: [PATCH 05/20] Update block markup and wrapper attributes --- .../the-block-wrapper.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md index 793c9a6fb205c2..2967f0da72115e 100644 --- a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md +++ b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md @@ -1,17 +1,16 @@ # The Block wrapper -Each block's markup has its own markup wrapper that needs to be properly identified to fully work in the Block Editor and include any custom style settings when the block is rendered in the front end. +Each block's markup is wrapped by a container HTML tag that needs the proper attributes to fully work in the Block Editor and reflect the proper block's style settings when rendered in the Block Editor and the front end. -There are three main markups involved in the lifecyle of a block: +Three markups can be defined for a block: -- Every block in the Block Editor (React SPA) is displayed through a React component (`edit` property passed to `registerBlockType`). -- Another React component can be defined for the Block to set the markup saved to the DB (`save` property passed to `registerBlockType`). ). -- The markup stored in the DB will be returned to the front end on request unless a specific server-side render way (`render_callback` on `register_block_type` or `render` in `block.json`) has been defined to return the markup of the block to the fron end. +- 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` React component 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 markup definition will take priority over the markup stored in DB ------ ---- idea edit markup is defined separatedly than markup returned to the frontend - but the recommendation is that the edit markup should reflect the front end one ----- - - -When defined, these markups need to include the proper block's attributes in their wrappers. +These markups are defined separately, but the recommendation is that they match each other so the block in the editor looks like as close as possible as how it will be rendered on the front end. ## The Edit component From 42d9fc58e804489c9c6a24b8b8a4701e0bb185ac Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Tue, 28 Nov 2023 07:13:16 +0000 Subject: [PATCH 06/20] Update block wrapper attributes and add documentation --- .../the-block-wrapper.md | 34 ++++++++++++++----- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md index 2967f0da72115e..708face01fee20 100644 --- a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md +++ b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md @@ -1,6 +1,12 @@ -# The Block wrapper +# The Block wrapper's attributes + +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 reflect the proper block's style settings when rendered in the Block Editor and the front end. + +Ensuring proper attributes to the block wrapper is especially important when using custom styling or features like `supports`. + +
+The use of `supports` 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 -Each block's markup is wrapped by a container HTML tag that needs the proper attributes to fully work in the Block Editor and reflect the proper block's style settings when rendered in the Block Editor and the front end. Three markups can be defined for a block: @@ -8,9 +14,10 @@ Three markups can be defined for a block: - The one used to save the block in the DB, defined through a `save` React component 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 markup definition will take priority over the markup stored in DB ------ + - If defined, this server-side generated markup will be returned to the front end, ignoring the markup stored in DB. + +These markups are defined separately, but the recommendation is to match each other so the block in the editor looks as close as possible to how it looks on the front end. -These markups are defined separately, but the recommendation is that they match each other so the block in the editor looks like as close as possible as how it will be rendered on the front end. ## The Edit component @@ -21,19 +28,28 @@ changes in blocks --- update store --- update blocks To render the block element wrapper for the block’s edit implementation, the block author must use the `useBlockProps()` hook. -The generated class names and styles are no longer added automatically to the saved markup for static blocks when save is processed. To include them, the block author must explicitly use `useBlockProps.save()` and add to their block wrapper. - - The block wrapper element needs to include `props` from `useBlockProps` to include its classes and atributes properly: - any custom attributes (like extra classes) should be passed as an argument of `useBlockProps` - When you add `support` for any feature, they get added to the object returned by the `useBlockProps` hook. -Like the edit function, when rendering static blocks, it’s important to add the block props returned by `useBlockProps.save()` to the wrapper element of your block. This ensures that the block class name is rendered properly in addition to any HTML attribute injected by the block supports API. + + +## The Save component + +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. This ensures that the block class name is rendered properly in addition to any HTML attribute injected by the block supports API. + +## The Render + +- in any server-side render definition for the block via the `get_block_wrapper_attributes()` function (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/render.php#L31)). + + +-------- + + The use of `supports` 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: - in the `Edit` component via the `useBlockProps()` hook (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/edit.js#L106)) - in the `Save` component via the `useBlockProps.save()` hook (see [example](https://github.com/WordPress/block-development-examples/blob/e804d8416775de94fccae27be6f26ae0ae75b3d9/plugins/copyright-date-block-09aac3/src/save.js#L40)) -- in any server-side render definition for the block via the `get_block_wrapper_attributes()` function (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/render.php#L31)). …but in order for the Gutenberg editor to know how to manipulate the block, add any extra classNames that are needed for the block… the block wrapper element should apply props retrieved from the `useBlockProps` react hook call. The block wrapper element should be a native DOM element, like
and
, or a React component that forwards any additional props to native DOM elements. Using a or component, for instance, would be invalid. From f408e654ede5f20940fb21d8fd370dc83b09fe17 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Tue, 28 Nov 2023 12:34:53 +0000 Subject: [PATCH 07/20] Content added --- .../the-block-wrapper.md | 111 ++++++++++++++---- 1 file changed, 89 insertions(+), 22 deletions(-) diff --git a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md index 708face01fee20..5a2fd872e7106c 100644 --- a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md +++ b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md @@ -1,46 +1,113 @@ -# The Block wrapper's attributes +# The Block markup's 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 reflect the proper block's style settings when rendered in the Block Editor and the front end. +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. Ensuring proper attributes to the block wrapper is especially important when using custom styling or features like `supports`. -
-The use of `supports` 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 +
+The use of supports 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 +
+**Three markups can be defined for a block**: -Three markups can be defined for a block: - -- 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` React component passed to `registerBlockType` when registering the block in the client. +- 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` React component 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` +- 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. +
These markups are defined separately, but the recommendation is to match each other so the block in the editor looks as close as possible to how it looks on the front end. +
+ +## 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: -## The Edit component +```js +const Edit = () =>

Hello World - Block Editor

; -The markup of the `Edit` React component ` function is wrapped in a few other elements. The outer wrapper of each block has the wp-block class and a data-block attribute that contains the name of the block with its namespace – core/group for the group block, for example. +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 +

Hello World - Block Editor

+``` +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. -changes in blocks --- update store --- update blocks -To render the block element wrapper for the block’s edit implementation, the block author must use the `useBlockProps()` hook. +## The Save component's markup -The block wrapper element needs to include `props` from `useBlockProps` to include its classes and atributes properly: -- any custom attributes (like extra classes) should be passed as an argument of `useBlockProps` -- When you add `support` for any feature, they get added to the object returned by the `useBlockProps` hook. +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, defining the markup desired for the DB (and returned to the front end by default): +```js +const Save = () =>

Hello World - Frontend

; + +registerBlockType( ..., { + edit: Edit, + save: 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 +

Hello World – Frontend

+``` + +Any additional classes and attributes for the `Save` component 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, they get added to the object returned by the `useBlockProps.save()` hook. + +```html +

Hello World

+``` -## The Save component +_(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)_ -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. This ensures that the block class name is rendered properly in addition to any HTML attribute injected by the block supports API. +## The server-side render markup -## The Render +Any server-side render definition for the block via the `get_block_wrapper_attributes()` function (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/render.php#L31)). -- in any server-side render definition for the block via the `get_block_wrapper_attributes()` function (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/render.php#L31)). +in the same way that `useBlockProps.save()` adds to the markup stored in the DB (and that potentially can also be returned to the front end ) -------- @@ -48,8 +115,8 @@ When saving the markup in the DB, it’s important to add the block props return The use of `supports` 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: -- in the `Edit` component via the `useBlockProps()` hook (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/edit.js#L106)) -- in the `Save` component via the `useBlockProps.save()` hook (see [example](https://github.com/WordPress/block-development-examples/blob/e804d8416775de94fccae27be6f26ae0ae75b3d9/plugins/copyright-date-block-09aac3/src/save.js#L40)) +- in the `Edit` component via the `useBlockProps()` hook +- in the `Save` component via the `useBlockProps.save()` hook …but in order for the Gutenberg editor to know how to manipulate the block, add any extra classNames that are needed for the block… the block wrapper element should apply props retrieved from the `useBlockProps` react hook call. The block wrapper element should be a native DOM element, like
and
, or a React component that forwards any additional props to native DOM elements. Using a or component, for instance, would be invalid. From 780727173233543e371bebfd240df0118e708f09 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Tue, 28 Nov 2023 12:59:59 +0000 Subject: [PATCH 08/20] Fix server-side render definition for block wrapper --- .../the-block-wrapper.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md index 5a2fd872e7106c..82f5c3bf7a0ddd 100644 --- a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md +++ b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md @@ -105,7 +105,15 @@ _(check the [example](https://github.com/WordPress/block-development-examples/tr ## The server-side render markup -Any server-side render definition for the block via the `get_block_wrapper_attributes()` function (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/render.php#L31)). +Any server-side render definition for the block can use the the `get_block_wrapper_attributes()` function (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/render.php#L31)). + +```php +

> + +

+``` + +The `render.php` file (or any other file defined in the `render` property of `block.json`) defines the server side process that returns the markup for the block when there is a request from the frontend. If this file is defined, it will take precedence over any other ways to render the block's markup for the frontend. in the same way that `useBlockProps.save()` adds to the markup stored in the DB (and that potentially can also be returned to the front end ) From 01c955b1ae98a53be1028d773dc4ec8caafe646e Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Tue, 28 Nov 2023 14:56:57 +0000 Subject: [PATCH 09/20] Refactor block wrapper markup --- .../the-block-wrapper.md | 76 +++---------------- 1 file changed, 12 insertions(+), 64 deletions(-) diff --git a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md index 82f5c3bf7a0ddd..eeef33045991ce 100644 --- a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md +++ b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md @@ -1,6 +1,6 @@ -# The Block markup's wrapper +# 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. +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, when creating a custom block, we need to manually add these attributes to the markup using some of the tools provided by WordPress. Ensuring proper attributes to the block wrapper is especially important when using custom styling or features like `supports`. @@ -8,7 +8,7 @@ Ensuring proper attributes to the block wrapper is especially important when usi The use of supports 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 -**Three markups can be defined for a block**: +A block can have three markups 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` React component passed to `registerBlockType` when registering the block in the client. @@ -16,9 +16,8 @@ The use of supports generates a set of properties that need to be m - 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. -
-These markups are defined separately, but the recommendation is to match each other so the block in the editor looks as close as possible to how it looks on the front end. -
+For the React components `edit` and `save`, the block wrapper element should be a native DOM element (like `
`) or a React component that forwards any additional props to native DOM elements. Using a or component, for instance, would be invalid. + ## The Edit component's markup @@ -31,7 +30,7 @@ Among other things, the `useBlockProps()` hook takes care of including in this w - 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: +For example, for the following piece of code of a block's registration in the client... ```js const Edit = () =>

Hello World - Block Editor

; @@ -42,7 +41,7 @@ registerBlockType( ..., { ``` _(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: +...the markup of the block in the Block Editor could look like this: ```html

Hello World - Frontend

; @@ -82,14 +81,14 @@ registerBlockType( ..., { _(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: +...the markup of the block in the front end could look like this: ```html

Hello World – Frontend

``` Any additional classes and attributes for the `Save` component 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, they get added to the object returned by the `useBlockProps.save()` hook. +When you add `support` for any feature, the proper classes get added to the object returned by the `useBlockProps.save()` hook. ```html

-© 2020–2023 -

-``` - -```html -

© 2020–2023

-``` +``` \ No newline at end of file From 5b58ceaec312bb7648f1565d1649ef0d8958ddc5 Mon Sep 17 00:00:00 2001 From: JuanMa Date: Tue, 28 Nov 2023 17:15:53 +0100 Subject: [PATCH 10/20] Update docs/getting-started/fundamentals-block-development/the-block-wrapper.md Co-authored-by: Ryan Welcher --- .../fundamentals-block-development/the-block-wrapper.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md index eeef33045991ce..5dc76ae6a92c3a 100644 --- a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md +++ b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md @@ -8,7 +8,7 @@ Ensuring proper attributes to the block wrapper is especially important when usi The use of supports 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
-A block can have three markups defined, each one of them with a specific target and purpose: +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` React component passed to `registerBlockType` when registering the block in the client. From 071016864f76eb709965b0556dde3e5749cced8d Mon Sep 17 00:00:00 2001 From: JuanMa Date: Tue, 28 Nov 2023 17:16:04 +0100 Subject: [PATCH 11/20] Update docs/getting-started/fundamentals-block-development/the-block-wrapper.md Co-authored-by: Ryan Welcher --- .../fundamentals-block-development/the-block-wrapper.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md index 5dc76ae6a92c3a..fa0efde8ceb070 100644 --- a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md +++ b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md @@ -70,7 +70,7 @@ When saving the markup in the DB, it’s important to add the block props return 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 Save = () =>

Hello World - Frontend

; +const save = () =>

Hello World - Frontend

; registerBlockType( ..., { edit: Edit, From 4d0ff8dfc773e8074826282a4c248a275ace0a91 Mon Sep 17 00:00:00 2001 From: JuanMa Date: Tue, 28 Nov 2023 17:16:14 +0100 Subject: [PATCH 12/20] Update docs/getting-started/fundamentals-block-development/the-block-wrapper.md Co-authored-by: Ryan Welcher --- .../fundamentals-block-development/the-block-wrapper.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md index fa0efde8ceb070..6e0e3f64884212 100644 --- a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md +++ b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md @@ -16,7 +16,7 @@ A block can have three sets of markup defined, each one of them with a specific - 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 components `edit` and `save`, the block wrapper element should be a native DOM element (like `
`) or a React component that forwards any additional props to native DOM elements. Using a or component, for instance, would be invalid. +For the React component `edit` and the `save` function, the block wrapper element should be a native DOM element (like `
`) or a React component that forwards any additional props to native DOM elements. Using a or component, for instance, would be invalid. ## The Edit component's markup From e03b686cd567687d3b88207aa02d0ed15d01ef08 Mon Sep 17 00:00:00 2001 From: JuanMa Date: Tue, 28 Nov 2023 17:16:24 +0100 Subject: [PATCH 13/20] Update docs/getting-started/fundamentals-block-development/the-block-wrapper.md Co-authored-by: Ryan Welcher --- .../fundamentals-block-development/the-block-wrapper.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md index 6e0e3f64884212..882144dbc306b6 100644 --- a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md +++ b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md @@ -86,7 +86,7 @@ _(see the [code above](https://github.com/WordPress/block-development-examples/b

Hello World – Frontend

``` -Any additional classes and attributes for the `Save` component 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)). +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. From 3c60893ed8721dc45735eb8144b7805c859f6cd3 Mon Sep 17 00:00:00 2001 From: JuanMa Date: Tue, 28 Nov 2023 17:16:37 +0100 Subject: [PATCH 14/20] Update docs/getting-started/fundamentals-block-development/the-block-wrapper.md Co-authored-by: Ryan Welcher --- .../fundamentals-block-development/the-block-wrapper.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md index 882144dbc306b6..19a45b1085e002 100644 --- a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md +++ b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md @@ -74,7 +74,7 @@ const save = () =>

Hello World - Frontend

; registerBlockType( ..., { edit: Edit, - save: Save, + save, } ); ``` From aa154a2fa696d40caedaf5142868540f18221aca Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Tue, 28 Nov 2023 16:20:15 +0000 Subject: [PATCH 15/20] Fix save function in block wrapper --- .../fundamentals-block-development/the-block-wrapper.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md index 19a45b1085e002..445a9961886ecd 100644 --- a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md +++ b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md @@ -11,7 +11,7 @@ The use of supports generates a set of properties that need to be m 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` 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. @@ -70,6 +70,7 @@ When saving the markup in the DB, it’s important to add the block props return 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 = () =>

Hello World - Block Editor

; const save = () =>

Hello World - Frontend

; registerBlockType( ..., { From 7a4ead27adb9f996ce6c4be73ac33e3e294891c2 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Tue, 28 Nov 2023 16:28:52 +0000 Subject: [PATCH 16/20] Refactor block wrapper markup to add attributes --- .../fundamentals-block-development/the-block-wrapper.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md index 445a9961886ecd..b391d758b7e546 100644 --- a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md +++ b/docs/getting-started/fundamentals-block-development/the-block-wrapper.md @@ -1,6 +1,6 @@ # 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, when creating a custom block, we need to manually add these attributes to the markup using some of the tools provided by WordPress. +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`. From fe8f253606af09480deeed73d58a918d889ce3fd Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Wed, 29 Nov 2023 09:02:10 +0000 Subject: [PATCH 17/20] update folder name --- .../file-structure-of-a-block.md | 0 .../javascript-in-the-block-editor.md | 0 .../registration-of-a-block.md | 0 .../the-block-wrapper.md | 0 4 files changed, 0 insertions(+), 0 deletions(-) rename docs/getting-started/{fundamentals-block-development => fundamentals}/file-structure-of-a-block.md (100%) rename docs/getting-started/{fundamentals-block-development => fundamentals}/javascript-in-the-block-editor.md (100%) rename docs/getting-started/{fundamentals-block-development => fundamentals}/registration-of-a-block.md (100%) rename docs/getting-started/{fundamentals-block-development => fundamentals}/the-block-wrapper.md (100%) diff --git a/docs/getting-started/fundamentals-block-development/file-structure-of-a-block.md b/docs/getting-started/fundamentals/file-structure-of-a-block.md similarity index 100% rename from docs/getting-started/fundamentals-block-development/file-structure-of-a-block.md rename to docs/getting-started/fundamentals/file-structure-of-a-block.md diff --git a/docs/getting-started/fundamentals-block-development/javascript-in-the-block-editor.md b/docs/getting-started/fundamentals/javascript-in-the-block-editor.md similarity index 100% rename from docs/getting-started/fundamentals-block-development/javascript-in-the-block-editor.md rename to docs/getting-started/fundamentals/javascript-in-the-block-editor.md diff --git a/docs/getting-started/fundamentals-block-development/registration-of-a-block.md b/docs/getting-started/fundamentals/registration-of-a-block.md similarity index 100% rename from docs/getting-started/fundamentals-block-development/registration-of-a-block.md rename to docs/getting-started/fundamentals/registration-of-a-block.md diff --git a/docs/getting-started/fundamentals-block-development/the-block-wrapper.md b/docs/getting-started/fundamentals/the-block-wrapper.md similarity index 100% rename from docs/getting-started/fundamentals-block-development/the-block-wrapper.md rename to docs/getting-started/fundamentals/the-block-wrapper.md From 8b9532d0bb4a2d0b5abb291b4093fe02a33c00a8 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Wed, 29 Nov 2023 09:08:33 +0000 Subject: [PATCH 18/20] Add block-wrapper.md to toc.json --- docs/getting-started/fundamentals/README.md | 1 + docs/getting-started/fundamentals/block-json.md | 7 +------ .../{the-block-wrapper.md => block-wrapper.md} | 0 docs/manifest.json | 8 +++++++- docs/toc.json | 3 +++ 5 files changed, 12 insertions(+), 7 deletions(-) rename docs/getting-started/fundamentals/{the-block-wrapper.md => block-wrapper.md} (100%) diff --git a/docs/getting-started/fundamentals/README.md b/docs/getting-started/fundamentals/README.md index 6917723f9a33c1..6367603351c82b 100644 --- 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. \ No newline at end of file diff --git a/docs/getting-started/fundamentals/block-json.md b/docs/getting-started/fundamentals/block-json.md index 4589787036e25a..89a716ac8ebeaf 100644 --- 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. @@ -60,11 +60,6 @@ _Example: Attributes as defined in block.json_ } }, ``` - -
-Check the attributes reference page for full info about the Attributes API. -
- 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/the-block-wrapper.md b/docs/getting-started/fundamentals/block-wrapper.md similarity index 100% rename from docs/getting-started/fundamentals/the-block-wrapper.md rename to docs/getting-started/fundamentals/block-wrapper.md diff --git a/docs/manifest.json b/docs/manifest.json index 6606d57dd6b65c..3ab4cefb2b533c 100644 --- 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 index ab69092dda42b0..91017ce69643c3 100644 --- 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": [] } From a4d191998e80974871edb9e88878dec54057c449 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Wed, 29 Nov 2023 09:14:00 +0000 Subject: [PATCH 19/20] Add link create-block --- .../getting-started/fundamentals/file-structure-of-a-block.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/fundamentals/file-structure-of-a-block.md b/docs/getting-started/fundamentals/file-structure-of-a-block.md index e38470ee306709..130483ae5af70f 100644 --- 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") From 6c0925f29a0474c947ff17fd72b3820c5bf7618a Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Wed, 29 Nov 2023 09:16:33 +0000 Subject: [PATCH 20/20] fixed link Metadata in block.json --- docs/getting-started/fundamentals/block-json.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals/block-json.md b/docs/getting-started/fundamentals/block-json.md index 89a716ac8ebeaf..3d65a8f016914e 100644 --- a/docs/getting-started/fundamentals/block-json.md +++ b/docs/getting-started/fundamentals/block-json.md @@ -10,7 +10,7 @@ Click