Provide a pathway to migrate widgets to block themes

[annezazu]

What problem does this address?

Currently, when switching from a classic theme to a block theme, widgets created in the classic theme aren't migrated over.

What is your proposed solution?

I could have sworn this was previously discussed, whether on a hallway hangout or in a core editor meeting, but I can't find any related issues so I decided to open this one up since this recently came up as a point of feedback. Since widgets "live" in the spaces that template parts fill, it makes the most sense for migration to happen in the form of generating template parts during migration:

• User has widgets in a classic theme.
• User switches to a block theme.
• Widget areas are converted to an equivalent template part with blocks (header, sidebar, etc). Anything already a block can remain as such and anything else could be converted to a legacy widget block thanks to the work done with the block widget editor.

If the user didn't want to use this, they could just ignore or delete the template part. If they switched back to a classic theme, it should preserve backwards compatibility. I don't know enough about the technical underpinnings here either way but wanted to get this documented regardless as it feels like a key area of refinement ahead of more folks adopting block themes in due time.

[mtias]

So I think you should be able to import an existing widget area content into a template part. We should probably place this in the block inspector for a template part as an "import", "use existing widget area" or "transform" action:

Considering widget areas can already have block content, this should be a fairly seamless transition. Once it's possible to use and edit template parts on non-block themes (#37943), this flow should be even more transparent.

[noisysocks]

I could have sworn this was previously discussed

It might have been privately with me! 😅 Let me copy and paste some notes that I wrote in July 2021 about this subject:

Using CPTs

• Hook into after_theme_switch. When we detect that user is moving from a classic theme to a block theme, or from a block theme to a classic theme, perform a migration.
• Migrating from a classic theme to a block theme: Grab all of the widget areas in the classic theme (sidebar-1, footer-1, etc.), create a template part with the same ID for each widget area, run widgetToBlock on each widget to create template part HTML.
• Migrating from a block theme to a classic theme: Grab all of the widget areas in the classic theme, find any template part with matching ID, run blockToWidget on each block to create widgets.
• Block widgets are turned directly into the block that's stored in it. Legacy widgets are turned into a core/legacy-widget block.
• The site editor can include legacy widget scripts if it detects the use of a core/legacy-widget block.
• In a classic theme, you do not see the site editor. In a block theme, you do not see Appearance → Widgets.

Pros

• Minimal changes required for the site editor.
• The site editor only has to know about template parts, which it already supports. (It's a "clean slate".)
• Migration, while finicky, is easy to write unit tests for.

Cons

• Running migration scripts on theme switch can be finicky. Need to ensure we create backups of data. Need to ensure we handle edge cases such as ID conflicts.
• Block themes will not have any notion of a "widget area". Plugins which add functionality to widget areas will no longer work.

Using widget areas

• Provide a Widget Area block in the site editor.
• In the frontend, the Widget Area block renders a single widget area by calling dynamic_sidebar().
• In the editor, the Widget Area block renders an InnerBlocks.
• The Widget Area block uses EntityProvider to save changes to a sidebar entity via the /wp/v2/widgets API added in 5.8.
• The Widgets screen can be refactored to use this Widget Area block as well as the multi-entity saving system. (This also fixes #32952.)
• Legacy widgets continue to work via the core/legacy-widget block.
• Block themes can support the Widgets editor at Appearance → Widgets if we want.

Pros

• Can have the standalone Widgets editor in block themes if we want. It's arguably a nicer interface than the standalone template editor.
• "Widget areas" continue to exist meaning plugins which use them and add functionality to them can continue to work.
• No finicky migration.

Cons

• Requires block theme authors to have to know about widget areas and template parts, even though both concepts are very similar (identical?).
• dynamic_sidebar() and its ilk are a mess :) No "clean slate" for block themes.

---

I lean towards the first approach because I feel it fits nicely with block themes and the site editor being a "fresh start" for WordPress that serves as a foundation for the next 15 years of growth. In the year 2030, do we want to be explaining to developers what a "widget" is? :)

But, this is all hypothetical. I think we should build a prototype of both approaches and see what happens.

[noisysocks]

We should probably place this in the block inspector for a template part as an "import", "use existing widget area" or "transform" action:

I like this idea of doing the migration on request as opposed to automatically on theme switch. It's more intentional—less surprises. Also, it caters for users who wish to ditch their existing widget areas and start fresh.

[carlomanf]

@noisysocks There are a few issues I see with the "Using CPTs" proposal:

• The migration will not run if the after_theme_switch hook doesn't fire for some reason (e.g. if the theme is switched using phpmyadmin)
• Currently, there is still no way to retrieve template parts from inactive block themes (see An equivalent to "Inactive Widgets" for template parts #31397) so the widget areas would only become available to block themes that are activated immediately in the wake of a classic theme, but not to block themes activated in the wake of another block theme, which seems silly.

I think @mtias suggestion of importing widget areas on request is far more preferable, and I believe it also mirrors the ability to import menus to the navigation block.

That said, the lack of a solution to #31397 could still cause confusion for users about why it's easier to import a "legacy" widget area than to import an inactive template part. No equivalent problem exists for the navigation block because navigations are not tied to themes.

#31971 still looks like a workable first step to solving #31397 but was closed due to the PHP code being moved from the experimental plugin into core.

[noisysocks]

Yeah, good call on #31397. I think it's another missing piece of the theme switching puzzle.

What makes sense to me right now is that both widget areas and template parts to stick around in the database after switching theme and for us to provide:

• For block themes, UI to import an old widget areas into a template part.
• For classic themes, UI to edit template parts in WP Admin and the ability to programatically render a template part (e.g. by calling render_template_part()).

[mtias]

@noisysocks the function for the last part already exists — themes can use block_template_part( $part ) already in PHP. It's just lacking a UI to edit them.

[mtias]

I'm bumping the priority of this for visibility.

[Mamaduka]

I just pushed my current progress for this feature #45509.