Migration path for widgets to blocks for plugin and theme authors

[draganescu]

As one of the goals of introducing blocks to widget areas is to create a kind of stepping stone for block based themes adoption and classic theme migration, a mechanism that is aimed at moving away from widgets should be provided. Therefore I propose that we:

Implement a way for plugins to convert the widgets they provide to alternative blocks they recommend.

Mechanism description:

1. The LegacyWidget block should offer a "Convert to blocks" button, similar to the one that the ClassicEditor block provides.
2. The LegacyWidget block "Convert to blocks" button only appears if the widget has a specified migration plan.
3. A migration plan is a setting defined at registration time for a widget (a new method for WP_Widget and a new argument for wp_register_sidebar_widget)
4. Any widget (both multi widgets or function widgets) should be updated to get at registration time the block name that it should be migrated to, and a mapping array between widget settings and block attributes.

That is all plugins should do: update their register_widget and wp_register_sidebar_widget calls withe migration path, then the system should automatically provide the conversion mechanism.

As an extra feature, plugins should also be able to specify if they want a widget to be converted to a "best approximation". The best approximation conversion effectively turns the rendered widget html to blocks. The usefulness of this is debatable, but users may want to opt out of a widgets' functionality while keeping the content they created.

Core should be the 1st to implement this migration strategy and provide the block migration plan for all core widgets that already have block equivalents.

In the future this mechanism can be used for a one way import of widget areas into template parts for a block based theme.

[noisysocks]

This already exists via block transforms. If a plugin sets WP_Widget::show_in_rest_api to true on their widget then they can add a new block and write a block transform that converts a core/legacy-widget into that block by accessing the widget settings from block.attributes.instance.raw. Users can then transform the Legacy Widget block into a regular block via the regular block transforms flow.

This has already been done for all core widgets that have a block equivalent:

https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/legacy-widget/transforms.js

So, I don't think any development work is required here.

We definitely need to document the steps I described above, though, so that third party plugin developers have an easy to follow guide.

Perhaps also the UI should be more prominent? We could e.g. display a "Convert to blocks" button in the toolbar when we see that a block transform exists from core/legacy-widget. What do you think @critterverse?

[draganescu]

Ha, indeed, should have checked and yes block transforms is the better approach than patching widget registration, doh!.
I wonder if the best approximation conversion which effectively turns the rendered widget html to blocks is a valid use case and worthy of developing initially?

I'll split a documentation task from this issue around transforming plugin provided widgets to blocks.

UI wise, I believe the transform menu to be a very power-user thing.

[noisysocks]

I'll split a documentation task from this issue around transforming plugin provided widgets to blocks.

It's an item in #25759. But maybe seperate issues would be better instead of one big issue with checkboxes.

UI wise, I believe the transform menu to be a very power-user thing.

Yes I don't think this bit of the UI is as prominent as it needs to be. (Even you missed it! 😛) A "Convert to blocks" button on every Legacy Widget block makes sense to me.

[noisysocks]

Closing this as we have:

• Blocks transforms which allow converting a Legacy Widget into a regular block.
• Legacy Widget: Add "Convert to blocks" button #25100 which tracks adding a 'Convert to blocks' button to Legacy Widget when the widget is a text widget.
• A note to write documentation on this in Add technical documentation #25759.