From 48b6a21617984ace9079ad66641cd4951d3b90d3 Mon Sep 17 00:00:00 2001 From: Nick Diego Date: Sat, 3 Feb 2024 15:41:26 -0600 Subject: [PATCH 1/2] Initial edits. --- .../fundamentals/static-dynamic-rendering.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index 214fb9da8b40fc..441595ab1485cb 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -8,11 +8,13 @@ The post Date: Mon, 5 Feb 2024 10:07:45 -0600 Subject: [PATCH 2/2] Copy and formatting edits. --- .../fundamentals/static-dynamic-rendering.md | 80 ++++++++++--------- 1 file changed, 42 insertions(+), 38 deletions(-) diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index 441595ab1485cb..c7a692a8ecb654 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -1,30 +1,30 @@ # 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). +A block's front-end markup can either be dynamically generated server-side upon request (dynamic blocks) or statically generated during the save process in the Block Editor (static blocks). This article explores each method.
-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 this topic.
## Static rendering -Blocks with "static rendering" produce front-end output that is fixed and stored in the database upon saving. These blocks rely solely on their `save` function to define the [HTML markup](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block/), which remains unchanged unless manually edited in the Block Editor. +Blocks with "static rendering" produce front-end output that is fixed and stored in the database upon saving. These blocks rely solely on their `save` function to define their [HTML markup](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block/), which remains unchanged unless manually edited in the Block Editor. If a block does not use a dynamic rendering method—meaning it doesn't generate content on the fly via PHP when the page loads—it's considered a "static block." -The diagram below illustrates how static block content is saved in the database and retrieved and rendered as HTML on the front end. +The diagram below illustrates how static block content is saved in the database and then retrieved and rendered as HTML on the front end. ![Blocks with static rendering diagram](https://developer.wordpress.org/files/2024/01/static-rendering.png) ### 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/) but 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), specifies the block's HTML structure that gets saved in the database whenever you save the block in the Editor. This saved HTML is then used to display the block on the front end. -To define static rendering for a block we define a `save` function for the block without any dynamic rendering method. +Blocks in WordPress are encapsulated within special comment tags that serve as unique [block delimiters](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block/). However, only the HTML defined in the static block's `save` function—excluding these delimiters—is rendered. -
Example of static rendering of the preformatted core block +
View an example of static rendering in the Preformatted block
-For example, the following save function of the preformatted core block... +The following save function for the Preformatted core block looks like this: ```js import { RichText, useBlockProps } from '@wordpress/block-editor'; @@ -40,7 +40,7 @@ export default function save( { attributes } ) { } ``` -...generates the following markup representation of the block when `attributes.content` has the value `"This is some preformatted text"`... +The function generates the following markup representation of the block when `attributes.content` has the value `"This is some preformatted text"`: ```html @@ -48,57 +48,59 @@ export default function save( { attributes } ) { ``` -...and it will return the following markup for the block to the front end when there's a request. +On the front end, the block will return the following markup. Notice how the delimiters are no longer present. ```html 
This is some preformatted text
``` -
-
-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. +Dynamic blocks, which we'll explore in the following section, can specify an initial HTML structure through a `save` function, similar to static blocks. However, dynamic blocks primarily rely on server-side rendering to generate their content. If, for any reason, the dynamic rendering isn't available—perhaps due to the block's plugin being deactivated—the system will fall back to using the HTML structure saved in the database to display the block on the front end. + +For a practical demonstration of how this works, refer to the [Building your first block](/docs/getting-started/tutorial.md) tutorial. Specifically, the [Adding static rendering](/docs/getting-started/tutorial.md#adding-static-rendering) section illustrates how a block can have both a saved HTML structure and dynamic rendering capabilities.
-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. +WordPress provides mechanisms like the render_block are the $render_callback function to alter the saved HTML of a block before it appears on the front end. These tools offer developers the capability to customize block output dynamically, catering to complex and interactive user experiences.
-Some examples of core blocks with static rendering are: +Additional examples of WordPress blocks that use static rendering, meaning their output is fixed at the time of saving and doesn't rely on server-side processing, include: -- [`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). +- [Separator](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/separator/save.js) +- [Spacer](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/spacer/save.js) +- [Button](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/button/save.js) ## 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 of block is often called a "dynamic block". +Blocks with "dynamic rendering" are designed to generate their content and structure in real-time when requested on the front end. Unlike static blocks, which have a fixed HTML structure saved in the database, "dynamic blocks" rely on server-side processing to construct their output dynamically, making them highly versatile and suitable for content that needs to be updated frequently or is dependent on external data. + +The diagram below illustrates how the representation of a dynamic block is saved in the database and then retrieved and dynamically rendered as HTML on the front end. ![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](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/latest-posts) block, which will automatically update whenever a new post is published. +2. **Blocks where updates to the markup should be immediately shown on the front end:** 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. Without dynamic blocks, similar updates could trigger [validation errors](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#validation) in the Block Editor. ### 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). -2. 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). +1. Using the `render_callback` argument that can be passed to the [`register_block_type()`](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#registration-of-the-block-with-php-server-side) function. +2. Using a separate PHP file usually named `render.php`. This file's path should be defined using the [`render`](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-json/#files-for-the-blocks-behavior-output-or-style) property in the `block.json` file. -Both of these ways to define the block's dynamic rendering receive the following data: +Both of these methods receive the following data: - - `$attributes` - The array of attributes for this block. - - `$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/)). + - `$attributes`: The array of attributes for the block. + - `$content`: The markup of the block as stored in the database, if any. + - `$block`: The instance of the [WP_Block](https://developer.wordpress.org/reference/classes/wp_block/) class that represents the rendered block ([metadata of the block](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/)). -
Example of dynamic rendering of the site-title core block +
View an example of dynamic rendering in the Site Title 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)... +The [Site Title](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/site-title) block uses the following [`render_callback`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/site-title/index.php): ```php function render_block_core_site_title( $attributes ) { @@ -141,13 +143,13 @@ function render_block_core_site_title( $attributes ) { } ``` -... 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))... +However, there is no `save` function defined for this block, as you can see from its [`index.js`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/site-title/index.js) file, which means the markup representation of the block in the database looks like this: ```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). +On the front end, the `render_callback` is used to dynamically render the markup for the block depending on the specific values on the server at the time the block is requested. These values include the current site title, URL, link target, etc. ```

My WordPress Website

@@ -158,18 +160,20 @@ function render_block_core_site_title( $attributes ) { ### 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 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. +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, 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. +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). -- 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](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover/save.js) a full HTML representation of the block in the database. This markup is processed via a [`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L74), which [dynamically injects](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L16) the featured image if the "Use featured image" setting is enabled. +- The [Image](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/image) block also [saves](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/image/save.js) its HTML representation in the database. This markup is processed via a [`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/image/index.php#L363), which [adds additional attributes](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/image/index.php#L18) to the markup if specific 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 ``. -## Additional Resources +## Additional resources -- [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 +- [Static vs. dynamic blocks: What’s the difference?](https://developer.wordpress.org/news/2023/02/27/static-vs-dynamic-blocks-whats-the-difference/) | Developer Blog +- [Block deprecation – a tutorial](https://developer.wordpress.org/news/2023/03/10/block-deprecation-a-tutorial/) | Developer Blog \ No newline at end of file