From 155b40bf5b4f92fc2b77f36f3f7e430fe7e03536 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Tue, 19 Dec 2023 20:07:25 +0100 Subject: [PATCH 01/29] Static or Dynamic rendering of a block first draft --- .../fundamentals/static-dynamic-rendering.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 docs/getting-started/fundamentals/static-dynamic-rendering.md diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md new file mode 100644 index 0000000000000..de7580c77fe39 --- /dev/null +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -0,0 +1,27 @@ +# Static or Dynamic rendering of a block + + + +A block can define dynamic rendering can be defined in two ways: + - The `register_block_type()` function includes a `render_callback` argument. + - A `render` property is added to `block.json`, whose value points to a separate PHP file (usually named `render.php`). + +Blocks can have static or dynamic rendering: +- If no dynamic rendering has been been defined the rendering + +## Blocks with Static Rendering + +Blocks with static rendering **generate the HMTL for the frontend at "update-time" (when it's saved)**: +- Blocks with static render use their markup representation in the DB to return the markup used in the frontend for the block +- The `save()` function writes the block’s markup inside the block indicators (HTML comments). +- Only the markup inside the block indicators is returned as markup to be rendered for the block in the frontend. +- For blocks with static render, the markup returned to the frontend is defined/set when the page is saved. + +## Blocks with Dynamic Rendering + +Blocks with dynamic rendering **generate the HMTL for the frontend at "request-time" (when it's requested)** +- These blocks usually need to display info that is not known at the time the page is saved +- Dynamic rendering for a block can be defined: + - The `register_block_type()` function includes a `render_callback` argument. + - A `render` property is added to `block.json`, whose value points to a separate PHP file (usually named `render.php`). +- Dynamic render methods receive attribute, inner content information and additional required dynamic site information. \ No newline at end of file From a66d0f4f1096c2cd8df1151a6fa8b6e7c63e5356 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Wed, 20 Dec 2023 18:31:31 +0100 Subject: [PATCH 02/29] Add explanation of static and dynamic rendering of blocks --- .../fundamentals/static-dynamic-rendering.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index de7580c77fe39..386d5e5774efa 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -1,10 +1,16 @@ # Static or Dynamic rendering of a block +A block can have +- **Blocks with static rendering** - Blocks with no dynamic rendering method defined (or available) for the block. In this case, the output for the front end will be taken from the markup representation of the block in the database. + - A block will also have static rendering when there was originally a dynamic rendering method defined for the block, but that method is no longer available due to the uninstallation of the plugin that registered the block. If no dynamic rendering method is found, any markup representation of the block in the database will be returned to the front end. +- **Blocks with dynamic rendering** - Blocks with dynamic rendering method defined (or available) for the block. In this case, the output for the front end will be processed in the server when there's a request from the client. + - This dynamic rendering process may take into account the markup representation of the block in the database, the attributes of the block, and any other data that is available from the server. +By default a block will use its representation in the DB as output to be delivered to the front end, unless it has dynamic rendering. If the block has some form of dynamic rendering defined and available, that logic will determine the output of the block for the front end. -A block can define dynamic rendering can be defined in two ways: - - The `register_block_type()` function includes a `render_callback` argument. - - A `render` property is added to `block.json`, whose value points to a separate PHP file (usually named `render.php`). +A block can define dynamic rendering in two ways: + 1. Via the `render_callback` argument that can be passed to the `register_block_type()` function. + 2. Via a separate PHP file (usually named `render.php`) which path can be defined at the `render` propertyof the `block.json`. Blocks can have static or dynamic rendering: - If no dynamic rendering has been been defined the rendering From 28da0783a466ca8f8f88394b52c5f34502baf091 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Thu, 21 Dec 2023 17:17:56 +0100 Subject: [PATCH 03/29] Updated context with first version --- .../markup-representation-block.md | 2 +- .../fundamentals/static-dynamic-rendering.md | 124 ++++++++++++++---- 2 files changed, 101 insertions(+), 25 deletions(-) diff --git a/docs/getting-started/fundamentals/markup-representation-block.md b/docs/getting-started/fundamentals/markup-representation-block.md index 20289f8f228ce..908881c4090c6 100644 --- a/docs/getting-started/fundamentals/markup-representation-block.md +++ b/docs/getting-started/fundamentals/markup-representation-block.md @@ -23,7 +23,7 @@ The [markup representation of a block is parsed for the Block Editor](https://de Whenever a block is saved, the `save` function, defined when the [block is registered in the client](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#registration-of-the-block-with-javascript-client-side), is called to return the markup that will be saved into the database within the block delimiter's comment. If `save` is `null` (common case for blocks with dynamic rendering), only a single line block delimiter's comment is stored, along with any attributes The Post Editor checks that the markup created by the `save` function is identical to the block's markup saved to the database: -- If there are any differences, the Post Editor trigger a **block validation error**. +- If there are any differences, the Post Editor triggers a [**block validation error**](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#validation). - Block validation errors usually happen when a block’s `save` function is updated to change the markup produced by the block. - A block developer can mitigate these issues by adding a [**block deprecation**](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-deprecation/) to register the change in the block. diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index 386d5e5774efa..ce02e310938fa 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -1,33 +1,109 @@ # Static or Dynamic rendering of a block -A block can have -- **Blocks with static rendering** - Blocks with no dynamic rendering method defined (or available) for the block. In this case, the output for the front end will be taken from the markup representation of the block in the database. - - A block will also have static rendering when there was originally a dynamic rendering method defined for the block, but that method is no longer available due to the uninstallation of the plugin that registered the block. If no dynamic rendering method is found, any markup representation of the block in the database will be returned to the front end. -- **Blocks with dynamic rendering** - Blocks with dynamic rendering method defined (or available) for the block. In this case, the output for the front end will be processed in the server when there's a request from the client. - - This dynamic rendering process may take into account the markup representation of the block in the database, the attributes of the block, and any other data that is available from the server. +The blocks's markup returned for the front end can be generated dynamically via a process in the server (dynamic blocks) or statically when the block is saved in the Block Editor (static blocks). -By default a block will use its representation in the DB as output to be delivered to the front end, unless it has dynamic rendering. If the block has some form of dynamic rendering defined and available, that logic will determine the output of the block for the front end. +- Blocks with static rendering _generate the HMTL for the frontend at "update-time" (when it's saved)_. +- Blocks with dynamic rendering _generate the HMTL for the frontend at "request-time" (when it's requested)_ -A block can define dynamic rendering in two ways: - 1. Via the `render_callback` argument that can be passed to the `register_block_type()` function. - 2. Via a separate PHP file (usually named `render.php`) which path can be defined at the `render` propertyof the `block.json`. - -Blocks can have static or dynamic rendering: -- If no dynamic rendering has been been defined the rendering +
+The post Static vs. dynamic blocks: What’s the difference? provides a great introduction to static and dynamic blocks +
## Blocks with Static Rendering -Blocks with static rendering **generate the HMTL for the frontend at "update-time" (when it's saved)**: -- Blocks with static render use their markup representation in the DB to return the markup used in the frontend for the block -- The `save()` function writes the block’s markup inside the block indicators (HTML comments). -- Only the markup inside the block indicators is returned as markup to be rendered for the block in the frontend. -- For blocks with static render, the markup returned to the frontend is defined/set when the page is saved. +![](https://developer.wordpress.org/files/2023/12/static-rendering.png) + +Blocks have static rendering (a.k.a. Static Blocks) **when no dynamic rendering method has been defined (or is available) for the block**. In this case, the output for the front end will be taken from the [markup representation of the block in the database](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block/) that is generated (returned by the `save` function) when the block is saved in the Block Editor via the p. + +### How to define static rendering for a block + +The `save` function, which can be defined when registering a block on the client, determines the markup of the block that will be stored in the database when the content is saved and eventually returned to the front end when there's a request. This markup is stored wrapped up in [unique block delimiters](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block/), and only the markup inside these block indicators is returned as the markup to be rendered for the block in the front end. + +_Example of `save` function_ + +```js +import { useBlockProps } from '@wordpress/block-editor'; + +export default function save( { attributes } ) { + const { fallbackCurrentYear, showStartingYear, startingYear } = attributes; + + if ( ! fallbackCurrentYear ) return null; + let displayDate; + + if ( showStartingYear && startingYear ) { + displayDate = startingYear + '–' + fallbackCurrentYear; + } else { + displayDate = fallbackCurrentYear; + } + + return

