Research Notes About Building Full Site Editing Block Themes for WordPress

WordPress version 5.8 just came out last month (July 2021) and we’re now embarking on building an experimental FSE (Full Site Editing) theme called Proto. That’s short for “prototype” if you’re wondering how much thought went into naming… it was 14 minutes grand total if you really want to know.

One of the first interesting realizations after embarking on this journey is that the Gutenberg plugin is still relevant. I had thought since the merging of Gutenberg into WordPress core, the plugin was just irrelevant. That turned out to not be the case. Some of you reading this might actually face the same challenge I did, where I’m reading about multiple plans for FSE template building support but I can’t seem to activate them. The key is, for bleeding edge FSE support not yet in WP core, you need Gutenberg plugin activated. This combined with theme_supports() statements will enable the cutting edge template editing, storage and related features.

add_theme_support( 'full-site-editing' );

This line declares that your theme supports FSE and if you have Gutenberg plugin installed this will add two new submenu items under appearance, “Templates” and “Template Parts”.

We have lift-off on the FSE theme experiment, with the Gutenberg plugin activated and theme support added for “full-site-editing” we now get to see the elusive Template and Template Parts features.

A couple of related notes here, first the version of Gutenberg plugin at the time of this writing was 11.2.1 and the WP core version was 5.8. These features are of course being rapidly developed and subject to significant changes, so by the time you get around to building an FSE theme the options under Appearance for example may be titled differently or work differently. That being said the direction of FSE is reasonably stable in the sense that there are plans to continue developing support for the ability to edit all aspects of the site in the Gutenberg editor, which includes handling theme parts, setting templates using all the advanced FSE theme features that are emerging such as Block Patterns, Block Templates, Global Styles.

Shout out to https://fullsiteediting.com which has some great resources on this topic including a course, https://fullsiteediting.com/lessons/what-is-full-site-editing/

This is the official handbook at WordPress.org for block themes, https://developer.wordpress.org/block-editor/how-to-guides/themes/block-theme-overview/

After trying out the template editors (Templates/Template Parts) a question arose which is what is a template part in this context, how is a template part different from a template? The editing experience for both seems to be the same, the only notable difference is they are stored separately as different CPT (Custom Post Types).

Editing a template part and wondering what does this do then compared to templates? Is this just a different way of organizing templates?

A notable concern about this functionality is the lack of taxonomies. I would have expected a taxonomy for templates in order to provide categorization and possibly tagging. This would then let us keep headers and footers organized and separate from other templates for instance, and potentially handle them different during editing and rendering? Those are just thoughts at this point because it isn’t clear exactly how an FSE theme is going to handle loading and using templates anyway.

Below is the Templates list after publishing the first template, it’s designed to be a header and now I’m going to try to render it on the front-end.

A minor break-through after searching the installed blocks and realizing there is a “Template Part” block. Okay now I’m starting to see the differentiation between “Templates” and “Template Parts”. It looks like Template Parts can be used within this Template Part blocks and added to Templates or just used within any Gutenberg post… they could also be added to code-based Block Templates and Block Patterns…

Another interesting discovery is https://github.com/WordPress/theme-experiments WordPress Theme Experiments repo which has several examples of FSE themes with various approaches to styles and block templates.

With the initial experiments out of the way and the theme templates drafted the Site Editor (Beta) now shows up in the WP Admin. The good news is the site realizes the theme is FSE and provides Site Editor, the bad news is the Site Editor crashes during load with a React DOM error. Not sure why, but it’s likely some failure to meet a requirement in the theme structure. Heading over to Theme Experiments repo to get a recently update theme to see if there is an answer.

Found the solution thanks to the help of the community after posting the Site Editor crash a bug somebody recognized it might be a Firefox specific error, and sure enough that was it. Now switching to Chrome for further testing, the Firefox issue already has a fix underway that should rectify that in future versions.

After switching to Chrome to get around a Firefox specific bug, this is the Site Editor loading for the first time with Pronto installed and templates ready to edit.

After trying the Site Editor for the first time, and playing around with code edits in the theme templates followed by Site Editor edits… my head is now spinning as I try to digest this new approach to theme development and editing control. First though, this is going to really be a great evolution in terms of democratization of the web and it’s going to do exactly what has been advertised which is make theme development and editing much easier for non-coders. In fact the challenge it would seem in terms of making a theme, is deciding how to best support this editor-based workflow. What features should the theme actually provide, when the editor is doing so much.

