Plugin-registered block template title and description missing when overwritten by theme

[justintadlock]

Description

With the changes in #61577, it's possible to register a block template via a plugin. As you can see in the screenshot below, I registered a few templates. Take particular note of the example template and its name and description:

If I then overwrite this from a theme via /templates/example.html, the Title field uses the template name and the Description field is missing:

Step-by-step reproduction instructions

Step 1: Register a block template (Code below is for a plugin named devblog-plugin-templates):

add_action( 'init', 'devblog_register_plugin_templates' );

function devblog_register_plugin_templates() {
	wp_register_block_template( 'devblog-plugin-templates//example', [
		'title'       => __( 'Example', 'devblog-plugin-templates' ),
		'description' => __( 'An example block template from a plugin.', 'devblog-plugin-templates' ),
		'content'     => '<!-- wp:template-part {"slug":"header","area":"header","tagName":"header"} /-->
			<!-- wp:group {"tagName":"main"} -->
			<main class="wp-block-group">
				<!-- wp:group {"layout":{"type":"constrained"}} -->
				<div class="wp-block-group">
					<!-- wp:paragraph -->
					<p>This is a plugin-registered template.</p>
					<!-- /wp:paragraph -->
				</div>
				<!-- /wp:group -->
			</main>
			<!-- /wp:group -->
			<!-- wp:template-part {"slug":"footer","area":"footer","tagName":"footer"} /-->'
	] );
}

Step 2: Verify title and description are correct in the UI

Title should be should be Example, and description should be An example block template from a plugin in the Templates UI.

Step 3: Overwrite example.html in a theme

Create a /templates/example.html template in a theme with whatever block markup you want.

Step 4: Check template title and description

Now you should see a template titled example with no description and listed under your theme in the Templates UI.

Screenshots, screen recording, code snippet

No response

Environment info

• WordPress trunk
• Gutenberg trunk

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

[justintadlock]

CC: @Aljullu - Just tagging you here since you worked on the original PR.

[Aljullu]

Thanks for tagging me, @justintadlock! I initially thought that themes would be expected to provide their own template title and description in theme.json. But thinking about this again, it makes sense to fall back to the plugin title/description if one is not provided by the theme. 🤔

[Aljullu]

Now you should see a template titled example with no description

I opened a PR that will fix this in #64610.

and listed under your theme in the Templates UI.

Hmmm, actually I made this on purpose (00d9f40): given that theme templates have priority over plugin templates, I thought it made sense that the displayed author is the theme and not the plugin. However, I can see pros and cons of both approaches, so I'm happy to change how this works if you think showing the plugin is better.

[justintadlock]

Thanks for tagging me, @justintadlock! I initially thought that themes would be expected to provide their own template title and description in theme.json. But thinking about this again, it makes sense to fall back to the plugin title/description if one is not provided by the theme. 🤔

You're the second person who's mentioned that. There's no mechanism for doing this in theme.json. 😄 The customTemplates property in theme.json is specifically meant for custom page templates (or post/CPT). You either have to set the postTypes array manually or it'll default to [ 'page' ].

Docs: https://developer.wordpress.org/themes/global-settings-and-styles/custom-templates/

Themes actually have to filter default_template_types to set a custom title and description for a template (or to register new templates).

The idea of letting themes set the title and description sounds like a good idea, though. But, yeah, I agree that falling back to the plugin defaults is ideal.

and listed under your theme in the Templates UI.

Hmmm, actually I made this on purpose (00d9f40): given that theme templates have priority over plugin templates, I thought it made sense that the displayed author is the theme and not the plugin. However, I can see pros and cons of both approaches, so I'm happy to change how this works if you think showing the plugin is better.

That bit was listed under my step-by-step instructions of how to recreate and see the issue, not under the description of the problem. I don't have any strong opinions either way at the moment, given the approach used to accomplish this feature. So I'd probably wait to see what the feedback looks like.

---

FWIW, I would've approached the feature entirely differently and opened the API to any plugin or theme that wanted to register a template:

• Let both themes and plugins create template categories (this would be a "nice to have").
• Let both themes and plugins register templates (this would be more of a "must have").

[Aljullu]

Themes actually have to filter default_template_types to set a custom title and description for a template (or to register new templates).

Oh, TIL. Thanks!

The idea of letting themes set the title and description sounds like a good idea, though. But, yeah, I agree that falling back to the plugin defaults is ideal.

That bit was listed under my step-by-step instructions of how to recreate and see the issue, not under the description of the problem. I don't have any strong opinions either way at the moment, given the approach used to accomplish this feature. So I'd probably wait to see what the feedback looks like.

Sounds good, let's leave it as-is, then.

FWIW, I would've approached the feature entirely differently and opened the API to any plugin or theme that wanted to register a template:

• Let both themes and plugins create template categories (this would be a "nice to have").
• Let both themes and plugins register templates (this would be more of a "must have").

I'm not an expert on theme development, but in the future it should be possible to open this API to be used by themes in addition to plugins, no? Or do you see any big blocker in the way it's shaped?

[justintadlock]

I'm not an expert on theme development, but in the future it should be possible to open this API to be used by themes in addition to plugins, no? Or do you see any big blocker in the way it's shaped?

I don't see anything that's a blocker for expanding it.

I'll open a second ticket to explore that for later.

[ntsekouras]

Hmmm, actually I made this on purpose (00d9f40): given that theme templates have priority over plugin templates, I thought it made sense that the displayed author is the theme and not the plugin. However, I can see pros and cons of both approaches, so I'm happy to change how this works if you think showing the plugin is better.

But, yeah, I agree that falling back to the plugin defaults is ideal.

I don't have a strong opinion since I'm not a theme builder, but I would also expect this to be the correct behavior. Won't this be confusing if the plugin's template description or title reference the plugin, but the author below now is a theme?

The idea of letting themes set the title and description sounds like a good idea, though.

In my mind this is the main issue here..

[Aljullu]

Won't this be confusing if the plugin's template description or title reference the plugin, but the author below now is a theme?

Just to confirm I'm following: you mean we should leave the plugin as the author even when the theme overrides the template, is that what you mean? This is not how it works now, but I'm fine changing it.