This page provides a comprehensive guide to the principles and usage of the Deprecation API. For an introduction check out the tutorial on the basics of block deprecation which can be found on the Developer Blog .
-
Do not deprecate the block and create a new one (a different name) -
Provide a “deprecated” version of the block allowing users opening these in the block editor to edit them using the updated block.
-
If the current save method does not produce a valid block the first deprecation in the deprecations array is passed the original saved content. -
If its save method produces valid content this deprecation is used to parse the block attributes. If it has a migrate method it will also be run using the attributes parsed by the deprecation. -
If the first deprecation’s save method does not produce a valid block the subsequent deprecations in the array are tried until one producing a valid block is encountered. -
The attributes, and any innerBlocks, from the first deprecation to generate a valid block are then passed back to the current save method to generate new valid content for the block. -
At this point the current block should now be in a valid state and the deprecations workflow stops.
const v1 = {}; const v2 = {}; const v3 = {}; const deprecated = [ v3, v2, v1 ];
attributes (Object): The attributes definition of the deprecated form of the block. supports (Object): The supports definition of the deprecated form of the block. save (Function): The save implementation 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 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 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 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.
-
attributes
supports
save
const { registerBlockType } = wp.blocks; const attributes = { text: { type: 'string', default: 'some random value', }, }; const supports = { className: false, }; registerBlockType( 'gutenberg/block-with-deprecated-version', { // ... other block properties go here attributes, supports, save( props ) { return <div>{ props.attributes.text }</div>; }, deprecated: [ { attributes, supports, save( props ) { return <p>{ props.attributes.text }</p>; }, }, ], } );
Changing the attributes set
const { registerBlockType } = wp.blocks; registerBlockType( 'gutenberg/block-with-deprecated-version', { // ... other block properties go here attributes: { content: { type: 'string', default: 'some random value', }, }, save( props ) { return <div>{ props.attributes.content }</div>; }, deprecated: [ { attributes: { text: { type: 'string', default: 'some random value', }, }, migrate( { text } ) { return { content: text, }; }, save( props ) { return <p>{ props.attributes.text }</p>; }, }, ], } );
Changing the innerBlocks
const { registerBlockType } = wp.blocks; registerBlockType( 'gutenberg/block-with-deprecated-version', { // ... block properties go here save( props ) { return <p>{ props.attributes.title }</p>; }, deprecated: [ { attributes: { title: { type: 'string', source: 'html', selector: 'p', }, }, migrate( attributes, innerBlocks ) { const { title, ... restAttributes } = attributes; return [ restAttributes, [ createBlock( 'core/paragraph', { content: attributes.title, fontSize: 'large', } ), ...innerBlocks, ], ]; }, save( props ) { return <p>{ props.attributes.title }</p>; }, }, ], } );