Docs: Template registration from a plugin

[juanmaguitar]

A new registration API for templates (wp_register_block_template) function has been merged. This new API allows extenders to register templates and template parts from a custom plugin or theme. It also allows extender to assign a template to a custom type (among other things)

There should be some guide or documentation in the Handbooks about this new way of registering templates.

At first glance, a new page called "Registering Templates" under Theme Handbook > Templates seems to be a good place for such a guide.

cc: @justintadlock @youknowriad

[youknowriad]

I'm not sure this should live in the "theme handbook". Theme register templates by adding files to the templates folder. This is more for plugin authors. So maybe a guide would be better.

[juanmaguitar]

I'm not sure this should live in the "theme handbook". Theme register templates by adding files to the templates folder. This is more for plugin authors. So maybe a guide would be better.

You're right! 🤦‍♂️
As there's already a Dev Blog tutorial planned about this topic (see WordPress/developer-blog-content#189) this could be a good next step documentation-wise.

From there, maybe we could add a new How-to-guide at Block Editor Handbook > How-to Guides explaining how to register templates, template parts, and any other theme-related stuff that can be registered from a plugin. This page could be just about introducing resources on other parts of wordpress.org (like articles in the developer blog)

[justintadlock]

Agreed that this new feature, at least in its current form, is specific to plugins registering templates.

Theme register templates by adding files to the templates folder.

Just noting that the /templates folder method doesn't let theme authors define a title and description. It merely shows up with the template filename. For themes to add a title and description for "registered templates," they have to filter default_template_types.

It might not be a bad idea to document that in the Theme Handbook as well.

[youknowriad]

Just noting that the /templates folder method doesn't let theme authors define a title and description.

Isn't this what the "customTemplates" in theme.json is about (at least for the title and postTypes config)

[justintadlock]

Isn't this what the "customTemplates" in theme.json is about (at least for the title and postTypes config)

That's only for custom post/page/CPT templates. It doesn't work for entirely custom templates.

For example, suppose I wanted to allow for a version of single templates based on post formats (e.g., single-post-format-audio.html, single-post-format-video.html, etc.) by filtering single_template_hierarchy. I would need to, of course, add the templates to the /templates folder. But I'd also need to filter default_template_types to give them titles and descriptions.