© { displayDate }

; +} +``` + +_(see the [code above](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/save.js) in [an example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/copyright-date-block-09aac3))_ + +Blocks with dynamic rendering can also define a markup representation of the block via `save` as a backup for when the dynamic rendering method is no longer available (uninstallation of the plugin that registered the block). If no dynamic rendering method is found, any markup representation of the block in the database will be returned to the front end. + +
+Even for static blocks, the markup stored for a block can be modified before it gets rendered on the front end via hooks such as [`render_block`](https://developer.wordpress.org/reference/functions/render_block/). +
+ +## Blocks with Dynamic Rendering + +Blocks with Dynamic Rendering (a.k.a. Dynamic Blocks) are blocks that **build their structure and content on the fly when the block is requested from the client**. + +![](https://developer.wordpress.org/files/2023/12/dynamic-rendering.png) + +There are two primary uses for dynamic blocks: + +1. **Blocks where content should change even if a post has not been updated**. An example is the Latest Posts block - this block will update everywhere it is used when a new post is published. +2. **Blocks where updates to the code (HTML, CSS, JS) should be immediately shown on the front end of the website**. For example, if you update the structure of a block by adding a new class, adding an HTML element, or changing the layout in any other way, using a dynamic block ensures those changes are applied immediately on all occurrences of that block across the site. If a dynamic block is not used then when block code is updated Gutenberg's [validation process](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#validation) generally applies, causing users to see the validation message, "This block appears to have been modified externally". + +### How to define dynamic rendering for a block + +A block can define dynamic rendering in two main ways: +1. Via the `render_callback` argument that can be passed to the [`register_block_type()` function](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#registration-of-the-block-with-php-server-side). +1. Via a separate PHP file (usually named `render.php`) which path can be defined at the [`render` property of the `block.json`](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-json/#files-for-the-blocks-behavior-output-or-style). + +Both of these ways to define the block's dynamic rendering receive the following data: + - `$attributes` - The array of attributes for this block. + - `$content` - Rendered block output. + - `$block` - The instance of the [WP_Block](https://developer.wordpress.org/reference/classes/wp_block/) class that represents the block being rendered. + +_Example of `render.php` file for a block with `"render": "file:./render.php"` in its `block.json`_ + +```php + +$current_year = gmdate( 'Y' ); + +if ( isset( $attributes['fallbackCurrentYear'] ) && $attributes['fallbackCurrentYear'] === $current_year ) { + $block_content = $content; +} else { + + if ( ! empty( $attributes['startingYear'] ) && ! empty( $attributes['showStartingYear'] ) ) { + $display_date = $attributes['startingYear'] . '–' . $current_year; + } else { + $display_date = $current_year; + } + + $block_content = '

© ' . esc_html( $display_date ) . '

'; +} + +echo wp_kses_post( $block_content ); +``` + +_(see the [code above](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/render.php) in [an example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/copyright-date-block-09aac3))_ + +### HTML representation of dynamic blocks in the database (`save`) + +For dynamic blocks, the `save` callback function can return just `null`, which tells the editor to save only the [block attributes](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/) to the database. These attributes are then passed into the server-side rendering callback, so you can decide how to display the block on the front end of your site. **When `save` is `null`, the Block Editor will skip the block markup validation process**, avoiding issues with frequently-changing markup. + +Blocks with dynamic rendering can also save an HTML representation of the block. If you provide a server-side rendering callback, this HTML will be replaced with the output of your callback, but will be rendered if your block is deactivated or your render callback is removed. + +If you are using [InnerBlocks](/docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md) in a dynamic block you will need to save the `InnerBlocks` in the `save` callback function using `` + -## Blocks with Dynamic Rendering +## Additional Resources -Blocks with dynamic rendering **generate the HMTL for the frontend at "request-time" (when it's requested)** -- These blocks usually need to display info that is not known at the time the page is saved -- Dynamic rendering for a block can be defined: - - The `register_block_type()` function includes a `render_callback` argument. - - A `render` property is added to `block.json`, whose value points to a separate PHP file (usually named `render.php`). -- Dynamic render methods receive attribute, inner content information and additional required dynamic site information. \ No newline at end of file +- [Static vs. dynamic blocks: What’s the difference?](https://developer.wordpress.org/news/2023/02/27/static-vs-dynamic-blocks-whats-the-difference/) +- [Block deprecation – a tutorial](https://developer.wordpress.org/news/2023/03/10/block-deprecation-a-tutorial/) \ No newline at end of file From 143469960708a63b0ef6c6f8391ad6816abc23e0 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Thu, 21 Dec 2023 17:20:04 +0100 Subject: [PATCH 04/29] Update link in static-dynamic-rendering.md --- docs/getting-started/fundamentals/static-dynamic-rendering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index ce02e310938fa..b39425a61a022 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -45,7 +45,7 @@ _(see the [code above](https://github.com/WordPress/block-development-examples/b Blocks with dynamic rendering can also define a markup representation of the block via `save` as a backup for when the dynamic rendering method is no longer available (uninstallation of the plugin that registered the block). If no dynamic rendering method is found, any markup representation of the block in the database will be returned to the front end.
-Even for static blocks, the markup stored for a block can be modified before it gets rendered on the front end via hooks such as [`render_block`](https://developer.wordpress.org/reference/functions/render_block/). +Even for static blocks, the markup stored for a block can be modified before it gets rendered on the front end via hooks such as render_block.
## Blocks with Dynamic Rendering From 98587a805508c42a737a8c42aafc781d9aa90556 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Thu, 21 Dec 2023 17:22:02 +0100 Subject: [PATCH 05/29] Refactor static/dynamic rendering explanation in static-dynamic-rendering.md --- .../getting-started/fundamentals/static-dynamic-rendering.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index b39425a61a022..eff73d52173e1 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -1,9 +1,6 @@ # Static or Dynamic rendering of a block -The blocks's markup returned for the front end can be generated dynamically via a process in the server (dynamic blocks) or statically when the block is saved in the Block Editor (static blocks). - -- Blocks with static rendering _generate the HMTL for the frontend at "update-time" (when it's saved)_. -- Blocks with dynamic rendering _generate the HMTL for the frontend at "request-time" (when it's requested)_ +The blocks's markup returned for the front end can be dynamically generated on the server when the block is requested from the client (dynamic blocks) or statically when the block is saved in the Block Editor (static blocks).
The post Static vs. dynamic blocks: What’s the difference? provides a great introduction to static and dynamic blocks From f5e573215c50ffcbe79aa089d397d53f49653905 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Fri, 22 Dec 2023 10:06:00 +0100 Subject: [PATCH 06/29] Update static/dynamic rendering explanation --- .../fundamentals/static-dynamic-rendering.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index eff73d52173e1..4a27f37f7c297 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -1,6 +1,6 @@ # Static or Dynamic rendering of a block -The blocks's markup returned for the front end can be dynamically generated on the server when the block is requested from the client (dynamic blocks) or statically when the block is saved in the Block Editor (static blocks). +The blocks's markup returned for the front end can be dynamically generated on the server when the block is requested from the client (dynamic blocks) or statically generated when the block is saved in the Block Editor (static blocks).
The post Static vs. dynamic blocks: What’s the difference? provides a great introduction to static and dynamic blocks @@ -10,11 +10,11 @@ The post Even for static blocks, the markup stored for a block can be modified before it gets rendered on the front end via hooks such as render_block. From 3233c889b6cbf3939be99188b624d6f37d489eab Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Fri, 22 Dec 2023 11:22:04 +0100 Subject: [PATCH 07/29] Update block fundamentals documentation with core blocks examples --- docs/getting-started/fundamentals/README.md | 3 ++- .../fundamentals/static-dynamic-rendering.md | 16 ++++++++++++---- docs/manifest.json | 6 ++++++ docs/toc.json | 3 +++ 4 files changed, 23 insertions(+), 5 deletions(-) diff --git a/docs/getting-started/fundamentals/README.md b/docs/getting-started/fundamentals/README.md index 799ff89aa3941..f91253989ddf0 100644 --- a/docs/getting-started/fundamentals/README.md +++ b/docs/getting-started/fundamentals/README.md @@ -9,5 +9,6 @@ In this section, you will learn: 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/block-wrapper) - How to set proper attributes to the block's markup wrapper. 1. [**The block in the Editor**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-in-the-editor) - The block as a React component loaded in the Block Editor and its possibilities. -1. [**Markup representation of a block**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block) - How blocks are represented in the DB or in templates. +1. [**Markup representation of a block**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block) - How blocks are represented in the DB or templates. +1. [**Static or Dynamic rendering of a block**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering) - How blocks can generate their output for the front end dynamically or statically. 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/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index 4a27f37f7c297..1b5e60e7fb571 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -42,9 +42,14 @@ _(see the [code above](https://github.com/WordPress/block-development-examples/b Blocks with dynamic rendering can also define a markup representation of the block (via the `save` function) as a backup for when the dynamic rendering method is no longer available (uninstallation of the plugin that registered the block). If no dynamic rendering method is found, any markup representation of the block in the database will be returned to the front end.
-Even for static blocks, the markup stored for a block can be modified before it gets rendered on the front end via hooks such as render_block. +The markup stored for a block can be modified before it gets rendered on the front end via hooks such as render_block or via $render_callback
+Some examples of core blocks whose output for the front end is statically generated when saved to the database (as returned by their `save` functions) are: + +- [**`preformatted`**](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/preformatted) - see [`save`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/preformatted/save.js) function +- [**`spacer`**](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/spacer) - see [`save`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/spacer/save.js) function + ## Blocks with Dynamic Rendering Blocks with Dynamic Rendering (a.k.a. Dynamic Blocks) are blocks that **build their structure and content on the fly when the block is requested from the client**. @@ -93,12 +98,15 @@ _(see the [code above](https://github.com/WordPress/block-development-examples/b ### HTML representation of dynamic blocks in the database (`save`) -For dynamic blocks, the `save` callback function can return just `null`, which tells the editor to save only the [block attributes](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/) to the database. These attributes are then passed into the server-side rendering callback, so you can decide how to display the block on the front end of your site. **When `save` is `null`, the Block Editor will skip the block markup validation process**, avoiding issues with frequently-changing markup. +For dynamic blocks, the `save` callback function can return just `null`, which tells the editor to save only the [block attributes](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/) to the database. These attributes are then passed into the server-side rendering callback, so you can decide how to display the block on the front end of your site. **When `save` is `null`, the Block Editor will skip the block markup validation process**, avoiding issues with frequently changing markup. -Blocks with dynamic rendering can also save an HTML representation of the block. If you provide a server-side rendering callback, this HTML will be replaced with the output of your callback, but will be rendered if your block is deactivated or your render callback is removed. +Blocks with dynamic rendering can also save an HTML representation of the block as a backup. If you provide a server-side rendering callback, this HTML will be replaced with the output of your callback, but will be rendered if your block is deactivated or your render callback is removed. -If you are using [InnerBlocks](/docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md) in a dynamic block you will need to save the `InnerBlocks` in the `save` callback function using `` +In some cases, the block saves an HTML representation of the block and uses a dynamic rendering to fine-tune this markup if some conditions are met. Some examples of core blocks using this approach are: +- the [`cover`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover) core block saves a [full HTML representation of the block in the database](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover/save.js). This markup is processed via a [`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L74) when requested to do some PHP magic that dynamically [injects the featured image if the "use featured image" setting is enabled](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L16). +- the [`image`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/image) core block also saves [its HTML representation in the database](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/image/save.js) and processes it via a [`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/image/index.php#L363) when requested to [add some attributes to the markup](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/image/index.php#L18) if some conditions are met. +If you are using [InnerBlocks](/docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md) in a dynamic block you will need to save the `InnerBlocks` in the `save` callback function using `` ## Additional Resources diff --git a/docs/manifest.json b/docs/manifest.json index 7bb1e847ce03f..d8c6bd02d457f 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -95,6 +95,12 @@ "markdown_source": "../docs/getting-started/fundamentals/markup-representation-block.md", "parent": "fundamentals" }, + { + "title": "Static or Dynamic rendering of a block", + "slug": "static-dynamic-rendering", + "markdown_source": "../docs/getting-started/fundamentals/static-dynamic-rendering.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 961fc88fae4f5..36ab5a08397b4 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -42,6 +42,9 @@ { "docs/getting-started/fundamentals/markup-representation-block.md": [] }, + { + "docs/getting-started/fundamentals/static-dynamic-rendering.md": [] + }, { "docs/getting-started/fundamentals/javascript-in-the-block-editor.md": [] } From d830bfc01f122077b916d4c2b4f67f0cabdeafc6 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Fri, 22 Dec 2023 13:15:43 +0100 Subject: [PATCH 08/29] Refactor dynamic rendering in save function --- .../fundamentals/static-dynamic-rendering.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index 1b5e60e7fb571..8a0540e005adf 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -39,10 +39,10 @@ export default function save( { attributes } ) { _(see the [code above](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/save.js) in [an example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/copyright-date-block-09aac3))_ -Blocks with dynamic rendering can also define a markup representation of the block (via the `save` function) as a backup for when the dynamic rendering method is no longer available (uninstallation of the plugin that registered the block). If no dynamic rendering method is found, any markup representation of the block in the database will be returned to the front end. +Blocks with dynamic rendering can also define a markup representation of the block (via the `save` function). If no dynamic rendering method is found, any markup representation of the block in the database will be returned to the front end.
-The markup stored for a block can be modified before it gets rendered on the front end via hooks such as render_block or via $render_callback +The markup stored for a block can be modified before it gets rendered on the front end via hooks such as render_block or via $render_callback
Some examples of core blocks whose output for the front end is statically generated when saved to the database (as returned by their `save` functions) are: @@ -56,7 +56,7 @@ Blocks with Dynamic Rendering (a.k.a. Dynamic Blocks) are blocks that **build th ![](https://developer.wordpress.org/files/2023/12/dynamic-rendering.png) -There are two primary uses for dynamic blocks: +There are some common use cases for dynamic blocks: 1. **Blocks where content should change even if a post has not been updated**. An example is the Latest Posts block - this block will update everywhere it is used when a new post is published. 2. **Blocks where updates to the code (HTML, CSS, JS) should be immediately shown on the front end of the website**. For example, if you update the structure of a block by adding a new class, adding an HTML element, or changing the layout in any other way, using a dynamic block ensures those changes are applied immediately on all occurrences of that block across the site. If a dynamic block is not used then when block code is updated Gutenberg's [validation process](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#validation) generally applies, causing users to see the validation message, "This block appears to have been modified externally". @@ -69,8 +69,8 @@ A block can define dynamic rendering in two main ways: Both of these ways to define the block's dynamic rendering receive the following data: - `$attributes` - The array of attributes for this block. - - `$content` - Rendered block output. - - `$block` - The instance of the [WP_Block](https://developer.wordpress.org/reference/classes/wp_block/) class that represents the block being rendered. + - `$content` - Rendered block output (markup of the block as stored in the database). + - `$block` - The instance of the [WP_Block](https://developer.wordpress.org/reference/classes/wp_block/) class that represents the block being rendered ([metadata of the block](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/)). _Example of `render.php` file for a block with `"render": "file:./render.php"` in its `block.json`_ From b33923c0abafdab1764b75e904d2c7362035fc54 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Fri, 22 Dec 2023 13:17:52 +0100 Subject: [PATCH 09/29] Refactor static/dynamic rendering examples in static-dynamic-rendering.md --- .../getting-started/fundamentals/static-dynamic-rendering.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index 8a0540e005adf..683661d5fdee8 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -45,10 +45,7 @@ Blocks with dynamic rendering can also define a markup representation of the blo The markup stored for a block can be modified before it gets rendered on the front end via hooks such as render_block or via $render_callback
-Some examples of core blocks whose output for the front end is statically generated when saved to the database (as returned by their `save` functions) are: - -- [**`preformatted`**](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/preformatted) - see [`save`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/preformatted/save.js) function -- [**`spacer`**](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/spacer) - see [`save`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/spacer/save.js) function +Some examples of core blocks whose output for the front end is statically generated when saved to the database (as returned by their `save` functions) are[`preformatted`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/preformatted) (see its [`save`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/preformatted/save.js) function) or [`spacer`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/spacer) (see its [`save`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/spacer/save.js) function). ## Blocks with Dynamic Rendering From dc8d2d8af292c909df4b01e0eafb8d16fee611f7 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Fri, 22 Dec 2023 13:19:31 +0100 Subject: [PATCH 10/29] Update examples of core blocks with static rendering --- docs/getting-started/fundamentals/static-dynamic-rendering.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index 683661d5fdee8..0e9330bfc775b 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -45,7 +45,9 @@ Blocks with dynamic rendering can also define a markup representation of the blo The markup stored for a block can be modified before it gets rendered on the front end via hooks such as render_block or via $render_callback
-Some examples of core blocks whose output for the front end is statically generated when saved to the database (as returned by their `save` functions) are[`preformatted`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/preformatted) (see its [`save`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/preformatted/save.js) function) or [`spacer`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/spacer) (see its [`save`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/spacer/save.js) function). +Some examples of core blocks whose output for the front end is statically generated when saved to the database (as returned by their `save` functions) are: +- [`preformatted`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/preformatted) (see its [`save`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/preformatted/save.js) function) +- [`spacer`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/spacer) (see its [`save`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/spacer/save.js) function). ## Blocks with Dynamic Rendering From 9f629b7f409e866b6c867e80201bfbecfb8a2846 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Fri, 22 Dec 2023 13:21:48 +0100 Subject: [PATCH 11/29] Update InnerBlocks link in static-dynamic-rendering.md --- docs/getting-started/fundamentals/static-dynamic-rendering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index 0e9330bfc775b..ac7f8e090d34c 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -105,7 +105,7 @@ In some cases, the block saves an HTML representation of the block and uses a dy - the [`cover`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover) core block saves a [full HTML representation of the block in the database](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover/save.js). This markup is processed via a [`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L74) when requested to do some PHP magic that dynamically [injects the featured image if the "use featured image" setting is enabled](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L16). - the [`image`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/image) core block also saves [its HTML representation in the database](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/image/save.js) and processes it via a [`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/image/index.php#L363) when requested to [add some attributes to the markup](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/image/index.php#L18) if some conditions are met. -If you are using [InnerBlocks](/docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md) in a dynamic block you will need to save the `InnerBlocks` in the `save` callback function using `` +If you are using [InnerBlocks](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/nested-blocks-inner-blocks/) in a dynamic block you will need to save the `InnerBlocks` in the `save` callback function using `` ## Additional Resources From 5a6dd25671481d71e2bd9091b1d61a135dcffd2b Mon Sep 17 00:00:00 2001 From: JuanMa Date: Thu, 4 Jan 2024 16:35:24 +0100 Subject: [PATCH 12/29] Update docs/getting-started/fundamentals/README.md Co-authored-by: Nick Diego --- docs/getting-started/fundamentals/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals/README.md b/docs/getting-started/fundamentals/README.md index f91253989ddf0..0683e55d7edf7 100644 --- a/docs/getting-started/fundamentals/README.md +++ b/docs/getting-started/fundamentals/README.md @@ -9,6 +9,6 @@ In this section, you will learn: 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/block-wrapper) - How to set proper attributes to the block's markup wrapper. 1. [**The block in the Editor**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-in-the-editor) - The block as a React component loaded in the Block Editor and its possibilities. -1. [**Markup representation of a block**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block) - How blocks are represented in the DB or templates. +1. [**Markup representation of a block**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block) - How blocks are represented in the database, theme templates, or patterns. 1. [**Static or Dynamic rendering of a block**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering) - How blocks can generate their output for the front end dynamically or statically. 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 From b9e9bc2fd688dbed2c68b6e631c3208d6ca6226a Mon Sep 17 00:00:00 2001 From: JuanMa Date: Thu, 4 Jan 2024 16:36:02 +0100 Subject: [PATCH 13/29] Update docs/getting-started/fundamentals/markup-representation-block.md Co-authored-by: Nick Diego --- .../getting-started/fundamentals/markup-representation-block.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals/markup-representation-block.md b/docs/getting-started/fundamentals/markup-representation-block.md index 908881c4090c6..506d0feb8d3d1 100644 --- a/docs/getting-started/fundamentals/markup-representation-block.md +++ b/docs/getting-started/fundamentals/markup-representation-block.md @@ -23,7 +23,7 @@ The [markup representation of a block is parsed for the Block Editor](https://de Whenever a block is saved, the `save` function, defined when the [block is registered in the client](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#registration-of-the-block-with-javascript-client-side), is called to return the markup that will be saved into the database within the block delimiter's comment. If `save` is `null` (common case for blocks with dynamic rendering), only a single line block delimiter's comment is stored, along with any attributes The Post Editor checks that the markup created by the `save` function is identical to the block's markup saved to the database: -- If there are any differences, the Post Editor triggers a [**block validation error**](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#validation). +- If there are any differences, the Post Editor triggers a [block validation error](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#validation). - Block validation errors usually happen when a block’s `save` function is updated to change the markup produced by the block. - A block developer can mitigate these issues by adding a [**block deprecation**](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-deprecation/) to register the change in the block. From 798df7642976f1d4f2058773ba63741e6f4eeb35 Mon Sep 17 00:00:00 2001 From: JuanMa Date: Thu, 4 Jan 2024 16:36:24 +0100 Subject: [PATCH 14/29] Update docs/getting-started/fundamentals/static-dynamic-rendering.md Co-authored-by: Nick Diego --- docs/getting-started/fundamentals/static-dynamic-rendering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index ac7f8e090d34c..58e48e0fa3443 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -3,7 +3,7 @@ The blocks's markup returned for the front end can be dynamically generated on the server when the block is requested from the client (dynamic blocks) or statically generated when the block is saved in the Block Editor (static blocks).
-The post Static vs. dynamic blocks: What’s the difference? provides a great introduction to static and dynamic blocks +The post Static vs. dynamic blocks: What’s the difference? provides a great introduction to static and dynamic blocks.
## Blocks with Static Rendering From c9d20684927b198ff0a0bd666cf307b3e4293545 Mon Sep 17 00:00:00 2001 From: JuanMa Date: Thu, 4 Jan 2024 16:36:32 +0100 Subject: [PATCH 15/29] Update docs/getting-started/fundamentals/static-dynamic-rendering.md Co-authored-by: Nick Diego --- docs/getting-started/fundamentals/static-dynamic-rendering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index 58e48e0fa3443..dcf8fb43a35a9 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -1,6 +1,6 @@ # Static or Dynamic rendering of a block -The blocks's markup returned for the front end can be dynamically generated on the server when the block is requested from the client (dynamic blocks) or statically generated when the block is saved in the Block Editor (static blocks). +The block's markup returned on the front end can be dynamically generated on the server when the block is requested from the client (dynamic blocks) or statically generated when the block is saved in the Block Editor (static blocks).
The post Static vs. dynamic blocks: What’s the difference? provides a great introduction to static and dynamic blocks. From 5885922c5eb6e09c2dd9232913a5f945c19971ac Mon Sep 17 00:00:00 2001 From: JuanMa Date: Thu, 4 Jan 2024 16:36:57 +0100 Subject: [PATCH 16/29] Update docs/getting-started/fundamentals/static-dynamic-rendering.md Co-authored-by: Nick Diego --- docs/getting-started/fundamentals/static-dynamic-rendering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index dcf8fb43a35a9..0c98c426dc596 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -10,7 +10,7 @@ The post Date: Thu, 4 Jan 2024 16:37:16 +0100 Subject: [PATCH 17/29] Update docs/getting-started/fundamentals/static-dynamic-rendering.md Co-authored-by: Nick Diego --- docs/getting-started/fundamentals/static-dynamic-rendering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index 0c98c426dc596..b435d21033d1f 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -51,7 +51,7 @@ Some examples of core blocks whose output for the front end is statically genera ## Blocks with Dynamic Rendering -Blocks with Dynamic Rendering (a.k.a. Dynamic Blocks) are blocks that **build their structure and content on the fly when the block is requested from the client**. +Blocks with dynamic rendering are blocks that **build their structure and content on the fly when the block is requested from the client**. This type is block is often called a "dynamic block". ![](https://developer.wordpress.org/files/2023/12/dynamic-rendering.png) From 62407bf4f16badf673d02b1c2b317013d068aa90 Mon Sep 17 00:00:00 2001 From: JuanMa Date: Thu, 4 Jan 2024 16:37:33 +0100 Subject: [PATCH 18/29] Update docs/getting-started/fundamentals/static-dynamic-rendering.md Co-authored-by: Nick Diego --- docs/getting-started/fundamentals/static-dynamic-rendering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index b435d21033d1f..7625f7f2f93fa 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -14,7 +14,7 @@ Blocks have static rendering **when no dynamic rendering method has been defined ### How to define static rendering for a block -The `save` function, which can be defined when [registering a block on the client](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#registration-of-the-block-with-javascript-client-side), determines the markup of the block that will be stored in the database when the content is saved and eventually returned to the front end when there's a request. This markup is stored wrapped up in [unique block delimiters](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block/), and only the markup inside these block indicators is returned as the markup to be rendered for the block in the front end. +The `save` function, which can be defined when [registering a block on the client](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#registration-of-the-block-with-javascript-client-side), determines the markup of the block that will be stored in the database when the content is saved and eventually returned to the front end when there's a request. This markup is stored wrapped up in [unique block delimiters](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block/), and only the markup inside these block indicators is returned as the markup to be rendered for the block on the front end. _Example of `save` function_ From bcddeb8e50a353e519f6aadc73e4f60e40cb1b9b Mon Sep 17 00:00:00 2001 From: JuanMa Date: Thu, 4 Jan 2024 16:37:47 +0100 Subject: [PATCH 19/29] Update docs/getting-started/fundamentals/static-dynamic-rendering.md Co-authored-by: Nick Diego --- docs/getting-started/fundamentals/static-dynamic-rendering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index 7625f7f2f93fa..35e609f234b8b 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -49,7 +49,7 @@ Some examples of core blocks whose output for the front end is statically genera - [`preformatted`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/preformatted) (see its [`save`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/preformatted/save.js) function) - [`spacer`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/spacer) (see its [`save`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/spacer/save.js) function). -## Blocks with Dynamic Rendering +## Blocks with dynamic rendering Blocks with dynamic rendering are blocks that **build their structure and content on the fly when the block is requested from the client**. This type is block is often called a "dynamic block". From af1577c2bd5291a0ae024b04fee40a99299384ca Mon Sep 17 00:00:00 2001 From: JuanMa Date: Thu, 4 Jan 2024 16:37:57 +0100 Subject: [PATCH 20/29] Update docs/getting-started/fundamentals/static-dynamic-rendering.md Co-authored-by: Nick Diego --- docs/getting-started/fundamentals/static-dynamic-rendering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index 35e609f234b8b..2368577116f54 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -42,7 +42,7 @@ _(see the [code above](https://github.com/WordPress/block-development-examples/b Blocks with dynamic rendering can also define a markup representation of the block (via the `save` function). If no dynamic rendering method is found, any markup representation of the block in the database will be returned to the front end.
-The markup stored for a block can be modified before it gets rendered on the front end via hooks such as render_block or via $render_callback +The markup stored for a block can be modified before it gets rendered on the front end via hooks such as render_block or via $render_callback.
Some examples of core blocks whose output for the front end is statically generated when saved to the database (as returned by their `save` functions) are: From add1bba7201739f8278855bcdafe492202c11a21 Mon Sep 17 00:00:00 2001 From: JuanMa Date: Thu, 4 Jan 2024 16:38:06 +0100 Subject: [PATCH 21/29] Update docs/getting-started/fundamentals/static-dynamic-rendering.md Co-authored-by: Nick Diego --- docs/getting-started/fundamentals/static-dynamic-rendering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index 2368577116f54..3bb11a9ea13c4 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -93,7 +93,7 @@ if ( isset( $attributes['fallbackCurrentYear'] ) && $attributes['fallbackCurrent echo wp_kses_post( $block_content ); ``` -_(see the [code above](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/render.php) in [an example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/copyright-date-block-09aac3))_ +_(See the [code above](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/render.php) in [an example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/copyright-date-block-09aac3))_ ### HTML representation of dynamic blocks in the database (`save`) From 39ece62da832785b514b19d527dd5a1e2a1931d2 Mon Sep 17 00:00:00 2001 From: JuanMa Date: Thu, 4 Jan 2024 16:38:21 +0100 Subject: [PATCH 22/29] Update docs/getting-started/fundamentals/static-dynamic-rendering.md Co-authored-by: Nick Diego --- docs/getting-started/fundamentals/static-dynamic-rendering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index 3bb11a9ea13c4..38c52fac81d12 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -105,7 +105,7 @@ In some cases, the block saves an HTML representation of the block and uses a dy - the [`cover`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover) core block saves a [full HTML representation of the block in the database](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover/save.js). This markup is processed via a [`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L74) when requested to do some PHP magic that dynamically [injects the featured image if the "use featured image" setting is enabled](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L16). - the [`image`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/image) core block also saves [its HTML representation in the database](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/image/save.js) and processes it via a [`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/image/index.php#L363) when requested to [add some attributes to the markup](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/image/index.php#L18) if some conditions are met. -If you are using [InnerBlocks](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/nested-blocks-inner-blocks/) in a dynamic block you will need to save the `InnerBlocks` in the `save` callback function using `` +If you are using [InnerBlocks](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/nested-blocks-inner-blocks/) in a dynamic block, you will need to save the `InnerBlocks` in the `save` callback function using ``. ## Additional Resources From 9fb116a1284fa37ce4d96daf0da5ad23849bbc2f Mon Sep 17 00:00:00 2001 From: JuanMa Date: Thu, 4 Jan 2024 16:38:29 +0100 Subject: [PATCH 23/29] Update docs/getting-started/fundamentals/static-dynamic-rendering.md Co-authored-by: Nick Diego --- docs/getting-started/fundamentals/static-dynamic-rendering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index 38c52fac81d12..c37dc6e9ac9f6 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -103,7 +103,7 @@ Blocks with dynamic rendering can also save an HTML representation of the block In some cases, the block saves an HTML representation of the block and uses a dynamic rendering to fine-tune this markup if some conditions are met. Some examples of core blocks using this approach are: - the [`cover`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover) core block saves a [full HTML representation of the block in the database](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover/save.js). This markup is processed via a [`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L74) when requested to do some PHP magic that dynamically [injects the featured image if the "use featured image" setting is enabled](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L16). -- the [`image`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/image) core block also saves [its HTML representation in the database](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/image/save.js) and processes it via a [`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/image/index.php#L363) when requested to [add some attributes to the markup](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/image/index.php#L18) if some conditions are met. +- The [Image](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/image) block also saves [its HTML representation in the database](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/image/save.js) and processes it via a [`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/image/index.php#L363) when requested to [add some attributes to the markup](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/image/index.php#L18) if some conditions are met. If you are using [InnerBlocks](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/nested-blocks-inner-blocks/) in a dynamic block, you will need to save the `InnerBlocks` in the `save` callback function using ``. From 9f453867a16cd61d8999017d702cb25650706864 Mon Sep 17 00:00:00 2001 From: JuanMa Date: Thu, 4 Jan 2024 16:39:26 +0100 Subject: [PATCH 24/29] Update docs/getting-started/fundamentals/static-dynamic-rendering.md Co-authored-by: Nick Diego --- docs/getting-started/fundamentals/static-dynamic-rendering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index c37dc6e9ac9f6..70106c87c80db 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -102,7 +102,7 @@ For dynamic blocks, the `save` callback function can return just `null`, which t Blocks with dynamic rendering can also save an HTML representation of the block as a backup. If you provide a server-side rendering callback, this HTML will be replaced with the output of your callback, but will be rendered if your block is deactivated or your render callback is removed. In some cases, the block saves an HTML representation of the block and uses a dynamic rendering to fine-tune this markup if some conditions are met. Some examples of core blocks using this approach are: -- the [`cover`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover) core block saves a [full HTML representation of the block in the database](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover/save.js). This markup is processed via a [`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L74) when requested to do some PHP magic that dynamically [injects the featured image if the "use featured image" setting is enabled](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L16). +- The [Cover](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover) block saves a [full HTML representation of the block in the database](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover/save.js). This markup is processed via a [`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L74) when requested to do some PHP magic that dynamically [injects the featured image if the "use featured image" setting is enabled](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L16). - The [Image](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/image) block also saves [its HTML representation in the database](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/image/save.js) and processes it via a [`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/image/index.php#L363) when requested to [add some attributes to the markup](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/image/index.php#L18) if some conditions are met. If you are using [InnerBlocks](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/nested-blocks-inner-blocks/) in a dynamic block, you will need to save the `InnerBlocks` in the `save` callback function using ``. From 538f4384623e2259b7caa77adf766026ace2717c Mon Sep 17 00:00:00 2001 From: JuanMa Date: Thu, 4 Jan 2024 16:39:41 +0100 Subject: [PATCH 25/29] Update docs/getting-started/fundamentals/static-dynamic-rendering.md Co-authored-by: Nick Diego --- docs/getting-started/fundamentals/static-dynamic-rendering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index 70106c87c80db..3a939cc7d81c0 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -1,4 +1,4 @@ -# Static or Dynamic rendering of a block +# Static or dynamic rendering of a block The block's markup returned on the front end can be dynamically generated on the server when the block is requested from the client (dynamic blocks) or statically generated when the block is saved in the Block Editor (static blocks). From d93db3ca01735b71aadd6b74ed1aa739fb62ac11 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Fri, 5 Jan 2024 20:33:08 +0100 Subject: [PATCH 26/29] Update diagrams and improved examples --- .../fundamentals/static-dynamic-rendering.md | 133 ++++++++++++------ 1 file changed, 93 insertions(+), 40 deletions(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index 3a939cc7d81c0..1b9e157699356 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -6,59 +6,74 @@ The block's markup returned on the front end can be dynamically generated on the The post Static vs. dynamic blocks: What’s the difference? provides a great introduction to static and dynamic blocks.
-## Blocks with Static Rendering +## Static rendering -![](https://developer.wordpress.org/files/2023/12/static-rendering.png) +![Blocks with static rendering diagram](https://developer.wordpress.org/files/2024/01/static-rendering.png) -Blocks have static rendering **when no dynamic rendering method has been defined (or is available) for the block**. In this case, the output for the front end will be taken from the [markup representation of the block in the database](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block/) that is generated (returned by the `save` function) when the block is saved in the Block Editor. This type is block is often called a "static block". +Blocks have static rendering **when no dynamic rendering method has been defined (or is available) for the block**. In this case, the output for the front end will be taken from the [markup representation of the block in the database](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block/) that is generated (returned by the `save` function) when the block is saved in the Block Editor. This type is block is often called a **"static block"**. ### How to define static rendering for a block -The `save` function, which can be defined when [registering a block on the client](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#registration-of-the-block-with-javascript-client-side), determines the markup of the block that will be stored in the database when the content is saved and eventually returned to the front end when there's a request. This markup is stored wrapped up in [unique block delimiters](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block/), and only the markup inside these block indicators is returned as the markup to be rendered for the block on the front end. +The `save` function, which can be defined when [registering a block on the client](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#registration-of-the-block-with-javascript-client-side), determines the markup of the block that will be stored in the database when the content is saved and eventually returned to the front end when there's a request. This markup is stored wrapped up in [unique block delimiters](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block/) but only the markup inside these block indicators is returned as the markup to be rendered for the block on the front end. -_Example of `save` function_ +
Example static rendering of preformatted core block +
+For example, the following save function of the preformatted core block... ```js -import { useBlockProps } from '@wordpress/block-editor'; +import { RichText, useBlockProps } from '@wordpress/block-editor'; export default function save( { attributes } ) { - const { fallbackCurrentYear, showStartingYear, startingYear } = attributes; + const { content } = attributes; - if ( ! fallbackCurrentYear ) return null; - let displayDate; + return ( + 
+			
+
+ ); +} +``` - if ( showStartingYear && startingYear ) { - displayDate = startingYear + '–' + fallbackCurrentYear; - } else { - displayDate = fallbackCurrentYear; - } +...generates the following markup representation of the block when `attributes.content` has the value `"This is some preformatted text"`... - return

© { displayDate }

; -} +```html + +
This is some preformatted text
+ ``` -_(see the [code above](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/save.js) in [an example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/copyright-date-block-09aac3))_ +...and it will return the following markup for the block to the front end when there's a request. + +```html +
This is some preformatted text
+``` -Blocks with dynamic rendering can also define a markup representation of the block (via the `save` function). If no dynamic rendering method is found, any markup representation of the block in the database will be returned to the front end. +
+ +
+ +Blocks with dynamic rendering can also define a markup representation of the block (via the `save` function) which can be processed in the server before returning the markup to the front end. If no dynamic rendering method is found, any markup representation of the block in the database will be returned to the front end.
The markup stored for a block can be modified before it gets rendered on the front end via hooks such as render_block or via $render_callback.
-Some examples of core blocks whose output for the front end is statically generated when saved to the database (as returned by their `save` functions) are: -- [`preformatted`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/preformatted) (see its [`save`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/preformatted/save.js) function) +Some examples of core blocks with static rendering (a.k.a. static blocks), this is blocks which output for the front end is statically generated when saved to the database (as returned by their `save` functions), are: +- [`separator`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/separator) (see its [`save`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/separator/save.js) function) - [`spacer`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/spacer) (see its [`save`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/spacer/save.js) function). +- [`button`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/button) (see its [`save`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/button/save.js) function). + -## Blocks with dynamic rendering +## Dynamic rendering Blocks with dynamic rendering are blocks that **build their structure and content on the fly when the block is requested from the client**. This type is block is often called a "dynamic block". -![](https://developer.wordpress.org/files/2023/12/dynamic-rendering.png) +![Blocks with dynamic rendering diagram](https://developer.wordpress.org/files/2024/01/dynamic-rendering.png) There are some common use cases for dynamic blocks: -1. **Blocks where content should change even if a post has not been updated**. An example is the Latest Posts block - this block will update everywhere it is used when a new post is published. -2. **Blocks where updates to the code (HTML, CSS, JS) should be immediately shown on the front end of the website**. For example, if you update the structure of a block by adding a new class, adding an HTML element, or changing the layout in any other way, using a dynamic block ensures those changes are applied immediately on all occurrences of that block across the site. If a dynamic block is not used then when block code is updated Gutenberg's [validation process](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#validation) generally applies, causing users to see the validation message, "This block appears to have been modified externally". +1. **Blocks where content should change even if a post has not been updated**. An example is the [`latest-posts` core block](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/latest-posts) which will update its content, on request time, everywhere it is used after a new post is published. +2. **Blocks where updates to the markup should be immediately shown on the front end of the website**. For example, if you update the structure of a block by adding a new class, adding an HTML element, or changing the layout in any other way, using a dynamic block ensures those changes are applied immediately on all occurrences of that block across the site. If a dynamic block is not used then when block code is updated Gutenberg's [validation process](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#validation) generally applies, causing users to see the validation message, "This block appears to have been modified externally". ### How to define dynamic rendering for a block @@ -71,39 +86,77 @@ Both of these ways to define the block's dynamic rendering receive the following - `$content` - Rendered block output (markup of the block as stored in the database). - `$block` - The instance of the [WP_Block](https://developer.wordpress.org/reference/classes/wp_block/) class that represents the block being rendered ([metadata of the block](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/)). -_Example of `render.php` file for a block with `"render": "file:./render.php"` in its `block.json`_ +
Example dynamic rendering of site-title core block +
-```php +For example, the [`site-title`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/site-title) core block with the following function registered as [`render_callback`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/site-title/index.php)... -$current_year = gmdate( 'Y' ); -if ( isset( $attributes['fallbackCurrentYear'] ) && $attributes['fallbackCurrentYear'] === $current_year ) { - $block_content = $content; -} else { +```php +function render_block_core_site_title( $attributes ) { + $site_title = get_bloginfo( 'name' ); + if ( ! $site_title ) { + return; + } + + $tag_name = 'h1'; + $classes = empty( $attributes['textAlign'] ) ? '' : "has-text-align-{$attributes['textAlign']}"; + if ( isset( $attributes['style']['elements']['link']['color']['text'] ) ) { + $classes .= ' has-link-color'; + } - if ( ! empty( $attributes['startingYear'] ) && ! empty( $attributes['showStartingYear'] ) ) { - $display_date = $attributes['startingYear'] . '–' . $current_year; - } else { - $display_date = $current_year; + if ( isset( $attributes['level'] ) ) { + $tag_name = 0 === $attributes['level'] ? 'p' : 'h' . (int) $attributes['level']; } - $block_content = '

© ' . esc_html( $display_date ) . '

'; + if ( $attributes['isLink'] ) { + $aria_current = is_home() || ( is_front_page() && 'page' === get_option( 'show_on_front' ) ) ? ' aria-current="page"' : ''; + $link_target = ! empty( $attributes['linkTarget'] ) ? $attributes['linkTarget'] : '_self'; + + $site_title = sprintf( + '%4$s', + esc_url( home_url() ), + esc_attr( $link_target ), + $aria_current, + esc_html( $site_title ) + ); + } + $wrapper_attributes = get_block_wrapper_attributes( array( 'class' => trim( $classes ) ) ); + + return sprintf( + '<%1$s %2$s>%3$s', + $tag_name, + $wrapper_attributes, + // already pre-escaped if it is a link. + $attributes['isLink'] ? $site_title : esc_html( $site_title ) + ); } +``` -echo wp_kses_post( $block_content ); +... generates the following markup representation of the block in the database (as [there's no `save` function defined for this block](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/site-title/index.js))... + +```html + +``` + +...and it could generate the following markup for the block to the front end when there's a request (depending on the specific values on the server at request time). + +``` +

My WordPress Website

``` -_(See the [code above](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/render.php) in [an example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/copyright-date-block-09aac3))_ +
+
### HTML representation of dynamic blocks in the database (`save`) -For dynamic blocks, the `save` callback function can return just `null`, which tells the editor to save only the [block attributes](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/) to the database. These attributes are then passed into the server-side rendering callback, so you can decide how to display the block on the front end of your site. **When `save` is `null`, the Block Editor will skip the block markup validation process**, avoiding issues with frequently changing markup. +For dynamic blocks, the `save` callback function can return just `null`, which tells the editor to save only the block delimiter comment (along with any existing [block attributes](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/)) to the database. These attributes are then passed into the server-side rendering callback, which will determine how to display the block on the front end of your site. **When `save` is `null`, the Block Editor will skip the [block markup validation process](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#validation)**, avoiding issues with frequently changing markup. Blocks with dynamic rendering can also save an HTML representation of the block as a backup. If you provide a server-side rendering callback, this HTML will be replaced with the output of your callback, but will be rendered if your block is deactivated or your render callback is removed. In some cases, the block saves an HTML representation of the block and uses a dynamic rendering to fine-tune this markup if some conditions are met. Some examples of core blocks using this approach are: -- The [Cover](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover) block saves a [full HTML representation of the block in the database](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover/save.js). This markup is processed via a [`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L74) when requested to do some PHP magic that dynamically [injects the featured image if the "use featured image" setting is enabled](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L16). -- The [Image](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/image) block also saves [its HTML representation in the database](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/image/save.js) and processes it via a [`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/image/index.php#L363) when requested to [add some attributes to the markup](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/image/index.php#L18) if some conditions are met. +- The [`cover`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover) block saves a [full HTML representation of the block in the database](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover/save.js). This markup is processed via a [`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L74) when requested to do some PHP magic that dynamically [injects the featured image if the "use featured image" setting is enabled](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L16). +- The [`image`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/image) block also saves [its HTML representation in the database](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/image/save.js) and processes it via a [`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/image/index.php#L363) when requested to [add some attributes to the markup](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/image/index.php#L18) if some conditions are met. If you are using [InnerBlocks](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/nested-blocks-inner-blocks/) in a dynamic block, you will need to save the `InnerBlocks` in the `save` callback function using ``. From 5995411d25da04c0c4ece8f7895a1ac0357703b4 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Sun, 7 Jan 2024 12:11:50 +0100 Subject: [PATCH 27/29] Updates on the text as per Justin's feedback --- .../fundamentals/static-dynamic-rendering.md | 20 +++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index 1b9e157699356..7c4be264d8a6b 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -10,13 +10,17 @@ The post Example static rendering of preformatted core block +To define static rendering for a block we define just a `save` function for the block without any dynamic rendering method. + +
Example of static rendering of the preformatted core block
For example, the following save function of the preformatted core block... @@ -58,7 +62,7 @@ Blocks with dynamic rendering can also define a markup representation of the blo The markup stored for a block can be modified before it gets rendered on the front end via hooks such as render_block or via $render_callback. -Some examples of core blocks with static rendering (a.k.a. static blocks), this is blocks which output for the front end is statically generated when saved to the database (as returned by their `save` functions), are: +Some examples of core blocks with static rendering are: - [`separator`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/separator) (see its [`save`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/separator/save.js) function) - [`spacer`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/spacer) (see its [`save`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/spacer/save.js) function). - [`button`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/button) (see its [`save`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/button/save.js) function). @@ -66,14 +70,14 @@ Some examples of core blocks with static rendering (a.k.a. static blocks), this ## Dynamic rendering -Blocks with dynamic rendering are blocks that **build their structure and content on the fly when the block is requested from the client**. This type is block is often called a "dynamic block". +Blocks with dynamic rendering are blocks that **build their structure and content on the fly when the block is requested from the client**. This type of block is often called a "dynamic block". ![Blocks with dynamic rendering diagram](https://developer.wordpress.org/files/2024/01/dynamic-rendering.png) There are some common use cases for dynamic blocks: -1. **Blocks where content should change even if a post has not been updated**. An example is the [`latest-posts` core block](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/latest-posts) which will update its content, on request time, everywhere it is used after a new post is published. -2. **Blocks where updates to the markup should be immediately shown on the front end of the website**. For example, if you update the structure of a block by adding a new class, adding an HTML element, or changing the layout in any other way, using a dynamic block ensures those changes are applied immediately on all occurrences of that block across the site. If a dynamic block is not used then when block code is updated Gutenberg's [validation process](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#validation) generally applies, causing users to see the validation message, "This block appears to have been modified externally". +1. **Blocks where content should change even if a post has not been updated**. An example is the [`latest-posts` core block](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/latest-posts), which will update its content on request time, everywhere it is used after a new post is published. +2. **Blocks where updates to the markup should be immediately shown on the front end of the website**. For example, if you update the structure of a block by adding a new class, adding an HTML element, or changing the layout in any other way, using a dynamic block ensures those changes are applied immediately on all occurrences of that block across the site. If a dynamic block is not used then when block code is updated, Gutenberg's [validation process](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#validation) generally applies, causing users to see the validation message: "This block appears to have been modified externally". ### How to define dynamic rendering for a block @@ -86,7 +90,7 @@ Both of these ways to define the block's dynamic rendering receive the following - `$content` - Rendered block output (markup of the block as stored in the database). - `$block` - The instance of the [WP_Block](https://developer.wordpress.org/reference/classes/wp_block/) class that represents the block being rendered ([metadata of the block](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/)). -
Example dynamic rendering of site-title core block +
Example of dynamic rendering of the site-title core block
For example, the [`site-title`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/site-title) core block with the following function registered as [`render_callback`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/site-title/index.php)... @@ -152,7 +156,7 @@ function render_block_core_site_title( $attributes ) { For dynamic blocks, the `save` callback function can return just `null`, which tells the editor to save only the block delimiter comment (along with any existing [block attributes](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/)) to the database. These attributes are then passed into the server-side rendering callback, which will determine how to display the block on the front end of your site. **When `save` is `null`, the Block Editor will skip the [block markup validation process](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#validation)**, avoiding issues with frequently changing markup. -Blocks with dynamic rendering can also save an HTML representation of the block as a backup. If you provide a server-side rendering callback, this HTML will be replaced with the output of your callback, but will be rendered if your block is deactivated or your render callback is removed. +Blocks with dynamic rendering can also save an HTML representation of the block as a backup. If you provide a server-side rendering callback, this HTML will be replaced with the output of your callback, but will be rendered if your block is deactivated (the plugin that registers the block is uninstalled) or your render callback is removed. In some cases, the block saves an HTML representation of the block and uses a dynamic rendering to fine-tune this markup if some conditions are met. Some examples of core blocks using this approach are: - The [`cover`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover) block saves a [full HTML representation of the block in the database](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover/save.js). This markup is processed via a [`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L74) when requested to do some PHP magic that dynamically [injects the featured image if the "use featured image" setting is enabled](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L16). From 1c8bd48d06388bd519b7c07608fae9326dd691f2 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Sun, 7 Jan 2024 20:28:52 +0100 Subject: [PATCH 28/29] small adjustments --- docs/getting-started/fundamentals/static-dynamic-rendering.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index 7c4be264d8a6b..b08ec16018070 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -18,7 +18,7 @@ Blocks have static rendering **when no dynamic rendering method has been defined The `save` function, which can be defined when [registering a block on the client](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#registration-of-the-block-with-javascript-client-side), determines the markup of the block that will be stored in the database when the content is saved and eventually returned to the front end when there's a request. This markup is stored wrapped up in [unique block delimiters](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block/) but only the markup inside these block indicators is returned as the markup to be rendered for the block on the front end. -To define static rendering for a block we define just a `save` function for the block without any dynamic rendering method. +To define static rendering for a block we define a `save` function for the block without any dynamic rendering method.
Example of static rendering of the preformatted core block
@@ -156,7 +156,7 @@ function render_block_core_site_title( $attributes ) { For dynamic blocks, the `save` callback function can return just `null`, which tells the editor to save only the block delimiter comment (along with any existing [block attributes](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/)) to the database. These attributes are then passed into the server-side rendering callback, which will determine how to display the block on the front end of your site. **When `save` is `null`, the Block Editor will skip the [block markup validation process](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#validation)**, avoiding issues with frequently changing markup. -Blocks with dynamic rendering can also save an HTML representation of the block as a backup. If you provide a server-side rendering callback, this HTML will be replaced with the output of your callback, but will be rendered if your block is deactivated (the plugin that registers the block is uninstalled) or your render callback is removed. +Blocks with dynamic rendering can also save an HTML representation of the block as a backup. If you provide a server-side rendering callback, the HTML representing the block in the database will be replaced with the output of your callback, but will be rendered if your block is deactivated (the plugin that registers the block is uninstalled) or your render callback is removed. In some cases, the block saves an HTML representation of the block and uses a dynamic rendering to fine-tune this markup if some conditions are met. Some examples of core blocks using this approach are: - The [`cover`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover) block saves a [full HTML representation of the block in the database](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover/save.js). This markup is processed via a [`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L74) when requested to do some PHP magic that dynamically [injects the featured image if the "use featured image" setting is enabled](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L16). From 879b3cab7907ae1cabd72f95921d4144b813c8b6 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Mon, 8 Jan 2024 18:21:34 +0100 Subject: [PATCH 29/29] Fix capitalization in static-dynamic-rendering.md --- docs/getting-started/fundamentals/static-dynamic-rendering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index b08ec16018070..34d5432850c45 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -1,4 +1,4 @@ -# Static or dynamic rendering of a block +# Static or Dynamic rendering of a block The block's markup returned on the front end can be dynamically generated on the server when the block is requested from the client (dynamic blocks) or statically generated when the block is saved in the Block Editor (static blocks).