Full Site Editing
With WordPress

Estimated reading time: 12 minutes

-Did you know that you can add almost every full site editing feature to your classic theme and still use PHP templates? The only two features not available to classic themes are the site editor and the global styles interface. You can add template editing to the theme and still keep widgets and the customizer.

This article is an overview of options for adding full site editing features to classic themes.
I bring up the benefits and potential problems with adding block styles and theme.json to classic and existing themes.

Should we stop developing classic themes?

With the addition of full site editing features starting in WordPress 5.9, theme developers are asking themselves if they should stop developing classic themes.
The answer to this question is individual and depends on many factors. -My advice is to switch to full site editing themes when it benefits you and your business.
Take the time to learn about full site editing and its limitations, and then make a decision.

There are several options for adding full site editing features to classic themes, making them hybrid themes -a bridge between classic themes and block themes.

Should we update or retire existing themes?

You can choose to update your existing theme, retire it, convert it to a full site editing theme, or do nothing.

Existing themes will not break, so doing nothing is a valid option. Just make sure that you take the time to learn about full site editing to be confident about your decision and not feel like you are falling behind!

How to decide if it is time to retire a theme

You can use my checklist for things to consider before retiring themes:

1. The number of purchases, downloads or active installs have dropped over a long period
2. The number of support requests are high compared to the number of active installs
3. The code is not up to current standards and best practices
4. The theme relies on third-party assets or plugins that are no longer maintained
5. You don’t love the theme

If the answer is yes and you think retirement is the best option, make sure that you do not abandon current users or customers. Give them options and guide them towards switching to another theme.

Number five is important to me. I create a small number of themes, and if working on updates for the theme is not enjoyable, I know that I keep putting off the maintenance and updates.

Updating existing themes

Updating themes created before the block editor

If you are updating an older theme built before WordPress 5.0, you need to decide if you want the theme to support both classic content and blocks.

• Supporting both classic content and blocks may lead to bloat and a codebase that is more difficult to maintain.
• You need to test for conflicts between the existing CSS and new block styles. -This can take a significant amount of time and headaches, or it can go smooth -all depending on how the theme is built.
• You need to test the theme with both the block editor and the classic editor plugin.

-If you no longer want to support classic content, carefully consider what this will mean for existing users.

Inform users of the decision and their options. Help users convert classic content to blocks by providing instructions and recommending a plugin that can do this:

Convert to Blocks

Increasing the minimum required WordPress version

If the theme no longer supports classic content, you should update the minimum required WordPress version to indicate what the theme supports.
Updating the minimum required WordPress version means that users who can’t or won’t update WordPress will not receive updates.

• If you want the theme to be compatible with Gutenberg, set the minimum required WordPress version to at least 6.0. Note that Gutenberg increases the minimum required WordPress version regularly. A year ago, the minimum required WordPress version was 5.7.
• For template editing, set the minimum required WordPress version to at least 5.8.
• And to support a popular block plugin like Coblocks, you need at least WordPress 5.5.

Dropping support for Internet Explorer 11

WordPress dropped support for Internet Explorer 11 with version 5.8. And you should too.

Dropping support for Internet Explorer 11

Document breaking changes

When updating themes, especially older themes and themes with many installs,
please consider if your update is a breaking change for existing users or child themes.
If you have to implement breaking changes, document them in the theme’s readme file or changelog.

Gradual adoption of blocks and full site editing features

There are several ways to update existing themes to increase their viability and life span, starting with the bare minimum and gradually adding more features:

1. Add basic support for blocks
2. Enhance the theme with custom block styles
3. Add block patterns
4. Add editable block templates for posts and pages
5. Add block-based template parts
6. Add theme.json

1. Add basic support for blocks

The absolute minimum you can do is make sure that WordPress core blocks look good with your theme. The editor and front also need to match; otherwise, the result is a bad editing experience.

Creating sample content using blocks helps me see which block styles I need to update to match the theme design.
I focus on the following blocks to start with:

• Heading 1-6, site title, post title, paragraph -Does the size, line height, font weight and font family match the design?
• Buttons -Do the default styles match the design or do I need to customize them? Try all different variations.
• List block –Does the size, line height, font weight and font family match the design?
• Quote and pull qoute -Do the default styles match the design or do I need to customize them?

Next, I test group and image blocks with different alignments and widths. Don’t forget to check the spacing between blocks and inner blocks.

Optimize block styles for performance

If you choose to support classic content, you need to locate and replace conflicting, redundant, and duplicate styles. There are build tools such as Post CSS and CSS nano that can help you with this and also minify the files.

For WordPress 5.8 and higher, use separate CSS files for each block and only load the style when you use the block. Learn more:

Block-styles loading enhancements in WordPress 5.8

Checklist

• Editor styles
• Color palette
• Wide and full width blocks
• Custom font sizes
• Responsive embeds

Optionally, add custom gradients, line height, and custom units.

2. Enhance the theme with custom block styles

A custom block style is an optional style that users can select in the block settings sidebar in the Styles section. Adding block styles that match your theme adds value and personality to your theme and makes it more unique. With block styles, you can add styles that are not available as block controls:

How to register custom block styles

3. Add block patterns

Patterns help users add pre-designed, customizable elements to their content. Features that work well as patterns include service sections, contact, product promotions, or other calls to action. You can also support plugin-specific blocks in your patterns; remember to check if the plugin is active.

And best of all, you can reuse block patterns across multiple themes: If you haven’t already started a pattern library, I strongly recommend doing so.
A pattern library is an excellent extension of a starter theme or whatever approach you are using.

Upgrade customizer options to block patterns

If the theme uses customizer options to add elements to the website, you should upgrade these to block patterns.

Compared to a customizer option, a block pattern:

• Can be placed wherever the user wants
• Gets all input and styling options for free without having to create custom options
• Is less code for the developer to maintain

Introduction to block patterns
You may also like this tutorial that I wrote for the Theme Developer Handbook:
Converting customizer options to block patterns

4. Add editable block templates for posts and pages

Template editing is a non-breaking, optional feature added in WordPress 5.8, that brings a part of full site editing to classic themes. By enabling template editing:

• Theme developers can include HTML page templates that are built using blocks.
• Users can assign the templates to posts and pages and edit them in the template editor.
• Users with the correct permissions can also create new templates via the block editor.

The theme can include both classic templates and block templates. Archives, 404, and search result pages are not editable -only post type templates are editable.

• The customizer remains available
• Widgets are available
• The menu screen is available

The template editing interface is limited compared to the Site Editor that is available in block themes. Templates can only be accessed from the block editor, and there is no overview with all available templates. There are plans to improve this in WordPress 6.2 (March 2023), and you can test the changes by activating the latest version of the Gutenberg plugin.

Choosing a method

There are two ways to enable template editing; by including a theme.json file or using theme support: add_theme_support( 'block-templates' );

With the theme support, you must manage and enqueue the block styles for the front and editor yourself. And if you need to filter block settings that are otherwise handled in theme.json, you will need to do it separately, using JavaScript.

With theme.json, WordPress generates CSS custom properties for you, and you can disable or enable block features like custom gradients and drop cap by simply adding true or false values.

-Using the theme.json file has a longer learning curve than adding the theme support because it is a new format. I recommend using the theme support only up until you are ready to take the step to use theme.json.

How to include the block templates

The HTML block templates work the same way in classic themes as in block themes. For a detailed guide please see the lesson about templates and template parts.

• Assemble your blocks in the block editor and copy the markup into your HTML file.
• Place the file inside a folder called templates.

WordPress will look for the HTML file first, and then look for a PHP file if the HTML file is unavailable.

5. Add block-based template parts

From WordPress version 6.1 theme developers can also include HTML template parts that can be used for editable site headers, footers and more. The feature in 6.1 works but is limited, and I strongly recommend activating the latest version of Gutenberg for a better experience.

There are important differences between enabling page template support and template part support:

• Template parts can only be enabled with theme support, not by adding theme.json:
  add_theme_support( 'block-template-parts' )
• Users can edit existing parts, but not add new template parts -unless they activate Gutenberg.
• Template parts are listed under Admin > Appearance > Template parts.

How to include the block template parts

• Assemble your blocks in the block editor and copy the markup into your HTML file.
• Place the file inside a folder called parts.
• Add the template part to your PHP template using the function block_template_part:
  <?php block_template_part( 'footer' ); ?> where ‘footer’ represents ‘footer.html’.

You can also include the template part in a block template or block pattern.

6. Add theme.json

By adding theme.json to a classic theme, theme developers can control block settings and default styles. For an introduction to theme.json, please see the lessons for full site editing themes.

Including theme.json does not hide the customizer, widgets, or menu screen in the WordPress admin area. It does not enable the site editor or the global styles interface.

• Use version 1 of theme.json with WordPress 5.8 (Support in WordPress 5.8 is limited compared to when the Gutenberg plugin is active).
• Use version 2 of theme.json with WordPress 5.9 or newer.

Including theme.json enables template editing

If you want to use theme.json without template editing, remove the theme support:

remove_theme_support( 'block-templates' );

There are potentially breaking changes that you need to be aware of when you include theme.json in a classic theme:

• The inner div for the group block is removed. This causes problems if you are targeting this div in your CSS.
• The default font family styles for the editor are not enqueued. Instead, theme developers are expected to define font families in theme.json.

Theme.json enables the layout control for blocks

Block alignments and widths rely on the layout setting in theme.json:

{
        "version": 2,
	"settings": {
		"layout": {
			"contentSize": "840px",
			"wideSize": "1100px"
		}
	}
}

For classic themes, this setting adds CSS to the editor but not to the front. Theme authors must enqueue the styles for the front of the website manually. -This is because a classic theme may use container elements on the front that the editor is unaware of when generating the CSS.

The layout setting in theme.json enables the layout control in the editor, allowing inner blocks to inherit the default layout and alignment options or specify custom widths:

Theme.json settings replaces theme support

If your theme has the following theme_support and a theme.json setting, the theme.json setting takes precedence.

If the theme does not support versions below WordPress 5.8, you can remove the theme support.

typography.fontSizes is the equivalent of add_theme_support( 'editor-font-sizes', array() );

typography.lineHeight is the equivalent of add_theme_support( 'custom-line-height' );

layout is the equivalent of add_theme_support( 'align-wide' );

color.palette is the equivalent of add_theme_support( 'editor-color-palette', array() );

color.gradients is the equivalent of add_theme_support( 'editor-gradient-presets', array() );

spacing is the equivalent of add_theme_support( 'custom-spacing' );

spacing.units is the equivalent of add_theme_support( 'custom-units', array() );

Introducing theme.json in WordPress 5.8

On layout and content width in WordPress 5.8

Conclusion

The era of the classic or PHP-based theme is not over yet. The upgrade path for adding full site editing features to existing classic themes varies depending on if the theme supports classic content, its minimum required WordPress version, and how it manages CSS.

There are two ways to enable template editing: Using theme support or adding a theme.json file. Meaning, you do not need to choose between the customizer and the new configuration file; with a hybrid theme, you can have both.

So, would I recommend hybrid themes over full site editing themes?

I recommend upgrading existing themes to hybrid themes if the number of installs is large enough for it to be viable (cost- and time-effective).

• If you produce themes that rely on companion plugins that use the customizer, I recommend slowly phasing this out, and mean while, create hybrid themes.
• If you produce themes that are standalone, I recommend creating new full site editing themes over hybrid or classic themes.

-In both cases, I recommend making useful and beautiful templates and block patterns that you can reuse with only minor changes. Reusable templates and patterns are huge time savers.

There are still significant differences between creating and maintaining classic themes and full site editing themes. A full site editing theme offers more customization options for the user, more control over the blocks for the theme developer, and less code to maintain.