New Plugin Template Registration API in WordPress 6.7

Since the introduction of block themes, theme developers have been able to create custom block templates. However, this possibility is limited to themes and plugins cannot register their own templates directly. In order to achieve similar functionality, plugins have to employ complex methods, including hooking multiple PHP filters, manually creatingWP_Block_Templateobjects and replicate the internal WordPress logic.

WordPress 6.7 A new API has been introduced that will greatly simplify the process of plugins registering their own block templates. To accomplish this, two new features have been introduced:register_block_template()For registering block templates andunregister_block_template()Used to unregister block templates.

register_block_template( string $template_name, $args = array() )Accepts two parameters that define how the template is registered:

• $template_name: Template name in the form of plugin_uri//template_name (note that this requires a double //).
• $args: Array of parameters used to define the template:
  • title: The internationalized title of the template.
  • description: An internationalized description of the template.
  • content: The default content (block markup) of the template when rendered in the editor or frontend.
  • post_types: A series of post type slugs that can be provided to users as custom templates for each post.

For example, the plugin can register templates using the following code snippet:

register_block_template( 'devblog-plugin-templates//my-template', [
    'title' => __( 'Example', 'devblog-plugin-templates' ), [ 'description' => __( 'An example block template from a plugin.
    '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"} /-->'
register_block_template( 'devblog-plugin-templates//my-template', [
    'title' => __( 'Example', 'devblog-plugin-templates' ), [ 'description' => __( 'An example block template from a plugin.
    '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"} /-->'
register_block_template( 'devblog-plugin-templates//my-template', [
    'title' =&gt; __( 'Example', 'devblog-plugin-templates' ), [ 'description' =&gt; __( 'An example block template from a plugin.
    'description' =&gt; __( 'An example block template from a plugin.', 'devblog-plugin-templates' ),
    'content' =&gt; '
        <!-- 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"} /-->'

Once registered, this template will appear with all other templates in the Site Editor:

And, if desired, you can unregister later using the following command:

  unregister_block_template( 'devblog-plugin-templates//my-template' )
  unregister_block_template( 'devblog-plugin-templates//my-template' )
	unregister_block_template( 'devblog-plugin-templates//my-template' )

The plugin can also override templates in the WordPress template hierarchy, such as archive pages for custom post types or specific author pages.

Theme templates take precedence over plugin-registered templates, allowing themes to override specific plugin templates, just like with WordPress templates.

Currently this API is limited to block templates and does not allow registration of block template sections.