Provide more documentation on how to convert RichText with multiline property to use InnerBlocks instead

[kory-northrop]

I developed a custom static block years ago that uses the component with the multiline property. I've started seeing the following notice in the web developer console when editing posts in Gutenberg:

wp.blockEditor.RichText multiline prop is deprecated since version 6.1 and will be removed in version 6.3. Please use nested blocks (InnerBlocks) instead. See: https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/nested-blocks-inner-blocks/

I've poured over that documentation as well as the Deprecation page, but cannot quite figure out how to accomplish the task of converting my block to use and still honor the original functionality that I built and be backwards compatible. I imagine that it involves using migrate() within the deprecated array, but I am struggling to crack the code and don't feel like there's ample documentation to help developers with this kind of conversion.

Here is a simplified example of what the block looked like originally:

// ...

attributes: {
    blurb: {
        type: 'string',
        source: 'html',
        multiline: 'p',
        selector: '.hello-custom-cta__blurb',
    },
},

edit: ( props ) => {
    const blockProps = useBlockProps( { className: 'custom-cta p-0 mb-0' } );
    const { attributes: { blurb }, setAttributes, className } = props;

    return (
        <div { ...blockProps }>
            <RichText
                tagName="div"
                multiline="p"
                className="custom-cta__blurb w-100"
                translate-name="blurb"
                onChange={ value => setAttributes( { blurb: value } ) }
                placeholder={ __( 'Subtext goes here (optional)', 'hello-tools' ) }
                value={ blurb }
                allowedFormats={ [ 'core/bold', 'core/italic' ] }
                focusOnInsert={ false }
                />
          </div>
    );
}

save: ( props ) => {
    const blockProps = useBlockProps.save();
    const { attributes: { blurb } } = props;

    return (
        <div { ...blockProps }>
            <RichText.Content 
                className="hello-custom-cta__blurb" 
                tagName="div" 
                value={ blurb } 
            />    
        </div>
    );
}

This is what the block looks like now as I'm trying to replace <RichText> multiline with <InnerBlocks />:

edit: ( props ) => {
    const blockProps = useBlockProps( { className: 'custom-cta p-0 mb-0' } );

    const blurbTemplate = [['core/paragraph', { placeholder: __( 'Subtext goes here (optional)', 'hello-tools' ) }]];
    let blurbAllowedBlocks = ['core/paragraph'];

    return (
        <div { ...blockProps }>
            <div className={'hello-custom-cta__blurb font-weight-light mt-0 w-100'}>
                <InnerBlocks
                    allowedBlocks={ blurbAllowedBlocks }
                    template={ blurbTemplate }
                    templateLock={ false }
                    templateInsertUpdatesSelection={ false }
                />
            </div>
        </div>
    );
}

save: ( props )  => {
    const blockProps = useBlockProps.save();

    return (
        <div { ...blockProps }>
            <div className="hello-custom-cta__blurb">
                <InnerBlocks.Content />
            </div>
        </div>
    );
}

[t-hamano]

Hi @kory-northrop,

Personally, I think that there are so many different cases of block migration and deprecation that it is sometimes difficult to document them.

If it's a case like yours. a migration of the list block may be helpful.

Also, the use of a react hook called useInnerBlocksProps would give you more flexibility and control over the markup of the inner block.

[kory-northrop]

Thanks for your reply @t-hamano. I looked over those resources and feel like I made some progress, but I'm still not successfully deprecating this block.

This is the message in the developer console, which makes me think that the new deprecation version is not converting the saved multiline RichText content properly.

Block validation: Expected token of type `EndTag` ( Object { type: "EndTag", tagName: "div" } ), instead saw `StartTag` ( Object { type: "StartTag", tagName: "p", attributes: [], selfClosing: false } ).

Content generated by `save` function:

<div class="wp-block-hello-tools-custom-cta"><div class="hello-custom-cta__blurb"></div></div>

Content retrieved from post body:

<div class="wp-block-hello-tools-custom-cta"><div class="hello-custom-cta__blurb"><p>Old version looks like this</p></div></div>

This is the deprecation code that I added:

deprecated: [
    {
        attributes: { 
            ...metadata.attributes, 
            blurb: {
                type: 'string',
                source: "html",
                multiline: "p",
                selector: ".hello-custom-cta__blurb"
            },
        },

        save( { props } ) {

            const blockProps = useBlockProps.save();
            const blurb = props.attributes.blurb;

            return (
                <div { ...blockProps }>
                    <RichText.Content 
                        className="hello-custom-cta__blurb" 
                        tagName="div" 
                        multiline="p"
                        value={ blurb } 
                    />       
                </div>
            )

        },

        migrate( attributes ) {

            const { blurb, ...otherAttributes } = attributes;

            const blurbElement = document.createElement( 'div' );
            blurbElement.classList.add('hello-custom-cta__blurb');
            blurbElement.innerHTML = blurb;

            const [ blurbBlock ] = rawHandler( { HTML: blurbElement.outerHTML } );

            return [
                { ...otherAttributes, ...blurbElement.attributes },
                blurbBlock.innerBlocks,
            ];

        },

    }
]

[talldan]

@kory-northrop It might be the rawHandler part that's failing for you. I think the list block is using this as a shortcut to get a block object from the raw html markup generated in the preceding code. It relies on this 'raw' transform:

gutenberg/packages/block-library/src/list/transforms.js

Lines 73 to 81 in 14e8390

	{
	type: 'raw',
	selector: 'ol,ul',
	schema: ( args ) => ( {
	ol: getListContentSchema( args ).ol,
	ul: getListContentSchema( args ).ul,
	} ),
	transform: createListBlockFromDOMElement,
	},

