search

WordPress / gutenberg

The Block Editor project for WordPress and beyond. Plugin is available from the official repository.
https://wordpress.org/gutenberg/
Other
10.33k stars 4.12k forks source link

Docs: Template registration from a plugin #64495

Open juanmaguitar opened 1 month ago

juanmaguitar commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

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 https://github.com/WordPress/developer-blog-content/issues/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 commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

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.