A new convert method will shortly become the preferred way to define the way in which one (or more blocks) can be transformed into one (or more) other blocks using the Block Transforms mechanic.

Currently developers define a transform method on the transform object definition in which they defined how to transform the block.

transforms: {
	from: [ {
		type: 'block',
		blocks: ['*'],
		transform: (attributes, innerBlocks) => {
			// do the transforming!
		}),
	} ],
},

The issue is that this function is provided with only 2 arguments

1. Block attributes
2. Block innerBlocks

However, there are many cases where having access to the entire Block object is required (eg: for example see the Grouping mechanic).

After a lengthy discussion in Slack and having reviewed several options, it was decided to create a new convert method which would accept the full block object.

transforms: {
	from: [ {
		type: 'block',
		blocks: ['*'],
		convert: (blocks) => {
			// do the transforming with all the block data!
		}),
	} ],
},

When the transform is applied this convert method is always run in preference over any transform method. However, if no convert method is defined then the transform method will be attempted. As a result it is fully backwards compatible.

transforms: {
	from: [ {
		type: 'block',
		blocks: ['*'],
		convert: (blocks) => {
			// this will run in preference to the transform method below
		}),
		transform: (attributes, innerBlocks) => {
			// this will NOT be run as convert takes precedence
		}),
	} ],
},

We now need to fully document this change. This involves:

• Updating the Transforms API documentation
• Some other tasks...

See also #14908