Skip to content

Commit

Permalink
Expand explanation of uses for dynamic blocks (#16228)
Browse files Browse the repository at this point in the history
* 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 <[email protected]>

* Update docs/designers-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md

Final suggestion accepted.

Co-Authored-By: Chris Van Patten <[email protected]>
  • Loading branch information
jodamo5 and chrisvanpatten committed Jun 29, 2019
1 parent b0ed6f5 commit 462d1a5
Showing 1 changed file with 12 additions and 1 deletion.
Original file line number Diff line number Diff line change
@@ -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.

Expand Down

0 comments on commit 462d1a5

Please sign in to comment.