Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Block API: Deprecate block transform function in favor of convert #19401

Closed
wants to merge 7 commits into from
Closed

Block API: Deprecate block transform function in favor of convert #19401

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
315df11
Block API: Rename __experimentalConvert to convert
aduth Jan 2, 2020
b3d1583
Block API: Add unit test for convert singular block form
aduth Jan 2, 2020
067cf46
Block API: Deprecate block transform in favor of convert
aduth Jan 3, 2020
23f3af1
Docs: Remove redundant mention of innerBlocks transform
aduth Jan 3, 2020
ee62090
Docs: Simplify conversion examplse
aduth Jan 3, 2020
e36e9b2
Docs: Fix Heading -> Paragraph transform example code
aduth Jan 3, 2020
22e5859
Docs: Document multi-block transforms
aduth Jan 3, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
146 changes: 100 additions & 46 deletions docs/designers-developers/developers/block-api/block-registration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -204,9 +204,9 @@ transforms: {
{
type: 'block',
blocks: [ 'core/paragraph' ],
transform: function ( attributes ) {
convert: function ( block ) {
return createBlock( 'core/heading', {
content: attributes.content,
content: block.attributes.content,
} );
},
},
Expand All @@ -220,9 +220,9 @@ transforms: {
{
type: 'block',
blocks: [ 'core/paragraph' ],
transform: ( { content } ) => {
convert( block ) {
return createBlock( 'core/heading', {
content,
content: block.attributes.content,
} );
},
},
Expand Down Expand Up @@ -303,10 +303,10 @@ transforms: {
to: [
{
type: 'block',
blocks: [ 'core/paragraph' ],
transform: function( attributes ) {
blocks: [ 'core/heading' ],
convert: function( block ) {
return createBlock( 'core/paragraph', {
content: attributes.content,
content: block.attributes.content,
} );
},
},
Expand All @@ -319,10 +319,10 @@ transforms: {
to: [
{
type: 'block',
blocks: [ 'core/paragraph' ],
transform: ( { content } ) => {
blocks: [ 'core/heading' ],
convert( block ) {
return createBlock( 'core/paragraph', {
content,
content: block.attributes.content,
} );
},
},
Expand All @@ -331,52 +331,106 @@ transforms: {
```
{% end %}

In addition to accepting an array of known block types, the `blocks` option also accepts a "wildcard" (`"*"`). This allows for transformations which apply to _all_ block types (eg: all blocks can transform into `core/group`):
It can also be transformed to multiple blocks by returning an array of blocks from the `convert` function.

{% codetabs %}
{% ES5 %}
```js
transforms: {
from: [
{
type: 'block',
blocks: [ '*' ], // wildcard - match any block
transform: function( attributes, innerBlocks ) {
// transform logic here
},
},
],
to: [
{
type: 'block',
blocks: [ 'core/paragraph' ],
convert: function( block ) {
var words = block.attributes.content.split( ' ' );

return words.map( function( word ) {
return createBlock( 'core/paragraph', {
content: word,
} );
} );
},
},
],
},
```
{% ESNext %}
```js
transforms: {
from: [
{
type: 'block',
blocks: [ '*' ], // wildcard - match any block
transform: ( attributes, innerBlocks ) => {
// transform logic here
},
},
],
to: [
{
type: 'block',
blocks: [ 'core/paragraph' ],
convert( block ) {
const words = block.attributes.content.split( ' ' );

return words.map( ( word ) => {
return createBlock( 'core/paragraph', {
content: word,
} );
} );
},
},
],
},
```
{% end %}

Similarly, multiple blocks can be transformed to one or more blocks. Including an `isMultiBlock` property value of `true` will indicate that the `convert` function should receive an array of blocks. Currently, multi-block transforms are only supported for blocks of the same type. For example, multiple Paragraph blocks can be converted to a List block.

A block with InnerBlocks can also be transformed from and to another block with InnerBlocks.
{% codetabs %}
{% ES5 %}
```js
transforms: {
to: [
{
type: 'block',
isMultiBlock: true,
blocks: [ 'core/paragraph' ],
convert: function( blocks ) {
return createBlock( 'core/list', {
values: blocks.reduce( function( result, block ) {
return result + '<li>' + block.attributes.content + '</li>';
}, '' ),
} );
},
},
],
},
```
{% ESNext %}
```js
transforms: {
to: [
{
type: 'block',
isMultiBlock: true,
blocks: [ 'core/paragraph' ],
convert( blocks ) {
return createBlock( 'core/list', {
values: blocks.reduce( ( result, block ) => {
return result + '<li>' + block.attributes.content + '</li>';
}, '' ),
} );
},
},
],
},
```
{% end %}

In addition to accepting an array of known block types, the `blocks` option also accepts a "wildcard" (`"*"`). This allows for transformations which apply to _all_ block types (eg: all blocks can transform into `core/group`):

{% codetabs %}
{% ES5 %}
```js
transforms: {
to: [
from: [
{
type: 'block',
blocks: [ 'some/block-with-innerblocks' ],
transform: function( attributes, innerBlocks ) {
return createBlock( 'some/other-block-with-innerblocks', attributes, innerBlocks );
blocks: [ '*' ], // wildcard - match any block
convert: function( block ) {
// transform logic here
},
},
],
Expand All @@ -385,12 +439,12 @@ transforms: {
{% ESNext %}
```js
transforms: {
to: [
from: [
{
type: 'block',
blocks: [ 'some/block-with-innerblocks' ],
transform: ( attributes, innerBlocks ) => {
return createBlock( 'some/other-block-with-innerblocks', attributes, innerBlocks);
blocks: [ '*' ], // wildcard - match any block
convert( block ) {
// transform logic here
},
},
],
Expand All @@ -411,9 +465,9 @@ transforms: {
isMatch: function( attributes ) {
return attributes.isText;
},
transform: function( attributes ) {
convert: function( block ) {
return createBlock( 'core/paragraph', {
content: attributes.content,
content: block.attributes.content,
} );
},
},
Expand All @@ -428,9 +482,9 @@ transforms: {
type: 'block',
blocks: [ 'core/paragraph' ],
isMatch: ( { isText } ) => isText,
transform: ( { content } ) => {
convert( block ) {
return createBlock( 'core/paragraph', {
content,
content: block.attributes.content,
} );
},
},
Expand Down Expand Up @@ -474,7 +528,7 @@ transforms: {
// We define a lower priority (higher number) than the default of 10. This
// ensures that the File block is only created as a fallback.
priority: 15,
transform: function( files ) {
convert: function( files ) {
var file = files[ 0 ];
var blobURL = createBlobURL( file );

Expand All @@ -499,7 +553,7 @@ transforms: {
// We define a lower priority (higher number) than the default of 10. This
// ensures that the File block is only created as a fallback.
priority: 15,
transform: ( files ) => {
convert( files ) {
const file = files[ 0 ];
const blobURL = createBlobURL( file );

Expand All @@ -526,7 +580,7 @@ transforms: {
{
type: 'prefix',
prefix: '?',
transform: function( content ) {
convert: function( content ) {
return createBlock( 'my-plugin/question', {
content,
} );
Expand All @@ -542,7 +596,7 @@ transforms: {
{
type: 'prefix',
prefix: '?',
transform( content ) {
convert( content ) {
return createBlock( 'my-plugin/question', {
content,
} );
Expand Down
2 changes: 1 addition & 1 deletion packages/block-editor/src/components/block-drop-zone/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ class BlockDropZone extends Component {

if ( transformation ) {
const insertIndex = this.getInsertIndex( position );
const blocks = transformation.transform( files, this.props.updateBlockAttributes );
const blocks = transformation.convert( files, this.props.updateBlockAttributes );
this.props.insertBlocks( blocks, insertIndex );
}
}
Expand Down
6 changes: 3 additions & 3 deletions packages/block-editor/src/components/block-switcher/test/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,12 +58,12 @@ describe( 'BlockSwitcher', () => {
{
type: 'block',
blocks: [ 'core/paragraph' ],
transform: () => {},
convert: () => {},
},
{
type: 'block',
blocks: [ 'core/paragraph' ],
transform: () => {},
convert: () => {},
isMultiBlock: true,
},
],
Expand All @@ -79,7 +79,7 @@ describe( 'BlockSwitcher', () => {
to: [ {
type: 'block',
blocks: [ 'core/heading' ],
transform: () => {},
convert: () => {},
} ],
},
} );
Expand Down
4 changes: 2 additions & 2 deletions packages/block-editor/src/components/rich-text/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ class RichTextWrapper extends Component {

if ( transformation ) {
onReplace( [
transformation.transform( { content: value.text } ),
transformation.convert( { content: value.text } ),
] );
markAutomaticChange();
}
Expand Down Expand Up @@ -290,7 +290,7 @@ class RichTextWrapper extends Component {
}

const content = valueToFormat( slice( value, start, text.length ) );
const block = transformation.transform( content );
const block = transformation.convert( content );

onReplace( [ block ] );
markAutomaticChange();
Expand Down
2 changes: 1 addition & 1 deletion packages/block-editor/src/store/test/effects.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -206,7 +206,7 @@ describe( 'effects', () => {
to: [ {
type: 'block',
blocks: [ 'core/test-block' ],
transform: ( { content2 } ) => {
convert: ( { attributes: { content2 } } ) => {
return createBlock( 'core/test-block', {
content: content2,
} );
Expand Down
2 changes: 1 addition & 1 deletion packages/block-library/src/audio/transforms.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ const transforms = {
isMatch( files ) {
return files.length === 1 && files[ 0 ].type.indexOf( 'audio/' ) === 0;
},
transform( files ) {
convert( files ) {
const file = files[ 0 ];
// We don't need to upload the media directly here
// It's already done as part of the `componentDidMount`
Expand Down
2 changes: 1 addition & 1 deletion packages/block-library/src/code/transforms.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ const transforms = {
{
type: 'enter',
regExp: /^```$/,
transform: () => createBlock( 'core/code' ),
convert: () => createBlock( 'core/code' ),
},
{
type: 'raw',
Expand Down
8 changes: 4 additions & 4 deletions packages/block-library/src/cover/transforms.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ const transforms = {
{
type: 'block',
blocks: [ 'core/image' ],
transform: ( { caption, url, align, id } ) => (
convert: ( { attributes: { caption, url, align, id } } ) => (
createBlock( 'core/cover', {
title: caption,
url,
Expand All @@ -25,7 +25,7 @@ const transforms = {
{
type: 'block',
blocks: [ 'core/video' ],
transform: ( { caption, src, align, id } ) => (
convert: ( { attributes: { caption, src, align, id } } ) => (
createBlock( 'core/cover', {
title: caption,
url: src,
Expand All @@ -48,7 +48,7 @@ const transforms = {
// If a url is not set the transform could happen if the cover has no background color or gradient;
return ! overlayColor && ! customOverlayColor && ! gradient && ! customGradient;
},
transform: ( { title, url, align, id } ) => (
convert: ( { attributes: { title, url, align, id } } ) => (
createBlock( 'core/image', {
caption: title,
url,
Expand All @@ -68,7 +68,7 @@ const transforms = {
// If a url is not set the transform could happen if the cover has no background color or gradient;
return ! overlayColor && ! customOverlayColor && ! gradient && ! customGradient;
},
transform: ( { title, url, align, id } ) => (
convert: ( { attributes: { title, url, align, id } } ) => (
createBlock( 'core/video', {
caption: title,
src: url,
Expand Down
8 changes: 4 additions & 4 deletions packages/block-library/src/embed/core-embeds.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,10 +155,10 @@ export const others = [
title: 'Crowdsignal',
icon: embedContentIcon,
keywords: [ 'polldaddy' ],
transform: [ {
convert: [ {
type: 'block',
blocks: [ 'core-embed/polldaddy' ],
transform: ( content ) => {
convert: ( content ) => {
return createBlock( 'core-embed/crowdsignal', {
content,
} );
Expand Down Expand Up @@ -316,10 +316,10 @@ export const others = [
settings: {
title: 'Speaker Deck',
icon: embedContentIcon,
transform: [ {
convert: [ {
type: 'block',
blocks: [ 'core-embed/speaker' ],
transform: ( content ) => {
convert: ( content ) => {
return createBlock( 'core-embed/speaker-deck', {
content,
} );
Expand Down
Loading