My experience trying to adapt a theme to Full Site Editing

[Jeremy-Bolella]

Howdy, I've been through the wringer trying to adapt FSE for my current theming system and I just about hit the point of giving up on this new system. To preface, I mostly work with custom themes that are not publicly distributed and each site gets a full custom treatment. For the last several months I've been leaning on the Gutenberg block system instead of relying on ACF/Custom templates. This has been a huge game changer being able to give clients a playground of blocks and letting them go to town on their own. It's a time saver and the DX of leveraging Gutenberg blocks just feels so much nicer compared to using ACF and custom themes. My last two sites were almost entirely built out as gutenberg blocks and each template file just returned the content of that page.

After finishing the last site I dived into figuring out FSE so I can be fully onboard with where Gutenberg is going. Thinking my last site was almost completely blocked out as it is, I'll just have to adapt the new theme layout and refresh my source files. After getting through refactoring my base theme I felt so good. Less files, deeply integrated styling from my sass files without having to touch theme.json. It was all big wins until I got into templating. I tried to dig as much as I could to get a good understanding of why this system is the way it is and I am no expert in the inner-workings of Gutenberg but I tried to be as knowledgeable as I could before writing out these opinions below.

1. Only allowing .html files with no easily integrated templating system or PHP in general is a jarring change of pace

This one I did a ton of digging on and I have a decent understanding of why this system is the way it is. Preventing theme lock in, removing the php dynamic render process, etc. But this is a huge issue that multiple other issues have mentioned and discussed with multiple alternatives to improve this issue even if PHP rendering isn't feasible. I'm just confused on why it's so locked down when countless plugins have been doing this for years: ACF blocks, Genesis Blocks, MB Blocks (even if that is just at the block level). (not to mention the countless page builders that allow php at multiple places in their systems)

I understand that the templates in this system have to be directly Gutenberg renderable and wrapped in the proper syntax but not providing any utility to interface with the template system in an easy way outside of html files doesn't feel very WordPress like at all. When a template doesn't match the .html structure it's immediately kicked out of the FSE templating system. To me that is a deal-breaking issue, I wouldn't expect myself to know two different systems let alone my clients.

2. Exposing the commented block system directly to developers as the only base templating option

<!-- wp:group {"layout":{"inherit":true}} -->
<div class="wp-block-group"><!-- wp:group {"align":"wide","style":{"spacing":{"padding":{"bottom":"var(--wp--custom--spacing--large, 8rem)","top":"var(--wp--custom--spacing--small, 1.25rem)"}}},"layout":{"type":"flex","justifyContent":"space-between"}} -->
<div class="wp-block-group alignwide" style="padding-top:var(--wp--custom--spacing--small, 1.25rem);padding-bottom:var(--wp--custom--spacing--large, 8rem)"><!-- wp:group {"layout":{"type":"flex"}} -->
<div class="wp-block-group"><!-- wp:site-logo {"width":64} /-->

<!-- wp:site-title {"style":{"typography":{"fontStyle":"italic","fontWeight":"400"}}} /--></div>
<!-- /wp:group -->

<!-- wp:navigation {"layout":{"type":"flex","setCascadingProperties":true,"justifyContent":"right"}} -->
<!-- wp:page-list {"isNavigationChild":true,"showSubmenuIcon":true,"openSubmenusOnClick":false} /-->
<!-- /wp:navigation --></div>
<!-- /wp:group --></div>
<!-- /wp:group -->

Taken right from the TwentyTwentyTwo theme. To me this is the number one deal breaker and why I cannot bring the FSE system back to my team. There's nothing about this layout that is easily readable or understandable from a development perspective. It's not standard syntax of any system, comments are not supposed to be structural with data. There's no linting or easy references to where variables come from and this code isn't DRY! In a system that a majority of the internet uses we're all gonna have to define our styles in two places?

There's been a bunch of suggestions even down to leveraging XML and I know there's the builtin array templating system but if this was the direction WP was heading in I would leverage Web components that can dump out the frontend renders automatically at save time. Or something along those lines to make the DX feel better than it is currently.

<wp-group layout="{inherit: true}">
  <wp-group align="wide" wp-styes="...">
     <wp-group>
       <wp-site-logo wp-styles="..." /></wp-site-logo>
       <wp-site-title wp-styles="..."></wp-site-title>
     </wp-group> 
    <wp-navigation layout="{"type":"flex","setCascadingProperties":true,"justifyContent":"right"}">
    </wp-navigation>
  </wp-group>
</wp-group>

<!-- possible basic custom block example -->
<wp-block src="/dist/js/custom-block.js">
</wp-block>

<!-- static block -->
<wp-block>
  <p>Hello World!</p>
</wp>

<!-- possible PHP block abstraction -->
<wp-php-block>
  <?php the_title(); ?>
</wp-php-block>

