Fabian Kägy 5:35 am on October 4, 2022
Tags: 6.1 ( 94 ), dev-notes ( 540 ), dev-notes-6.1 ( 37 )

Block-based “template parts” in traditional themes

Starting in WordPress 6.1, traditional WordPress themes can adopt the usage of blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.-based template parts in their themes. To enable this feature a theme needs to specify the block-template-parts theme support. The theme developer can add block-based template parts by placing HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. files containing the block template into the /parts folder inside the root directory 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 PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher templates by using the block_template_part function.

Example:

If a theme developer wants to make the site footer editable using blocks, they can create a new file called footer.html inside the my-theme/parts/ directory. This file should contain the default markup of the blocks used to build the footer.

<!-- 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 actually use this template part the theme author then needs to call the block_template_part function and pass the name of the template part as the first and only parameter.

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

Props to @mamaduka, @bph, and @annezazu for reviewing this post.

#6-1, #dev-notes, #dev-notes-6-1

Paul Biron 9:07 pm on October 8, 2022

I really like this. When I saw this post I immediately started experimenting with one of my classic themes.

All was going great…I got several things converted over to using blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.-based template parts. Big win!

Then I ran into a problem. I need to include a shortcodeShortcode A shortcode is a placeholder used within a WordPress post, page, or widget to insert a form or function generated by a plugin in a specific location on your site. block in one of these new block-based template parts…and that doesn’t work, even tho shortcode blocks work fine in a block-based template parts that are part of a full block-based theme 🙁

It took a lot of digging to figure out why it wasn’t working:

1. the first thing I learned is that the render_callback for the core/shortcode block does not actually call do_shortcode()…that was a real surprise to me!!

2. full block-based themes rely on get_the_block_template_html() to call do_shortcode() after the template (and it’s parts) have been loaded.

I came up with a workaround, although it’s a very hacky, not to mention that it runs afoul of Add sniff to warn against using output buffering. In the classic template that calls block_template_part(), I do something like:

ob_start();

block_template_part( ‘my-block-template-that-includes-a-shortcode-block’ );

$content = shortcode_unautop( ob_get_clean() );

echo do_shortcode( $content );

Is the fact that shortcode blocks do not work in block-based template parts within classic themes a known “issue”? Should I open a GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ Issue or TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticketticket Created for both bug reports and feature development on the bug tracker. for this?
- George Mamadashvili 7:57 am on October 10, 2022
  
  Thanks for testing and catching the issue, @pbiron!
  
  As you mentioned, the block_template_part function is missing a few function calls that are usually applied to the_content.
  
  I believe the ticketticket Created for both bug reports and feature development on the bug tracker. should be opened on TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress..
  
  Feel free to pingPing The act of sending a very small amount of data to an end point. Ping is used in computer science to illicit a response from a target server to test it’s connection. Ping is also a term used by Slack users to @ someone or send them a direct message (DM). Users might say something along the lines of “Ping me when the meeting starts.” me in the ticket, and I will try to follow up with a patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing..
  - Paul Biron 2:03 pm on October 10, 2022
    
    Done, 56780
Ryo 5:05 am on October 21, 2022

Thanks for the great feature.

I would like to confirm one point, but can this new template function only call the prepared file?

Do you have any plans to add a feature in the future, such as a template editor that appears in the adminadmin (and super admin) screen and allows users to edit the template in blocks?
Ryo 5:35 am on October 21, 2022

Oh…I’m sorry. I was so misunderstood. The edit screen has appeared…!
- George Mamadashvili 5:42 am on October 21, 2022
  
  I’m happy that the issue got resolved.
  
  I would like to confirm one point, but can this new template function only call the prepared file?
  
  Technically block_template_part can display any existing template part; you just need to provide the slug.
WebMan Design | Oliver Juhas 12:49 pm on November 2, 2022

Thanks for this functionality!
Suggestion:
Would be great if the `block_template_part()` function also returned boolean, so we can use it conditionally like in this example:
“`php
<?php
if ( true === block_template_part( 'footer' ) ) {
return
} else {
// Theme's native footer here, such as a sidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme..
}
“`
- WebMan Design | Oliver Juhas 12:58 pm on November 2, 2022
  
  Also, unfortunately, it does not really work with classic themes (without theme.json file) as when editing the template part I can not set first Group blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. wide/full alignment.
- maurodf 7:00 pm on November 7, 2022
  
  Yeah, i think that would be great too!
  But i don’t think that in this moment is possible to achive.
  
  if ( true === block_template_part( ‘footer’ ) ) respond true if the file exist. But the file must exist to activate template parts in classic theme and to provide the user to modify its with the FSE, so, the if respond always true.
mrwweb 7:54 pm on November 4, 2022

