Gutenberg: Clearly articulate required changes for migrating existing themes into themes using full-site editing

[skorasaurus]

As discussed in https://wordpress.slack.com/archives/C015GUFFC00/p1595959225195300 ;
several of us (cc @tomjn @pattonwebz ) are not aware of the required changes to migrate or adapt existing themes to use full site editing; these should be articulated clearly if they are already known. ( cc @kjellr )

One decision that caught me (and others off guard) is that
once full-site editing is enabled, all php templates are ignored and the theme developer will need to migrate every template at once into a block based theme template.

At the very least, this point needs to be documented and clearly articulated for theme developers.

Not to mention, I'd strongly hope for the ability to use both (php templates and block based html templates) would still be possible.

We are still occasionally using the classic editor for some content (particularly for custom post types) for their post_content and I greatly appreciate this as I occasionally judge whether the block-editor is a better tool (as well my skills with React) than the status quo for these post types.

For starters, several page templates that are more complicated with things like multiple loops, fetching data (and then displaying that content) from 3rd party APIs via JSON or from separate MYSQL databases; which doesn't seem quite yet feasible within the block editor.

related: https://github.com/WordPress/gutenberg/issues/10764

[tomjn]

I think a lot of confusion and misunderstandings can be cleared up with a few simple statements about FSE. I might be wrong but my understanding is that:

• Templates in FSE are posts
  
  
  
  • There are template posts, and template part posts
  
  
• Template files in the theme are just presets used to create posts
• Template files are just HTML, specifically post content. They aren't equivalents of TWIG or PHP templates, they're just post content, specifically blocks
• The template hierarchy still applies:
  
  
  
  • use the template post
  
  
  • if it doesn't exist use content from the child theme HTML
  
  
  • if it doesn't exist, use the child theme PHP file
  
  
  • if it doesn't exist use content from the parent theme HTML
  
  
  • if it doesn't exist, use the parent theme PHP file
  
  
• A block based theme doesn't need to define any templates or template parts in HTML, afterall they're just presets
  
  
  
  • without these presets though the user experience of activating a new theme involves them constructing the header and post loop from scratch in the FSE interface
  
  

---

I would also note there are some more general block related items mentioned:

We are still occasionally using the classic editor for some content (particularly for custom post types) for their post_content and I greatly appreciate this as I occasionally judge whether the block-editor is a better tool (as well my skills with React) than the status quo for these post types.

Post content is still post content, I don't see how this is relevant to FSE. It changes how the_content() gets called but that's a sidestep. It does however mean the concept of page templates aren't necessary for the future where templates and template parts can be used instead.

(as well my skills with React)

You can build blocks that render in PHP, and blocks that don't use React. React skills are helpful but not necessary.

For starters, several page templates that are more complicated with things like multiple loops, fetching data (and then displaying that content) from 3rd party APIs via JSON or from separate MYSQL databases; which doesn't seem quite yet feasible within the block editor.

Multiple loops appear to be possible already with the query and query loop blocks. Or they could be implemented as blocks. Doing it as blocks would allow them to be inserted in both pages with templates, and pages that use FSE. You don't need to use FSE to take advantage of that methodology.

fetching data (and then displaying that content) from 3rd party APIs via JSON

This is bad practice, it doesn't matter if you use the classic or block editor, you don't make requests in PHP on the frontend to fetch data from APIs, it has awful performance. Do this on a cron job and store the result, or, do it in a REST API request.

But if you still wanted to do this despite the major downsides, it's still doable via a PHP rendered block. Likewise interacting with remote databases, just use a dynamically rendered block in PHP. It's the same paradigm as using a shortcode.

One decision that caught me (and others off guard) is that
once full-site editing is enabled, all php templates are ignored and the theme developer will need to migrate every template at once into a block based theme template.

I would consider this a bug, it does not appear to be intended.

[pattonwebz]

Just wanting to note that my specific request/questions here are quite simple:

1. How can a theme be made that has new style block templates thta co-exist with original style php templates.

Nobody wants to be forced to migrate all their templates in one go and I can see that some people will want to keep both template styles for a very long time. For example someone could want a block based front-page template but keep their php based single template. I actually believe that most users will want to keep all of their static templates as php ones and not migrate them to block templates (things like category, archive etc I see no value in migrating).

[youknowriad]