How to Add a New Template Part to the Site Editor

First add the HTML template (copying an existing template) to the /block-template-parts directory. Then add the reference to the theme.json at the root of the theme.

Notes above presume you’ve got a fairly standard theme structure based on most existing FSE themes which have theme.json at the root, and then have a /block-template-parts/ directory. Presumably this directory structure can be customized if needed as long as the paths are referenced properly?

In theme.json the section to edit is “templateParts”. After adding “Header Fire” to the list Pronto’s template parts definition looked like this:

"templateParts": [
		{
			"name": "header",
			"area": "header"
		},
		{
			"name": "header-sticky",
			"area": "header"
		},
		{
			"name": "header-fire",
			"area": "header"
		},
		{
			"name": "footer",
			"area": "footer"
		},
		{
			"name": "product-content",
			"area": "uncategorized"
		}
	],

How Menu Editing Works in FSE

Wondering how navigation works in FSE? So am I! We have a “navigation block” but I’m not sure how we add items to it? Are menus now blocks? The regular menu editor is missing under “Appearances”, is that because it’s removed in FSE or because our draft theme doesn’t declare menu support? Answer me! This is like a tutorial in reverse… you come looking for answers, and you find questions.

The solution turned out to be simple, themes must still declare support for features like menu’s, so we added:

add_theme_support( 'menus' );

Once Proto supported menus we got the familiar menu editor at WP Admin > Appearances > Menus and after adding a menu, the Navigation Block had a button for selecting a menu to display!

Here is how our mildly customized header looks after adding a logo, adding the menu and removing a couple of the default blocks:

Navigation Block Has Big Issues

Although I’m very much sold on the future of FSE and Gutenberg, that doesn’t mean I’m going to ignore bad UX experiences which keep cropping up when using the block editor. It’s sometimes scary to think the future of WP rests on Gutenberg becoming the dominant editing experience, and in production we have major UX flaws that lead to a frustrating experience. Check out this screenshot of trying to edit the Navigation Block. See how the block context menu cleverly positions itself directly over top of the block so we can’t see it and have to dodge the context menu items to try to edit the block? Who designed this? Bring me their heads!

Gutenberg reminding me why Elementor is so at least a few years ahead. This is called a sucky editing experience, a context menu that should never cover the block rendering is completely covering it.

Presumably the issue there happens because the navigation block is near to the top of the Gutenberg editor, and the context menu isn’t smart enough to realize it’s sitting on top of the block. Normally the context editor would rise further north on the screen to sit above, but it can’t because the block is near the top of the editor. This seems like something you’d work on day 2 of building an editor to be honest, but here we are it’s 2021 and we’re pushing forward with making Gutenberg the de facto standard in editing, and frankly it still doesn’t have the basic capability to properly load context menus consistently.

Enabling Responsive Menu

The navigation block comes with a built-in responsiveness option! It’s simply a setting on the block.

Navigation Block options including “Enable responsive menu”.
Menu created by the Navigation Block showing in responsive mode. For some reason the hamburger seems to have 2 rows instead of the standard 3?

Using Revert Template During Theme Building

As work begins on creating useful and stylish templates an important question came up. How do we even see the changes in our theme templates, given we’ve already started editing the templates using the Site Editor which means changes to the theme templates are not even utilized? The answer is to revert the templates back to their unedited/original state which causes the editor to then load the current version from the theme file. This is interesting aspect of this FSE approach to theme building.

The revert/restore option is available from the title display part of the current template once loaded into the Site Editor. Now when we combine this with exporting, we end up with a very cool and friendly workflow that prevents us from having to write any code. In fact we might even say that we need to avoid writing code, unless we really want to learn to manually write the block format comment code. But why bother when we Gutenberg generates that code automatically when we drop in blocks, and we can export the entire template at any time?

Exporting Templates from the Site Editor