It’s possible that there is some user error on my part, but I was unable to get this working without also registering templatePart in `theme.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML.`.

Without that, I could see the Appearance > Template Parts menu item and click the template part from the `/parts`, but the template part editor screen was white with the console error “TypeError: s is null” (Firefox) or “TypeError: Cannot read properties of null (reading ‘default’)” (Chrome).
- mrwweb 8:06 pm on November 4, 2022
  
  It seems like I spoke too soon. I realize now that the presence of the `theme.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML.` in my theme seems to be causing the issue. (When adding `templateParts` to my `theme.json` I invalidated the JSON with a typo. This made the template editor load briefly. Fixing the typo and restoring valid JSON creates the white screen again.)
  
  This helped me narrow it down to this: Setting `settings.color.customDuotone` to `null` breaks the template part editor. This is the only way I know of to remove support for the duotone SVGs in the page source via `theme.json`, although I believe it’s not officially supported.
  
  Hope this helps someone else!
  - Paul Biron 8:19 pm on November 4, 2022
    This is what I use:
    
    { "$schema": "https://schemas.wp.org/trunk/theme.json", "version": 2, "settings": { "color": { "customDuotone": false, "duotone": [] } } }
    
    That is: false instead of null for customDuotone, and [] (empty array) for duotone.
    
    And those values validate against the jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. schema for theme.json
Jason LeMahieu (MadtownLems) 8:20 pm on November 7, 2022

I’m loving this so far! Is it possible to use a more human-readable title and description for template parts registered like this?

Example:
“name” = home-page-post-list-above,
“title”= Home Page Post List (Above),
“description” = “This will show above your post listings on your site’s home page.”

