Plugin Block Template editor inconsistency

[widoz]

Description

I've noticed that registering a block template with a slug matching exactly page even if not applied (so the meta _wp_page_template does not exist) will be applied if and only if I click on the Template within the editor.

The template is applied only to the Editor.

Below is the code I've used

namespace Plugin\Templates;

function load_template(string $templateName): string {
	ob_start();
	include plugin_dir_path(__FILE__) . '/templates/' . $templateName . '.php';
	return ob_get_clean();
}

add_action( 'init', static function() {
	wp_register_block_template(
		'templates//page',
		[
			'title' => 'My Single Page',
			'description' => 'This is my single template',
			'content' => load_template('page'),
			'post_types' => [ 'page' ],
		]
	);
} );

Step-by-step reproduction instructions

1. Register a new block template using a slug including '//page' as part of the template name
2. Open the Sample Page Edit page
3. On Page Panel, click Pages near the right of the Template label

Screenshots, screen recording, code snippet

Screencast.from.2024-09-23.23-41-27.webm

Environment info

WordPress Version: 6.7-alpha-59076
Gutenberg Version: 19.3.0-rc.1

Please confirm that you have searched existing issues in the repo.

• Yes

Please confirm that you have tested with all plugins deactivated except Gutenberg.

• Yes

[colorful-tones]

Thanks for reporting this issue. However, I'm not certain that it is a bug, or merely how the API is designed?

With the example code above it seems you would be trying to overwrite the page.php. However, the wp_register_block_template API is to allow plugins to register custom templates, and not overwrite existing or default WP template files.

If we look at this check: https://github.com/WordPress/wordpress-develop/blob/292769dde95d7fec3b4f335af5b1c5cf04054db4/src/wp-includes/class-wp-block-templates-registry.php#L89

It is doing a lookup for get_default_block_template_types() (see: wp-includes/block-template-utils.php#L141), which checks against 'page' (see: wp-includes/block-template-utils.php#L163).

If my understanding is correct then maybe we could look to introduce some additional error boundary for checking against get_default_block_template_types() and consider updating the dev note for 6.7. But, I would like @Aljullu to give some perspective. I believe he helped sheperd some of this API into being.

I may be misunderstanding @widoz use case, and please forgive me if so. 😃

[colorful-tones]

I meant to also tag @getdave and @kevin940726 for insight please.

[widoz]

With the example code above it seems you would be trying to overwrite the page.php. However, the wp_register_block_template API is to allow plugins to register custom templates, and not overwrite existing or default WP template files.

Hi @colorful-tones, They do not if the template exists in the theme but it is allowed if the theme does not provide one of them.
See #61577

[ndiego]

@Aljullu since you have worked on the template registration API, would you be able to provide any insight here?

[ndiego]

Since RC1 is occurring later today and there is no active PR, I think we should punt this to 6.8 or 6.7.1. Thoughts @colorful-tones @getdave @kevin940726?

[colorful-tones]

Since RC1 is occurring later today and there is no active PR, I think we should punt this to 6.8 or 6.7.1.

Agree 👍

[Aljullu]

Thanks for opening this issue, @widoz. I'm not able to reproduce and I'm not 100% sure to understand what's going on here. A couple of questions:

• Does the theme you use include a page template?
• Does enabling/disabling the Gutenberg plugin makes a difference? Asking because the backend code in WP core and in Gutenberg is slightly different, so the issue might only be reproducible in GB or in WP. Never mind, the code from WP core takes precedence over the code from Gutenberg, so the issue might be there. 🤔

Also wondering if you can reproduce the issue by hardcoding the content in the code snippet, that would allow us to have simpler steps. Something like this: 🙂

add_action( 'init', static function() {
	wp_register_block_template(
		'templates//page',
		[
			'title' => 'My Single Page',
			'description' => 'This is my single template',
			'content' => '<!-- wp:paragraph --><p>This is a plugin-registered template.</p><!-- /wp:paragraph -->',
			'post_types' => [ 'page' ],
		]
	);
} );

However, the wp_register_block_template API is to allow plugins to register custom templates, and not overwrite existing or default WP template files.

In fact, the goal of the API is to allow registering any template, even default WP ones. However, as @widoz mentions, theme templates take priority over plugin-registered templates. So if the theme includes a page.html template, the plugin-registered one shouldn't be available anywhere, as the theme template is considered to "override" the plugin one.

[colorful-tones]

Also wondering if you can reproduce the issue by hardcoding the content in the code snippet

I wondered about this too. Good call out for simplifying the recreation steps. 👍

[colorful-tones]

@widoz do you mind clarifying these items please:

• Does the theme you use include a page template (page.html)?
• Can reproduce the issue with the following simplified code?

add_action( 'init', static function() {
	wp_register_block_template(
		'templates//page',
		[
			'title' => 'My Single Page',
			'description' => 'This is my single template',
			'content' => '<!-- wp:paragraph --><p>This is a plugin-registered template.</p><!-- /wp:paragraph -->',
			'post_types' => [ 'page' ],
		]
	);
} );

[widoz]

Hi everyone, sorry about the late reply, I'll try to answer as best as I can

@Aljullu
Here is my Gutenberg fork I use for study, the templates plugin is located at https://github.com/widoz/gutenberg/tree/my-trunk/development/plugins/templates . I use twentytwentyfour as a theme for my local env.

Does the theme you use include a page template?

Yes

Also wondering if you can reproduce the issue by hardcoding the content in the code snippet

Unfortunately, I cannot replicate the problem anymore, at least not the way I was able to replicate it the first time (see first video). Now as you can see from the video below, the Template name appears for less than a second. It's not persistent anymore.

No differences in using a load_template or a static content.

Screencast.from.2024-10-18.23-31-44.webm

Unfortunately I had problems with my local setup, and I had to destroy everything and I've also updated to the latest changes in the plugin, therefore my current installation is no longer the same of the one I had when I was experiencing the issue.

cc @colorful-tones

[ndiego]

Thanks for the additional info @widoz. I was finally able to replicate this. As you mentioned, the issue is no longer persistent, but I was able to capture the flash in the video below.

custom-template-bug.mp4

Steps to replicate:

• Set up a local site with 6.7 Beta/RC installed
• Add the following code via a plugin for the functions.php of the current theme

add_action( 'init', function() {
	register_block_template(
		'templates//page',
		[
			'title' => 'My Single Page',
			'description' => 'This is my single template',
			'content' => '<!-- wp:paragraph --><p>This is a plugin-registered template.</p><!-- /wp:paragraph -->',
			'post_types' => [ 'page' ],
		]
	);
} );

• Navigate to a new page
• The Template setting should be set to "Pages"
• Click on "Pages" and notice the flash.
• Update the code by replacing templates//page with something like templates//testing
• Confirm that the flash no longer occurs when clicking "Pages"

cc @Aljullu