The above syntax isn't anything concrete at all but at a glance it's much more readable. There's no random divs tagged against an even longer html comment and structure is easier to see even if it still has the same con of not knowing the full rendered structure (which is a con in the first example as well). But web components offer a very strong advantage compared to xml or other options brought up. They are extendable! A custom block could be easily extended by a base gutenberg-block that has all the required functionalities built-in to function in the gutenberg system but give the flexibility of rendering statically/dynamically. With the added benefit that theme builders can leverage multiple "hooks" of being able to adjust the blocks/template as needed like the classic theme system.

To me the FSE system is boxing in developers with all the cons of going headless without any of the benefits and that's why I decided I cannot leverage this system currently. I was already essentially leveraging FSE in my old system but this paradigm shift with rigid html templating seems like the wrong direction and ultimately destroys the DX experience of wordpress developers especially if this takes over the classic theming system.

[LukaszJaro]

Nice writeup! I also love Gutenberg, great replacement for many things as you mentioned, it was very much needed in core.

I'm building my first FSE theme and also felt like I was in some alternative world, such a change from using PHP.

Carolina Nymark resources on full site editing have been indispensable, in your case about the PHP templates, she explains very good way of doing it while still keeping things consistent using block markup:

https://fullsiteediting.com/lessons/how-to-use-php-templates-in-block-themes/

The block markup comments are definitely weird and difficult to weird but I'm not normally editing the actual html files. I found the best way is to build the UI visually in the block editor and then copy it to the html templates.

Some other things I ran into:

• I lost my template customizations accidentally and I was unable to retrieve them since there is no template revision system and as I mentioned I will not attempt to build the templates with the html markup comment system(although that would provide better save functionality and git history)
• The responsive menu icon can not be changed to use a different icon, nor can the there be a icon + text combo (this will probably not be difficult to address)
• I tried a few plugins I use commonly like Polylang and it did not fully work with FSE, basically it was unusable. The author has only added FSE functionality in the paid version so that was very disappointing. Relevanssi also did not work unless you added a filter to functions.php which was provided by the theme author. These are only a few plugins I tried, I don't know what further surprises will come up with other plugins.

I don't normally work with clients who are editing the header/footer, so really FSE is for me and how much I can leverage it. It does make things more organized and reduces alot of custom functionality that I had to previously add. I'm also trying to leverage theme.json as much as possible but some styles still need separate stylesheets. I strongly recommended using "$schema": "https://schemas.wp.org/trunk/theme.json", for them.json that way when you type "" it will show you what options are possible and validate things!

Overall FSE is better than using PHP templates, just look at classic theme templates and how complicated they are scattered with hooks, if/else statements and what not. Some rigidity is traded for simplicity and consistency.

[catkit]

Hi @Jeremy-Bolella

I'm in the same situation as you, I'm not a theme builder, I'm a site builder and I think we're not in the radar of decision makers. I decided to create a Blockbase child theme for my client and I'm now founding myself creating patterns instead of template parts so I can add dynamic content. Unlike you, I'm not as knowledgeable as I could, but the decision behind making patterns php files whereas template files are html doesn't make any sense to me.

Carolina Nymark resources on full site editing have been indispensable, in your case about the PHP templates, she explains very good way of doing it while still keeping things consistent using block markup:

https://fullsiteediting.com/lessons/how-to-use-php-templates-in-block-themes/

@LukaszJaro it would be a solution if it didn't depend on the do_blocks() function which has a bug since February that hasn't been touched yet.

[zimaben]

I'm not sure who reads these, but fourthed on being a developer that does custom sites to spec and was all in on Blocks, tried one client site on FSE, and is now back to headers/footers being delivered via PHP with blocks/patterns handling the rest.

There are currently just too many land-mines in FSE that would take 5 minutes server-side and take half a day in FSE (I spent probably 4 hours trying to figure out how to put a simple copyright notice inside a hamburger nav...ended up giving up and injecting it via css pseudos having no real options.)

I get the html comments system, and I think it solves a lot of problems with the data model and backwards-compatibility, but it's still not there yet. It's too developer-driven to be a competitive page builder but too inflexible to turn in a custom build from design files on a deadline.

Getting really close though.

[certainlyakey]

@Jeremy-Bolella you've mentioned you switched away from ACF to Gutenberg blocks, how do you register them and what do you use to provide content fields for editing those blocks?

I've been using ACF to create custom fields in blocks, how do you deal with this aspect?

[Der-Alex]

It's 2024 and I am facing the same problems as the others stated. The last WordPress site that I built is about 4 years ago. It was built with Timber and ACF. It felt kind of natural. The only 'pain' was maintaining the content the old way. The new FSE is good but it feels really weird, when you are facing "edge cases". Currently I am working on a new customer project and here the current main issue is that we cannot simply build the navigation with a mega menu. The only way I saw to build this, is to use the wp:navigation, give it a custom class name and fiddle around in custom js and css files until it looks and behaves like the predefined design. On the other hand it doesn't look like that when you are inside of the FSE. This and other things we are facing right now still feel unnatural. But maybe this is the way to go and we just have to get used to it...