I second what @tomjn just shared here with a small correction;

Template files in the theme are just presets used to create posts

They are not just presets because if you don't "edit" the templates, the files are actually used to render the pages on the frontend. Or put differently, we don't save new templates when switching themes we just rely on the files.

---

That said, things are still in flux and this why things are not documented properly yet.

[tomjn]

Would it make more sense to say fallbacks than presets then? Or placeholders?

[youknowriad]

Yes, fallbacks make sense 👍

[jffng]

The template hierarchy still applies:
use the template post
if it doesn't exist use content from the child theme HTML
if it doesn't exist, use the child theme PHP file
if it doesn't exist use content from the parent theme HTML
if it doesn't exist, use the parent theme PHP file

Could we alter the FSE template resolution logic to account for this, so that existing theme templates could be used in tandem with block-based templates? cc @epiqueras

If so, we'd need to consider how the site editor functions on pages whose underlying template is not block-based.

[epiqueras]

We could, but that could lead to really weird outputs when a site has a few block templates lying around from a theme switch.

[pattonwebz]

With the current situation there is already unexpected outputs (namely only index.html) when there is no fallback taken into account :)

[tomjn]

Not supporting PHP templates is going to be a nonstarter and deal breaker
to the vast majority of the community. It’s a big enough deal breaker to
kill off FSE. The migration path without this would be cruel and painful,
and raises the barrier to entry super high.

[youknowriad]

I don't have a strong opinion personally but I think there's an important aspect that is missed here. What happens to the Site Editor when the site is composed of block-based templates and regular php templates. It becomes almost impossible to show anything meaningful for the user there which reduces the value of FSE as the whole point is about being able to edit everything visually.

[epiqueras]

Exactly.

With the current situation there is already unexpected outputs (namely only index.html) when there is no fallback taken into account :)

An empty block template could be loaded instead.

[pattonwebz]

What happens when developers decide it is too much work to migrate to FSE and do not bother to build themes with FSE in mind? Maybe their users will go elsewhere or maybe the pool of choices for the end users will wind up being so small the user decides to use a different tool.

An empty block template being loaded instead is not sufficient.

[skorasaurus]

Thanks all for the discussion and clarifications; in particularly for @pattonwebz for more concisely articulating my question than I did.

This is bad practice, it doesn't matter if you use the classic or block editor, you don't make requests in PHP on the frontend to fetch data from APIs, it has awful performance. Do this on a cron job and store the result, or, do it in a REST API request.

Thank you for the advice; I do use a REST API request via custom JS script in my theme; nevertheless (the poor php performance) is good to know about.

[pattonwebz]

It becomes almost impossible to show anything meaningful for the user there which reduces the value of FSE as the whole point is about being able to edit everything visually.

If this is the whole point then you should make FSE work within existing templates instead of enforcing that they must build brand new templates in an unfamiliar way. FSE is not a _wipe it all away_ feature - It is supposed to enhance what the block editor offers.

[tomjn]

I don't have a strong opinion personally but I think there's an important aspect that is missed here. What happens to the Site Editor when the site is composed of block-based templates and regular php templates. It becomes almost impossible to show anything meaningful for the user there which reduces the value of FSE as the whole point is about being able to edit everything visually.

I advocate embrace and extend, being strict in order to be ideologically pure is nice but it ignores reality. I don't recommend encouraging mixing PHP template support as anything more than a migration path.

It's a given that if your theme is a hybrid of PHP template files, and FSE style template parts, that you won't be able to edit the entire UI in FSE, that just seems obvious.

If I can use both block templates and PHP templates however, then I can remove them 1 at a time and replace with FSE style templates. I can start with a new section of the site build and use it to showcase FSE.

Otherwise, I'm forced to rebuild my theme and all my clients themes from scratch for FSE, and very few clients will pay for that. I'm not going to update my plugins as a result, I can't get client funding to make them FSE compatible, and I can't encourage others to use FSE by making the tooling easier as a result. It's a negative feedback cycle that doesn't need to exist.

An empty block template could be loaded instead.

If a block template references a PHP template that does not exist, it should not attempt to load it and display nothing. It can then report the issue in the editor.

However, I don't believe this scenario is possible, afterall a template is tied to a theme, if you change themes that template post is no longer being used, so I struggle to think of a scenario outside of theme development that would cause this.

I also don't expect the inverse to be true, any PHP template that tries to load a template part that doesn't exist in PHP should load the post equivalent, failing that the HTML equivalent. If none of those are available then we're in a situation that already happens in WP, and can be demonstrated by adding this code to the default themes header.php:

get_template_part( "the quick brown fox jumps over the lazy dog" );

That behaviour is already defined and has been for at least a decade.

[tomjn]

I think it's important to think of how template parts from old themes fit into this new world, even if they're second class citizens destined to go away. There are a lot of possibilities and paths to take.

For example, one idea might be to annotate PHP template parts as a form of blocks the same way there's a classic widget block. Allowing a theme to register them with options that are provided using the recently added get_template_part parameters, with the eventual intention that the PHP template part dissapears behind a common block interface. Eventually the implementation gets replaced with a pure block implementation either in JS or usiing dynamic server rendered content.

Another example is providing a simplified component that maps to get_template_part and other high level theme functions, so that blocks can be built that rely on them

Another example could be a PHP Template Part block that accepts the same parameters as get_template_part

---

With one or several of these, or another idea, a theme can use FSE without needing any block templates, providing an experience that's enhanced further by using native blocks. Rather than FSE being a complete replacement, it takes FSE and drills tendrils down into what we already have, reframing it and enhancing, drawing users and developers in.

Imagine if everybody can use some form of FSE from day 1 without having to spend their day assembling their sites layout from scratch, or if it took a developer an hour or two to get a midway version of FSE up to demo to clients for a proper migration?

[pattonwebz]

I like a lot of the suggestions that @tomjn is providing here. I don't know what the right solution is but - with insight into the theme ecosystem and access to speak directly with many theme developers - I know the wrong solution is to do nothing.

Day 1 access to FSE for as many people as possible feel to me like the only way that it gets enough buyin to be feasable this year.

[epiqueras]

If a block template references a PHP template that does not exist, it should not attempt to load it and display nothing. It can then report the issue in the editor.

Block templates shouldn't reference PHP templates. That's kind of backward.

My original idea was for PHP templates to act as a fallback if used with block templates. The site editor can show a preview and provide an option to overwrite it with a block template. Does that resolve all your concerns?

[tomjn]

My original idea was for PHP templates to act as a fallback if used with block templates. The site editor can show a preview and provide an option to overwrite it with a block template. Does that resolve all your concerns?

That was my thought too, but I thought it worth addressing that situation before explaining why it couldn't occur

[noahtallen]

The site editor can show a preview and provide an option to overwrite it with a block template

This sounds like a pretty interesting approach. I think wonder what it would take to create a "php -> blocks" template converter, maybe just by trying to detect if we can switch out things like the_content() for the post content block. I could see that been difficult and buggy, though.

Overwriting the preview with a blank slate could be useful to devs, but maybe confusing to end-users. 🤔

[noahtallen]

Bringing the conversation back to this point quickly:

several of us are not aware of the required changes to migrate or adapt existing themes to use full site editing; these should be articulated clearly if they are already known.

This is 100% a valid concern to have. I think the issue currently is that many of these things are not yet "already known!" So it's difficult to come up with a step-by-step guide to converting a theme to support FSE when we are still iterating, changing, and (hopefully) improving how it works. I think the basic block-template hierarchy approach is pretty solid (as discussed above), but other things might not be yet. So these kinds of concerns (i.e. "how do existing php templates interop with block templates") are very good to bring up, so that they can be used to inform what we are working on.

[skorasaurus]

To follow up and summarize this to more actionable items; there's two action items/requests here that @tomjn @pattonwebz and I have articulated; please correct if I missing something:

1a] Allow 'original style' php templates to coexist in a theme.
For example, allow a theme to use both archives.php but the frontpage/home page is written as a block template.
I think this is covered by #24803

1b] Provide a fallback mechanism so that if 'archives' block template exists, then archives.php will not be used.
(ref 2020-08-19 core-editor meeting https://wordpress.slack.com/archives/C02QB2JS7/p1597849265358200)
update: issue created for this - #24834

2] Document the changes (mostly 1a) for migrating existing themes into themes that utilize FSE and effectively communicate them to theme developers.
Let's leave this issue open for point 2, to ensure that documentation is written for it?

(issue needs documentation tag)

[pattonwebz]

@skorasaurus that all sounds correct to me :+1: