From 899d85f432bf9360ccd5b618a92188e2154ce2fc Mon Sep 17 00:00:00 2001 From: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com> Date: Tue, 7 Mar 2023 16:01:12 +1000 Subject: [PATCH 1/4] Block Deprecations: Provide extra data for isEligible check --- docs/reference-guides/block-api/block-deprecation.md | 6 +++--- .../src/api/parser/apply-block-deprecated-versions.js | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/reference-guides/block-api/block-deprecation.md b/docs/reference-guides/block-api/block-deprecation.md index 0314939ee8f64..35908ec4476b0 100644 --- a/docs/reference-guides/block-api/block-deprecation.md +++ b/docs/reference-guides/block-api/block-deprecation.md @@ -38,7 +38,7 @@ Deprecations are defined on a block type as its `deprecated` property, an array - `supports` (Object): The [supports definition](/docs/reference-guides/block-api/block-registration.md) of the deprecated form of the block. - `save` (Function): The [save implementation](/docs/reference-guides/block-api/block-edit-save.md) of the deprecated form of the block. - `migrate` (Function, Optional): A function which, given the old attributes and inner blocks is expected to return either the new attributes or a tuple array of `[ attributes, innerBlocks ]` compatible with the block. As mentioned above, a deprecation's `migrate` will not be run if its `save` function does not return a valid block so you will need to make sure your migrations are available in all the deprecations where they are relevant. -- `isEligible` (Function, Optional): A function which, given the attributes and inner blocks of the parsed block, returns true if the deprecation can handle the block migration even if the block is valid. This is particularly useful in cases where a block is technically valid even once deprecated, but still requires updates to its attributes or inner blocks. This function is not called when the results of all previous deprecations' `save` functions were invalid. +- `isEligible` (Function, Optional): A function which, given the attributes and inner blocks of the parsed block, returns true if the deprecation can handle the block migration even if the block is valid. This is particularly useful in cases where a block is technically valid even once deprecated, but still requires updates to its attributes or inner blocks. If further information is required to determine this deprecation's eligibility, the entire block object is provided within a third parameter. This function is not called when the results of all previous deprecations' `save` functions were invalid. It's important to note that `attributes`, `supports`, and `save` are not automatically inherited from the current version, since they can impact parsing and serialization of a block, so they must be defined on the deprecated object in order to be processed during a migration. @@ -63,7 +63,7 @@ registerBlockType( 'gutenberg/block-with-deprecated-version', { // ... other block properties go here attributes, - + supports, save( props ) { @@ -73,7 +73,7 @@ registerBlockType( 'gutenberg/block-with-deprecated-version', { deprecated: [ { attributes, - + supports, save( props ) { diff --git a/packages/blocks/src/api/parser/apply-block-deprecated-versions.js b/packages/blocks/src/api/parser/apply-block-deprecated-versions.js index 2a3e880a3f746..54ccddb9a5c9e 100644 --- a/packages/blocks/src/api/parser/apply-block-deprecated-versions.js +++ b/packages/blocks/src/api/parser/apply-block-deprecated-versions.js @@ -50,7 +50,7 @@ export function applyBlockDeprecatedVersions( block, rawBlock, blockType ) { const { isEligible = stubFalse } = deprecatedDefinitions[ i ]; if ( block.isValid && - ! isEligible( parsedAttributes, block.innerBlocks ) + ! isEligible( parsedAttributes, block.innerBlocks, { block } ) ) { continue; } From eb137f1756428222a16503e566b8552866b57e29 Mon Sep 17 00:00:00 2001 From: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com> Date: Thu, 9 Mar 2023 17:17:13 +1000 Subject: [PATCH 2/4] Provide raw block node as well --- docs/reference-guides/block-api/block-deprecation.md | 2 +- .../blocks/src/api/parser/apply-block-deprecated-versions.js | 5 ++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/reference-guides/block-api/block-deprecation.md b/docs/reference-guides/block-api/block-deprecation.md index 35908ec4476b0..bf4d9239cd307 100644 --- a/docs/reference-guides/block-api/block-deprecation.md +++ b/docs/reference-guides/block-api/block-deprecation.md @@ -38,7 +38,7 @@ Deprecations are defined on a block type as its `deprecated` property, an array - `supports` (Object): The [supports definition](/docs/reference-guides/block-api/block-registration.md) of the deprecated form of the block. - `save` (Function): The [save implementation](/docs/reference-guides/block-api/block-edit-save.md) of the deprecated form of the block. - `migrate` (Function, Optional): A function which, given the old attributes and inner blocks is expected to return either the new attributes or a tuple array of `[ attributes, innerBlocks ]` compatible with the block. As mentioned above, a deprecation's `migrate` will not be run if its `save` function does not return a valid block so you will need to make sure your migrations are available in all the deprecations where they are relevant. -- `isEligible` (Function, Optional): A function which, given the attributes and inner blocks of the parsed block, returns true if the deprecation can handle the block migration even if the block is valid. This is particularly useful in cases where a block is technically valid even once deprecated, but still requires updates to its attributes or inner blocks. If further information is required to determine this deprecation's eligibility, the entire block object is provided within a third parameter. This function is not called when the results of all previous deprecations' `save` functions were invalid. +- `isEligible` (Function, Optional): A function which, given the attributes and inner blocks of the parsed block, returns true if the deprecation can handle the block migration even if the block is valid. This is particularly useful in cases where a block is technically valid even once deprecated, but still requires updates to its attributes or inner blocks. If further information is required to determine this deprecation's eligibility, the block node and object are provided within a third parameter. This function is not called when the results of all previous deprecations' `save` functions were invalid. It's important to note that `attributes`, `supports`, and `save` are not automatically inherited from the current version, since they can impact parsing and serialization of a block, so they must be defined on the deprecated object in order to be processed during a migration. diff --git a/packages/blocks/src/api/parser/apply-block-deprecated-versions.js b/packages/blocks/src/api/parser/apply-block-deprecated-versions.js index 54ccddb9a5c9e..6c9d81d47b031 100644 --- a/packages/blocks/src/api/parser/apply-block-deprecated-versions.js +++ b/packages/blocks/src/api/parser/apply-block-deprecated-versions.js @@ -50,7 +50,10 @@ export function applyBlockDeprecatedVersions( block, rawBlock, blockType ) { const { isEligible = stubFalse } = deprecatedDefinitions[ i ]; if ( block.isValid && - ! isEligible( parsedAttributes, block.innerBlocks, { block } ) + ! isEligible( parsedAttributes, block.innerBlocks, { + blockNode: rawBlock, + block, + } ) ) { continue; } From efd2cd7bd6f484ada942433ed4fc32dc4786e261 Mon Sep 17 00:00:00 2001 From: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com> Date: Tue, 14 Mar 2023 18:53:14 +1000 Subject: [PATCH 3/4] Try to reformat and improve docs clarity further --- .../block-api/block-deprecation.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/docs/reference-guides/block-api/block-deprecation.md b/docs/reference-guides/block-api/block-deprecation.md index bf4d9239cd307..308d5e00c7229 100644 --- a/docs/reference-guides/block-api/block-deprecation.md +++ b/docs/reference-guides/block-api/block-deprecation.md @@ -37,8 +37,21 @@ Deprecations are defined on a block type as its `deprecated` property, an array - `attributes` (Object): The [attributes definition](/docs/reference-guides/block-api/block-attributes.md) of the deprecated form of the block. - `supports` (Object): The [supports definition](/docs/reference-guides/block-api/block-registration.md) of the deprecated form of the block. - `save` (Function): The [save implementation](/docs/reference-guides/block-api/block-edit-save.md) of the deprecated form of the block. -- `migrate` (Function, Optional): A function which, given the old attributes and inner blocks is expected to return either the new attributes or a tuple array of `[ attributes, innerBlocks ]` compatible with the block. As mentioned above, a deprecation's `migrate` will not be run if its `save` function does not return a valid block so you will need to make sure your migrations are available in all the deprecations where they are relevant. -- `isEligible` (Function, Optional): A function which, given the attributes and inner blocks of the parsed block, returns true if the deprecation can handle the block migration even if the block is valid. This is particularly useful in cases where a block is technically valid even once deprecated, but still requires updates to its attributes or inner blocks. If further information is required to determine this deprecation's eligibility, the block node and object are provided within a third parameter. This function is not called when the results of all previous deprecations' `save` functions were invalid. +- `migrate`: (Function, Optional). A function which, given the old attributes and inner blocks is expected to return either the new attributes or a tuple array of attributes and inner blocks compatible with the block. As mentioned above, a deprecation's `migrate` will not be run if its `save` function does not return a valid block so you will need to make sure your migrations are available in all the deprecations where they are relevant. + - _Parameters_ + - `attributes`: The block's old attributes. + - `innerBlocks`: The block's old inner blocks. + - _Return_ + - `Object | Array`: Either the updated block attributes or tuple array `[attributes, innerBlocks]`. +- `isEligible`: (Function, Optional). A function which returns `true` if the deprecation can handle the block migration even if the block is valid. It is particularly useful in cases where a block is technically valid even once deprecated, but still requires updates to its attributes or inner blocks. This function is **not** called when the results of all previous deprecations' save functions were invalid. + - _Parameters_ + - `attributes`: The block attributes parsed directly from the saved markup without being passed through any further code. + - `innerBlocks`: The block's current inner blocks. + - `data`: An object containing properties representing the block node and its resulting block object. + - `data.blockNode`: The raw form of the block and the result of simply parsing the serialized HTML. + - `data.block`: The block object, which is the result of feeding the `blockNode` through the block type's code. + - _Return_ + - `boolean`: Whether or not this otherwise valid block is eligible to be migrated by this deprecation. It's important to note that `attributes`, `supports`, and `save` are not automatically inherited from the current version, since they can impact parsing and serialization of a block, so they must be defined on the deprecated object in order to be processed during a migration. From 2532a4698c42f7c76265eee231ee03eff6221ffe Mon Sep 17 00:00:00 2001 From: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com> Date: Wed, 15 Mar 2023 13:35:42 +1000 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Daniel Richards --- docs/reference-guides/block-api/block-deprecation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference-guides/block-api/block-deprecation.md b/docs/reference-guides/block-api/block-deprecation.md index 308d5e00c7229..d3773948112c4 100644 --- a/docs/reference-guides/block-api/block-deprecation.md +++ b/docs/reference-guides/block-api/block-deprecation.md @@ -45,11 +45,11 @@ Deprecations are defined on a block type as its `deprecated` property, an array - `Object | Array`: Either the updated block attributes or tuple array `[attributes, innerBlocks]`. - `isEligible`: (Function, Optional). A function which returns `true` if the deprecation can handle the block migration even if the block is valid. It is particularly useful in cases where a block is technically valid even once deprecated, but still requires updates to its attributes or inner blocks. This function is **not** called when the results of all previous deprecations' save functions were invalid. - _Parameters_ - - `attributes`: The block attributes parsed directly from the saved markup without being passed through any further code. + - `attributes`: The raw block attributes as parsed from the serialized HTML, and before the block type code is applied. - `innerBlocks`: The block's current inner blocks. - `data`: An object containing properties representing the block node and its resulting block object. - - `data.blockNode`: The raw form of the block and the result of simply parsing the serialized HTML. - - `data.block`: The block object, which is the result of feeding the `blockNode` through the block type's code. + - `data.blockNode`: The raw form of the block as a result of parsing the serialized HTML. + - `data.block`: The block object, which is the result of applying the block type to the `blockNode`. - _Return_ - `boolean`: Whether or not this otherwise valid block is eligible to be migrated by this deprecation.