I tried also registering the templatepart in theme.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML., hoping that would let me use the title, but it doesn’t seem to be the case (and no idea where/how I’d enter a description)
- mrwweb 9:20 pm on November 7, 2022
  
  @MadtownLems I was able to use `theme.json` to get the result you were hoping for:
  
  `{
  “$schema”: “https://schemas.wp.org/trunk/theme.json”,
  “version”: 2,
  “templateParts”: [
  {
  “area”: “footer”,
  “name”: “footer”,
  “title”: “Footer”
  }
  ]
  }`
  
  That made what had been “footer” from my `parts/footer.html` file appear as “Footer” in the Template Parts UI.
  
  Maybe just double-check your `theme.json` and make sure it validates or double-check that your file name and `name` are the same?
  
  @fabiankaegy I was surprised the `theme.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML.` stuff wasn’t documented in this post. It might be worth adding!
  - Jason LeMahieu (MadtownLems) 9:49 pm on November 7, 2022
    
    Interesting – thank you for sharing! I just double-checked everything, and ensured theme.json validated successfully, and still can’t get that result, unfortunately:
    
    // index.php
    block_template_part( ‘post-listing-header’ );
    
    // theme.json
    {
    “$schema”: “https://schemas.wp.org/trunk/theme.json”,
    “version”: 2,
    “templateParts”: [
    {
    “name”: “post-listing-header”,
    “title”: “Post Listing Header”,
    “area”: “header”
    }
    ],
    “settings”: {….
    
    & finally
    my-theme/parts/post-listing-header.html
    
    I also tried enabling Gutenberg plugin to see if that helped (it didn’t), and tried a name without dashes (didn’t help either).
    
    Oh well ¯\_(ツ)_/¯ I’ll try to dig deeper if we decide to pursue this option more seriously. Cheers!
    - Jason LeMahieu (MadtownLems) 10:05 pm on November 7, 2022
      
      Update: It’s working now. Unfortunately I don’t know exactly what was wrong, but clear skies ahead! Thanks again
  - Jason LeMahieu (MadtownLems) 7:29 pm on November 25, 2022
    
    While I could get “nice names” working, I’m curious if there’s any way to get a “description.” I opened a ticketticket Created for both bug reports and feature development on the bug tracker. here with more information and screenshots:
    https://github.com/WordPress/gutenberg/issues/46068
jeffmcnear 7:52 pm on November 16, 2022

something in 6.1.1 seems to have broken this, in 6.1 all was well but as of the latest coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. release the ability to edit the parts is gone …
- Jason LeMahieu (MadtownLems) 7:58 pm on November 16, 2022
  
  For what it’s worth, it’s still working on non-blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. based themes for me on 6.1.1 (and we’re loving it!)
jeffmcnear 8:09 pm on November 16, 2022

are you still able to edit the template parts? I get a white screen when I try it…
- Fabian Kägy 8:15 pm on November 16, 2022
  
  I just tested this on a traditional (classic) theme with 6.1.1 installed and the feature works as expected for me
  - jeffmcnear 8:21 pm on November 16, 2022
    so strange, I have two local sites where once I upgraded to 6.1.1 the ability to edit has ceased although the files themselves still work in the theme
    here is how I activate:
    
    //https://make.wordpress.org/core/2022/10/04/block-based-template-parts-in-traditional-themes/ function add_block_template_part_support() { add_theme_support( 'block-template-parts' ); } add_action( 'after_setup_theme', 'add_block_template_part_support' );
    - jeffmcnear 8:29 pm on November 16, 2022
      
      to be clear there is a “template parts” item under appearance, and I can see the created parts when I follow the link, but unlike with 6.1 with 6.1.1 when I go to edit a template part in the interface the screen is blank white when it loads…
      - jeffmcnear 8:41 pm on November 16, 2022
        
        I have just tried a fresh install modifying the 2019 theme and I get the same result – my local encironment is local-by-flywheel
        
        jeffmcnear 8:43 pm on November 16, 2022
        
        PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher version = 7.4.1
        
        jeffmcnear 8:44 pm on November 16, 2022
        
        toggling between NGINXNGINX NGINX is open source software for web serving, reverse proxying, caching, load balancing, media streaming, and more. It started out as a web server designed for maximum performance and stability. In addition to its HTTP server capabilities, NGINX can also function as a proxy server for email (IMAP, POP3, and SMTP) and a reverse proxy and load balancer for HTTP, TCP, and UDP servers. https://www.nginx.com/. and APACHEApache Apache is the most widely used web server software. Developed and maintained by Apache Software Foundation. Apache is an Open Source software available for free. makes no difference
        
        jeffmcnear 8:55 pm on November 16, 2022
        
        installing the gutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party doesn’t make a difference
- maurodf 9:13 pm on November 16, 2022
  
  Hi, same error for me on my classic theme. White page when i try to edit with template parts.
  - jeffmcnear 9:31 pm on November 16, 2022
    
    happy to hear that I’m not losing my mind … however this is a great disappointment as having template parts in a non-blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. field is a tremendous feature
    - jeffmcnear 9:32 pm on November 16, 2022
      
      non-blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. theme (I meant to say)
    - maurodf 9:51 pm on November 16, 2022
      
      I’m using local too, no theme.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. file added in Classic theme.
      - jeffmcnear 10:27 pm on November 16, 2022
        
        in two cases the instant the 6.1.1 upgrade was complete the issue cropped up … I also can duplicate the issue with an empty install with no conflicting plugins … hopefully we will see a resolution in 6.1.2
  - karks88 2:11 pm on November 17, 2022
    
    Same here on both Local and on a server.
    - jeffmcnear 3:42 pm on November 17, 2022
      
      for what its’ worth I can confirm that directly modifying a file in the theme’s “parts” directory does work which is a slight improvement over using widgets (since there is no code view in widgets)
      - Fabian Kägy 5:06 pm on November 17, 2022
        
        Thank you all for reporting this issue and adding so much detail. Today @mamaduka and I spend some time replicating the issue and have some thoughts of how this regressionregression A software bug that breaks or degrades something that previously worked. Regressions are often treated as critical bugs or blockers. Recent regressions may be given higher priorities. A "3.6 regression" would be a bug in 3.6 that worked as intended in 3.5. got introduced. To track this we have created an issue here: https://github.com/WordPress/gutenberg/issues/45862 You can follow the status of this in there.
        
        jeffmcnear 5:41 pm on November 17, 2022
        
        I am delighted that you are looking into this!!!
        
        karks88 1:38 pm on December 2, 2022
        
        Thank you!
    - George Mamadashvili 6:34 pm on November 17, 2022
      
      I found a temporary solution to the issue – https://github.com/WordPress/gutenberg/issues/45862#issuecomment-1319044884
      - jeffmcnear 8:44 pm on November 17, 2022
        
        absolutely works for me… thank you!
      - ioankoul 2:22 pm on November 30, 2022
        
        Still not working for me; I have a hybrid theme, where I’m using GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ blocks and theme.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. but not FSE. I have followed all the steps to enable the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.-based template parts on my site, but I can’t make it visible on the menu (appearance->template parts). Still works correctly when i’m calling it in the code
interactiveRob 10:49 pm on December 20, 2022

How do I assign content to different regions of the page?

To explain – Assume I’m editing a page and I’ve got lots of content in the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor for said page being rendered via the_content() in a classic theme using page.php

In the page editor, I want to be able to move blocks into different theme-defined regions (aka. block-template-parts) on a page-per-page basis to fit my theme’s layout. Some into main content, some into a sidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme., some into an area below for full-width components.

Is that what this feature is for? or are the block-template-parts supposed to be used site-wide like the given examples headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. and footer?

Comments are closed.

Welcome!

Communication

Block-based “template parts” in traditional themes

Example:

Welcome!

Communication

Example:

Share this: