DocsWP — WordPress Help

Testing and Feedback for using block based template parts in classic themes

This post was a collaboration between @greenshady @mamaduka @fabiankaegy @annezazu. 

Gutenberg 14.1, coming September 15th, enables the ability to use block template parts without adopting everything that comes with block templates. Using this functionality, you can do things like allow a user to edit and build a header with blocks without exposing them to the entire block template system. This offers a new gradual adoption pathway for folks with classic or hybrid themes and new ways to explore full site editing features for agencies that need testing and feedback ahead of WordPress 6.1’s release on November 1st.

For more information around larger gradual adoption pathways, please review the converting a classic theme to a block theme handbook page. For information around how to curate the experience further while still allowing new abilities to edit template parts, please review the curating the editor experience handbook page.

Overview

Gradual adoption options remains a focus for the project and, increasingly, there are more ways to adopt parts rather than the whole of a feature coming to the latest version of WordPress. The aim is to allow folks to adopt what they need as they are ready in a way that is still future forward. In this case, once the feature is enabled, users will see a new “Template Parts” menu visible under “Appearance,” which displays a list of template parts. From there, all theme blocks are available, but the environment is inherently limited compared to block themes. For example, users can edit existing template parts but not delete them or create new ones.

WP Admin interface with the Appearance menu open highlighting the new template parts section.

For a sense of how one could adopt this feature, here are a few examples to get creativity flowing:

  • Offering a header template part that allows a user to set a video or image background, set duotone colors, change the focal point, and more without altering the positioning of the blocks within (navigation, site title, etc).
  • Providing the ability to edit parts of a footer directly, like location and hours of operations, while keeping the structural blocks locked down to preserve the design.
  • Adding a more open ended header template part that allows for any and all block movement/removal/etc but curates the experience with certain design tools disabled for certain blocks and offering default colors that match the broader theme style.

How to test

In order to enable this feature a theme first needs to specify block-template-parts theme support and to use Gutenberg trunk or Gutenberg 14.1 when it’s released on September 15th, 2022. You can also follow these instructions to use the specific PR that implemented this feature.

With that theme support added a theme can now add block-based template parts by placing html files containing the block template into the parts directory inside the root of the theme.

function add_block_template_part_support() {
    add_theme_support( 'block-template-parts' );
}

add_action( 'after_setup_theme', 'add_block_template_part_support' );

These block-based template parts can now be used in the traditional PHP templates by using the block_template_part function. This function returns the markup of the template part which then needs to get output.

If a theme author wanted to make the site footer available to edit as a template part, they would create a footer.html file and place it within their theme’s /parts folder.  The following code snippet is an example of what the template part would look like:

<!-- wp:group {"layout":{"inherit":true}} -->
<div class="wp-block-group">
	<!-- wp:group {"style":{"spacing":{"padding":{"top":"80px","bottom":"30px"}}}} -->
	<div class="wp-block-group" style="padding-top:80px;padding-bottom:30px">
		<!-- wp:paragraph {"align":"center"} -->
		<p class="has-text-align-center">Proudly Powered by <a href="https://wordpress.org" rel="nofollow">WordPress</a></p>
		<!-- /wp:paragraph -->
	</div>
	<!-- /wp:group -->
</div>
<!-- /wp:group -->

To display the part on the front end, the theme would include it in its top-level templates, such as index.php, single.php, and others via the block_template_part() function with a reference to the part name.  In the case of a site footer, this code would replace the call to get_footer() in most themes.

<?php block_template_part( 'footer' ); ?>

Advanced testing

While this feature is currently aimed at providing options for themes, plugins can also explore extending this functionality to enable the same UI for users. If you explore extending this feature via a plugin, please share what blockers, bugs, and enhancements you’d like to see to help shape future work in this area.

Leave your feedback in the comments 

The following are some questions to keep in mind and answer:

  • Did the Template Parts menu appear under Appearance? 
  • Were you able to properly define a template part and see it appear under Appearance > Template Parts?
  • When you edited a template part, did the changes properly reflect on the front end of the site? 
  • Are there missing features or options that would improve this experience as a developer?
  • What did you find frustrating or confusing about the feature?
  • Are there things you particularly appreciated about it?

Please share any and all feedback in the comments.

#testing