From 1a11a846eee74f990fe40d17ac2fd1ab28195f50 Mon Sep 17 00:00:00 2001 From: Jorge Date: Tue, 21 May 2019 23:37:01 +0100 Subject: [PATCH 1/4] Add: note in the save function documentation to discourage side effects --- .../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 362bc08e6bcce..2eb46192dd7be 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 `wp.data.select...`. +If the function uses external information when the external information changes for the same attribute values, the save result may vary, and when that happens, the block will be considered invalid by the editor. +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. + - Add another attribute value that contains the needed value that the save function depends on and dynamically update that value in the `edit` component which can depend on external information and contain side effects to update the attribute when the external information changes. + 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. From 484b32e0058d625c4e0c4d2e13154404a4b07227 Mon Sep 17 00:00:00 2001 From: Jorge Costa Date: Wed, 22 May 2019 20:16:12 +0100 Subject: [PATCH 2/4] Update docs/designers-developers/developers/block-api/block-edit-save.md Co-Authored-By: Andrew Duthie --- .../developers/block-api/block-edit-save.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 2eb46192dd7be..bc1cf20ac0054 100644 --- a/docs/designers-developers/developers/block-api/block-edit-save.md +++ b/docs/designers-developers/developers/block-api/block-edit-save.md @@ -228,7 +228,7 @@ _Note:_ While it is possible to return a string value from `save`, it _will be e _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 `wp.data.select...`. -If the function uses external information when the external information changes for the same attribute values, the save result may vary, and when that happens, the block will be considered invalid by the editor. +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. - Add another attribute value that contains the needed value that the save function depends on and dynamically update that value in the `edit` component which can depend on external information and contain side effects to update the attribute when the external information changes. From b3e1a035c11144391f055fd2bc32ee8e8d6cc9c9 Mon Sep 17 00:00:00 2001 From: Jorge Costa Date: Wed, 22 May 2019 20:17:11 +0100 Subject: [PATCH 3/4] Update docs/designers-developers/developers/block-api/block-edit-save.md Co-Authored-By: Andrew Duthie --- .../developers/block-api/block-edit-save.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 bc1cf20ac0054..b527f96037355 100644 --- a/docs/designers-developers/developers/block-api/block-edit-save.md +++ b/docs/designers-developers/developers/block-api/block-edit-save.md @@ -231,7 +231,7 @@ It can not have any side effect or retrieve information from another source, e.g 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. - - Add another attribute value that contains the needed value that the save function depends on and dynamically update that value in the `edit` component which can depend on external information and contain side effects to update the attribute when the external information changes. + - 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. From a81b20469d49d97346ca13621eefa72ece2d102a Mon Sep 17 00:00:00 2001 From: Jorge Date: Wed, 22 May 2019 20:21:21 +0100 Subject: [PATCH 4/4] Not reference globals --- .../developers/block-api/block-edit-save.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 b527f96037355..5d0cc72b6c6b7 100644 --- a/docs/designers-developers/developers/block-api/block-edit-save.md +++ b/docs/designers-developers/developers/block-api/block-edit-save.md @@ -227,7 +227,7 @@ 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 `wp.data.select...`. +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.