From 462d1a58f3e249252800c0c8e0df56794f4edb7c Mon Sep 17 00:00:00 2001 From: jodamo5 Date: Sun, 30 Jun 2019 01:07:04 +1200 Subject: [PATCH] Expand explanation of uses for dynamic blocks (#16228) * Expand explanation of uses for dynamic blocks Gives clearer explanation of dynamic blocks uses. This update especially explains the need to use dynamic blocks if developers want their block updates to be immediately reflected on the front end of the site, instead of Gutenberg's validation process applying. * Apply suggestions to documentation All suggestions have been accepted. Co-Authored-By: Chris Van Patten * Update docs/designers-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md Final suggestion accepted. Co-Authored-By: Chris Van Patten --- .../block-tutorial/creating-dynamic-blocks.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md b/docs/designers-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md index 73448eadf0d02..f21c3b3f09988 100644 --- a/docs/designers-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md +++ b/docs/designers-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md @@ -1,6 +1,17 @@ # Creating dynamic blocks -Dynamic blocks are blocks that can change their content even if the post is not saved. One example from WordPress itself is the latest posts block. This block will update everywhere it is used when a new post is published. +Dynamic blocks are blocks that build their structure and content on the fly when the block is rendered on the front end. + +There are two primary uses for dynamic blocks: + +1. Blocks where content should change even if a post has not been updated. One example from WordPress itself 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 HTML structure of a block by adding a new class, adding a div, or changing the layout in any other way, if you want these changes to be applied immediately on all occurrences of that block across the site, a dynamic block should be used. (If a dynamic block is not used then when block code is updated Guterberg's [validation process](https://developer.wordpress.org/block-editor/developers/block-api/block-edit-save/#validation) applies, causing users to see the validation message, "This block appears to have been modified externally"). + +For many dynamic blocks, the `save` callback function should be returned as `null`, which tells the editor to save only the [block attributes](https://developer.wordpress.org/block-editor/developers/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 you return `null`, the editor will skip the block markup validation process, avoiding issues with frequently-changing markup. + +You 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. + +Block attributes can be used for any content or setting you want to save for that block. In the first example above, with the latest posts block, the number of latest posts you want to show could be saved as an attribute. Or in the second example, attributes can be used for each piece of content you want to show in the front end - such as heading text, paragraph text, an image, a URL, etc. The following code example shows how to create a dynamic block that shows only the last post as a link.