If your block doesn't have that, then it might not return the right data from rawHandler. If you inspect or log out the value of blurbBlock, what do you get?

[kory-northrop]

@talldan thanks for your comment. I am probably unnecessarily using rawHandler. I added a simple console.log() statement as the first line of code with the save() function and another in the migrate() function, but I only see the log message for save(). I'm assuming that's because the save() does not provide a valid deprecation for the block since this message is appearing in the console:

Block validation: Expected token of type `EndTag` ( Object { type: "EndTag", tagName: "div" } ), instead saw `StartTag` ( Object { type: "StartTag", tagName: "p", attributes: [], selfClosing: false } ).

[t-hamano]

@kory-northrop
I think this is a question, not an issue, so let's treat it as a discussion.

[t-hamano]

Content generated by `save` function:

<div class="wp-block-hello-tools-custom-cta"><div class="hello-custom-cta__blurb"></div></div>

From this message, it appears that the save() function is not generating the correct markup. Did you rewrite the save function using innerBlocks?

[kory-northrop]

@t-hamano, yes a new block works just fine, it's just the existing instances of the block that are not validating and migrating. I just responded to talldan above, it doesn't appear that the migrate() function is running, which I think is due to the error in the save().

[t-hamano]

If the migrate() function does not run, you may want to check to see if the definitions of attributes and save() match the old one.

[kory-northrop]

I've been trying to do this over and over and making no progress. I even built a new custom block that is the most simple example possible based on the Deprecation doumentation and I cannot get a migrate() function to work when changing the default value of an attribute.

[kory-northrop]

Just circling back to say this never got resolved and my team has held off updating Wordpress to 6.3.x because of it. Has anyone actually had success migrating a block that used RichText with a multiline property to utilize InnerBlocks instead?

[t-hamano]

I have been able to migrate RichText with multiline properties to InnerBlocks.

Is the migrate() function itself not running? Or is the migrate() function running but the conversion to InnerBlocks fails? I think you may need to identify which is the current situation.

[markusfinell]

I've created blocks that use multiple RichText components. But you can't use multiple InnerBlocks components. So what's the solution there?

[t-hamano]

Currently, one block can only have one InnerBlocks.
A solution would be to wrap each InnerBlocks with a child block as follows

• Main Block
  • Child Block 1
    • InnerBlocks
  • Child Block 2
    • InnerBlocks

[jg314]

Our team has spent about 10 hours modifying a custom block to migrate from the RichText multiline property to InnerBlocks and hasn't found an effective solution. Our goal was to transition from using RichText for adding multiple paragraphs to allowing InnerBlocks to include only Paragraph blocks inside our block. We're running into these issues:

• RichText includes the allowedFormats property which offers the ability to remove formatting options we don't want our users to have. For example, the parent custom block is linkable, so we don't want users to be able to add links inside each paragraph. This doesn't seem to be possible when using Paragraph blocks.
• We're restricting the InnerBlocks to only allow the Paragraph block, but the placeholder "Type / to choose a block" is still shown. That doesn't make sense because typing "/" doesn't do anything. We also want to customize this placeholder to make it more clear.

We've tried a number of options to fix this issue with no luck:

• We tried creating a custom block that mimics the Paragraph block, but includes our customizations. This requires a lot of code, and includes a lot of repetition with the existing Paragraph block. It's not as simple as just adding a RichText component inside the custom block. The Paragraph block has other functionality we want, such as that hitting the Enter key causes a new Paragraph block to be added. A custom block won't do this by default.
• We took a shot at trying to use existing block filters, but those also require a lot of duplicated code from the Paragraph block.

We're hoping we're missing something simple here, but we're struggling with how complex it has become to implement functionality we used to accomplish with the single multiline="p" line of code.

If anyone has ideas on how to solve this problem more simply, please let us know. We're very open to suggestions and input. Thanks.

[t-hamano]

Thank you for your comment.

RichText includes the allowedFormats property which offers the ability to remove formatting options we don't want our users to have. For example, the parent custom block is linkable, so we don't want users to be able to add links inside each paragraph. This doesn't seem to be possible when using Paragraph blocks.

I don't think it is currently possible to change the allowedFormats prop of a RichText component in a block that you did not develop. You may be able to submit an issue regarding this as a feature enhancement.

We're restricting the InnerBlocks to only allow the Paragraph block, but the placeholder "Type / to choose a block" is still shown. That doesn't make sense because typing "/" doesn't do anything. We also want to customize this placeholder to make it more clear.

If you want to change the placeholder of a paragraph block, you can specify the placeholder attribute in the InnerBlocks template.
However, if you can only insert paragraph blocks, the default placeholder is certainly unfriendly. Regarding this, I submitted #55378.

[jg314]

Thanks a ton for the response @t-hamano.

I don't think it is currently possible to change the allowedFormats prop of a RichText component in a block that you did not develop. You may be able to submit an issue regarding this as a feature enhancement.

We appreciate you confirming this. We thought it wasn't possible, but it's helpful to know that's the case.

If you want to change the placeholder of a paragraph block, you can specify the placeholder attribute in the InnerBlocks template.
However, if you can only insert paragraph blocks, the default placeholder is certainly unfriendly. Regarding this, I submitted #55378.

We really appreciate you creating an issue for this. It would certainly help with usability to be able to remove or modify the default placeholder. And for what it's worth, we are using the placeholder attribute within the InnerBlocks template. Unfortunately though, once you start adding and removing Paragraph blocks the initial paragraph can easily be deleted. That causes the default Paragraph block placeholder to appear again.