From c53f62193e354b14f62933e6a89dfd94ac0a6124 Mon Sep 17 00:00:00 2001 From: Jorge Costa Date: Wed, 22 May 2019 22:35:44 +0100 Subject: [PATCH] Add: note in the save function documentation to discourage side effects (#15765) I noticed people are not aware side effects cannot be used in the save function, and people use the data module in the save function e.g: to query the post title. This may easily break the blocks. This commit updates the documentation to make people more aware of this problem. --- .../developers/block-api/block-edit-save.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/designers-developers/developers/block-api/block-edit-save.md b/docs/designers-developers/developers/block-api/block-edit-save.md index 362bc08e6bccef..5d0cc72b6c6b78 100644 --- a/docs/designers-developers/developers/block-api/block-edit-save.md +++ b/docs/designers-developers/developers/block-api/block-edit-save.md @@ -226,6 +226,13 @@ For most blocks, the return value of `save` should be an [instance of WordPress _Note:_ While it is possible to return a string value from `save`, it _will be escaped_. If the string includes HTML markup, the markup will be shown on the front of the site verbatim, not as the equivalent HTML node content. If you must return raw HTML from `save`, use `wp.element.RawHTML`. As the name implies, this is prone to [cross-site scripting](https://en.wikipedia.org/wiki/Cross-site_scripting) and therefore is discouraged in favor of a WordPress Element hierarchy whenever possible. +_Note:_ The save function should be a pure function that depends only on the attributes used to invoke it. +It can not have any side effect or retrieve information from another source, e.g. it is not possible to use the data module inside it `select( store ).selector( ... )`. +This is because if the external information changes, the block may be flagged as invalid when the post is later edited ([read more about Validation](#validation)). +If there is a need to have other information as part of the save, developers can consider one of these two alternatives: + - Use [dynamic blocks](/docs/designers-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md) and dynamically retrieve the required information on the server. + - Store the external value as an attribute which is dynamically updated in the block's `edit` function as changes occur. + For [dynamic blocks](/docs/designers-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md), the return value of `save` could represent a cached copy of the block's content to be shown only in case the plugin implementing the block is ever disabled. If left unspecified, the default implementation will save no markup in post content for the dynamic block, instead deferring this to always be calculated when the block is shown on the front of the site.