A way for programmatically define block-based template files

[mateuswetah]

What problem does this address?

The scenario is very specific: say you want, as discussed here, in a plugin or a theme, to define block-based templates (the .html ones) to render for a certain post type (consider a dynamic one, that could not be defined simply by creating the file in the theme, for example). In classic themes, one could use single_template_hierarchy from inside a plugin to point to a PHP file. In this file, there should probably be a complete wrapper markup (<html, <head, <body...).

When using a block-based theme, the plugin (or a theme, programmatically) can not do this with an equivalent .html file. It would also have to use a .PHP file. Which would also require the wrapper markup, something very odd to do in a block-based theme scenario.

What is your proposed solution?

I'm really not sure of a better solution, but what I'm looking for seems to be:

1. An equivalent of single_template_hierarchy for block-based templates (.html);
2. If .html cannot be used, a way of rendering the wrapper main markup into a PHP file that does not require writing all the markup by hand. If the block-based theme-engine does the work, can't I call it via some function?

@justintadlock Let me know if you can explain this better 😅

[justintadlock]

Here's a Gist where I was testing a custom template for a virtual page that falls back to the plugin: https://gist.github.com/justintadlock/cfcdcdf47ea785e84c8575dddc68ea37

The template hierarchy and its related filter hooks exist for block templates. So I don't think there's anything that needs to change there. At the theme level, this is a non-issue because, well, themes can have block templates. The issue lies with templates at the plugin level.

The missing piece, from what I can tell, is the wrapper that we get from wp-includes/template-canvas.php. This generates the wrapping page markup around block templates. Currently, plugins must produce the markup for that wrapper instead of WordPress doing it if they want to provide a fallback block template from the plugin itself.

This is actually the same as it has always been, including in the classic era. However, with block themes, we now have an opportunity to better standardize the output for plugin fallback templates. If there would be a standard function for plugins to generate that markup that's included in template-canvas.php, it'd mean they would be able to keep up with any changes and remain forward-compatible.

[mateuswetah]

Uhmm, I did not know about that wp-includes/template-canvas.php that is exactly what we need. If using it is somehow simplified and we can just set the templates for the inner content using block-based files, things would be solved!

[gziolo]

We want a new API in WordPress core that makes registering custom block-based templates easy for plugins.

[fabiankaegy]

@helgatheviking shared this on Twitter recently:

So by searching github I see lots of plugins are filtering get_block_templates already... but seriously, nobody has written a tutorial?

And by looking through GitHub here is how a few plugins do it today:

• The Events Calendar
• WooCommerce
• docspress

Bu the amount of custom code that I would describe as hacky they have to use to do it is very large. So a core way to register additional templates would go a long way :)

[helgatheviking]

Yes!!! I didn't know this issue existed already, but following for sure. Plugins are going to need to be able to provide some visual editing capabilities for things that are unique to our plugin.... at least as a fallback for theme's that haven't explicitly provided support.

For example, this week I am working on displaying a quickview modal of a product's details. I can render it all myself, but if a customer asks me how to add some specific content (like nutrition info or ratings or something) I don't know how that would be possible.

[helgatheviking]

Could there be an API that say includes things like register_template and register_template_part() and then maybe spits them out with the relevant wrapping code like do_template()

[simison]

Recent discussion in "Extending available templates via plugins" #41401

[gziolo]

@simison, do you think this issue is a duplicate?

[simison]

Seems so, at least at a glance, unless I'm missing some nuance.

[annezazu]

Going to close this out as the template registration API landed #61577 and afaik it covers this scenario as described! Thanks for opening this and I deeply encourage you to help test what's landed.