[Block Themes] Consider an FSE-compatible approach to starter content

[kjellr]

The legacy way of providing starter content for themes relied on users visiting the customizer after a fresh install:

Starter content is applied and displayed upon entering the customizer, with no changes appearing on the live site until customizer changes are explicitly saved and published.

Gutenberg currently hides the Customizer, so that's not possible for block themes. For Twenty Twenty-Two (WordPress/twentytwentytwo#116), I'd like to at least have us set a static homepage on a fresh install of the theme, but there's no FSE-based way of making that happen.

How can we make that happen? And beyond that, the previous way of entering starter content relied on a bunch of post markup sitting inside of PHP. Is there a way we can improve that now that we're working with HTML templates?

[noisysocks]

Thinking about this... it's a tricky problem, excuse the rough notes! 😅

This is how starter content works currently:

• If the fresh_site option is set then we import a bunch of fake posts, widgets, menus into the current Customizer changeset on after_theme_setup.
• This appears in the Customizer because the Customizer will use the current URL to determine which templates to render. For example if the URL being customised is / then the page with slug home will appear.
• Modifying the database in any way (e.g. publishing a post) will unset the fresh_site option.

But full site editing is different:

• There are no changesets. What you see in the Site Editor is the published content that comes back via the REST API.
  • We do, however, have local changes made to WordPress entities that exist in memory (@wordpress/data).
• Users pick a template or template part to edit. It's not automatic. You can, for example, edit the index or page-home template but the Site Editor won't choose one for you based on the URL being /.
• There's no real need for fake widgets and menus, just fake posts and perhaps template parts (e.g. to fake a navigation).

Perhaps we can set up a system where the theme can define a set of fake entities that the block editor loads into @wordpress/data after initialisation. I'm not sure how to have the Site Editor display the home page by default, though.

I'm also not sure if it will be confusing that starter content looks exactly like real content except for that it disappears when you make a change and doesn't appear in the site's frontend. I suppose we already have this problem. Still, this is a good opportunity to figure out if there is a better way to solve the problem that starter content solves.

[noisysocks]

Is there something minimal we can do here for WP 5.9? cc. @WordPress/gutenberg-core

[kjellr]

For what it's worth, I believe the theme will have to ship with traditional starter content to power its Theme Showcase preview (unless we change the way that works too, but that seems like a stretch). So the issue is specifically that we don't have a way to preview/activate that content since there's no Customizer.

[Mamaduka]

I think I've POC for this feature. I'll push it shortly.

[Mamaduka]

@kjellr, Customizer will be available for block themes in 5.9. See #36168.

It gives us the way to use traditional starter content that works with Theme Showcase. Plus time to build a better API for block-based starter content for the next release.

[kjellr]

Thanks — While that does theoretically help with the issue, I noted over in #36168 (comment) that I think we should push for something better.

[Mamaduka]

Thanks for commenting on the other PR, @kjellr.

I also would prefer to better/native API for handling block themes starter content. But I don't think there's enough time left until the feature freeze to land something like this.

[noisysocks]

Since there is strong opposition to always showing the Customize link I will revert #36168 and allow this issue to be addressed after the feature freeze date next week in time for 5.9 beta 1.

[helen]

👋 Just want to make myself available for questions/rubberducking if you need, since I was behind the original drive to starter content as well as the integration with theme directory previews last year.

Ignoring the theme directory part for a moment, I do rather wonder if the whole "fresh site" concept isn't really relevant in this paradigm - maybe it's more like full page patterns that you can experiment with, either within a content area or for a full template?

The directory preview probably needs to become something that can actually display all the different patterns, both theme-specific and from the directory, within the context of the theme, in addition to "idealized" combinations of content. That is definitely a bit of a stretch, but we made the whole thing work in a matter of a couple weeks last year including a manual review of every enabled theme's preview, so never say never :)

[noisysocks]

I think as far as WP 5.9 goes we can bump this in favour of WordPress/twentytwentytwo#243. We should continue to work on alternatives to starter content for future releases though.

[kjellr]

That makes sense to me too. I think we’ve got it covered for now in WordPress/twentytwentytwo#243.

[mtias]

One interesting aspect of patterns and templates is that starter content becomes a lot more flexible. They can be starting points for new pages or new templates at any point, not just an initial install as a whole.

I think templates should also be embraced more as providers of starting points. We should be seeing themes with opinionated home.html templates, given it's now trivial (or at least easier) for a user to change them, or choose a different pattern if they don't want something. Before a theme had to be careful since the user couldn't do modifications to home.php as easily.

[jameskoster]

On that note, I shared some initial ideas for surfacing patterns whilst template editing here, but I agree this area is ripe for more exploration.