At any given point in time the Site Editor enables you to export everything which is then downloaded in a ZIP. What do you get? Everything and more! You get the entire set of templates, that’s the full page templates (Templates) and the partial templates (Template Parts). Combined, this is pretty much the entire theme… however the goal is not to have a theme you can install (apparently). Because what is missing is both the definition of the theme (style.css) and the now all-important theme.json. So this utility is super useful in the process of building, but it doesn’t create an exported theme you could install on a different site for instance. Maybe in the future it will, but on the other hand, it’s hard to say if that would be an improvement or just a complication. Because as it stands now, we can make whatever changes we want to our templates, export them, then move the files from the export folder back into the theme. This combined with the revert edited templates mention in the previous section makes custom template creation a breeze, it’s a fully visual experience with no coding required.

Creating a Split View Layout

You know what they say, the best way to learn to swim is to drown in the ocean. That’s why we’re making a split view layout which almost immediately flies in the face of what might be the more natural flow of Gutenberg content. The theme we’re modelling for this is called Uppercase, shout out to the makers of Uppercase for their very popular theme available over at ThemeForest.

One of several demo sites from the popular UPPERCASE theme sold on ThemeForest. It features a sort of split view, where the header is the left side and the content scrolls on the right. It’s an interesting challenge to build this into Gutenberg as an FSE theme.

After a bit of playing around in the Gutenberg editor starting with columns and a Cover Block we reached this initial point:

The split view is there… no custom CSS was used aside from adding the most basic body { margin: 0 } to clear the margins. Aside from that it’s fully Gutenberg block editor content. The most challenging part of this was getting the alignment (which still needs work actually) arranged. The Cover Block by default likes to center/center everything using flex, but we were able to get the logo and navigation bar aligned top. Why the navigation won’t align right is a mystery we will never solve. Well, maybe we will solve it… someday (tomorrow).

The content on the right is a Query Block. We’ll tackle styling that later on and probably give some thought to shipping something in our theme to support a view that looks like our model theme UPPERCASE.

How to Load Fonts in an FSE Theme

@TODO This section coming soon as we look at font loading and support. This topic isn’t really specific to FSE themes, but there are some unique considerations including how to give site users the options of which fonts to load, and also how to integrate the loaded fonts with the FSE theme.json global styles so that the fonts become available throughout the Gutenberg editor.

The fastest way to get started with loading custom themes is to use Google Font import statements in the theme stylesheet. Notice I didn’t say best way, this is just the fastest way. Next you’ll need to add each new font family imported to the theme.json fontFamily array under the “typography” section.

"typography": {
			"fontFamilies": [
				{
					"fontFamily": "Inter, sans-serif",
					"name": "Inter",
					"slug": "inter"
				},
				{
					"fontFamily": "\"Work Sans\", sans-serif",
					"name": "Work Sans",
					"slug": "work-sans"
				},

Making the Inner Content Part of the Cover Block Full Width

Strangely I could not find a way to make the inner block part of the cover block expand to full width. Instead “width: auto” was firmly baked into the styles, and it took a custom CSS class and this monstrous CSS declaration to create the full-width inner content area we needed to get our menu aligned to the right of the cover area:

.wp-block-cover.full-width-cover-block.has-custom-content-position.has-custom-content-position .wp-block-cover__inner-container {
	width: 100%;
}

The class name added was just “full-width-cover-block” but to be specific enough to target the inner content it has to be chained with the existing properties. Quite possibly in the future the Cover Block can have a new attribute option to make the contents full width.

Customizing the Query Loop Post Template

The new Query Loop block is a modern marvel. Arguably the most powerful block ever created and now available in WP v5.8, this block contains within it a Post Template Block.

One way to edit the Post Template is to do so directly when using the Query Loop block. We can insert a Columns Block to create a multiple column layout for example. I like using the List View in Gutenberg for this because after inserting the Columns Block, we can then drag the various inner blocks into the columns.

Putting the inner blocks from the Post Template into 2-columns using List View in the Gutenberg Editor.

After that customization to the Post Template we end up with a much nicer list of blog posts. I like this style, it puts a lot of focus on each post without the distraction of a multiple column grid. And by using 2 columns as the layout the images are scaled down a thumbnail and there is plenty of room for the title, except and read more links. This was a 30/70 column split.

Customized Post Template Block with a 30/70 two column layout.

Similar Posts

Leave a Reply

Your email address will not be published. Required fields are marked *