Add: Template types to the patterns API.

[jorgefilipecosta]

This PR adds a new templateType property to the patterns registration API.
This property allows a pattern to specify which template it makes sense on e.g.: 404, single-post, single-product, category.

This is required by #42325 in order to when creating a template show all the relevant patterns that exist for it.
It may also allow users on the pattern directory to explore patterns by the template where they are supposed to be used.

Testing

I pasted the following sample pattern on lib/compat/wordpress-6.2/block-patterns.php.

register_block_pattern(
	'query/template-type-test',
	array(
		'title'      => __( 'Template type test', 'gutenberg' ),
		'templateTypes' => array( '404' ),
		'content'    => '<!-- wp:paragraph {"align":"center","fontSize":"x-large"} -->
						<p class="has-text-align-center has-x-large-font-size">404</p>
						<!-- /wp:paragraph -->',
	)
);

I opened the post editor and the developer tools and pasted wp.apiFetch( { path: '/wp/v2/block-patterns/patterns' } ).then( console.log );on the browser console.
I verified that the API response for included query/template-type-test include 404 in the templateTypes.

[codesandbox]

  Open in CodeSandbox Web Editor | VS Code | VS Code Insiders

[spacedmonkey]

Please add a unit test

[jorgefilipecosta]

Please add a unit test

Hi @spacedmonkey, thank you for the review 👍 The unit tests were updated to take into account template types.

[youknowriad]

What does it mean to have both block types and template types for instance? Is this even possible? I feel like we need some kind of documentation about all these properties.

[jorgefilipecosta]

They are two distinct things. blocktTypes specifies blocks where the pattern makes sense, e.g: group, templateTypes specifies templates where the pattern makes sense. I think it is ok to have both and may make sense, e.g.: a 404 pattern that is a group block wrapping some 404 content may have group block type and 404 template, it should work well I don't see a reason for it not to work.
My plan is to add the same documentation the other properties have e.g: here docs/reference-guides/block-api/block-patterns.md, and a follow-up core PR similar to this one WordPress/wordpress-develop#2858.

[youknowriad]

Ok, this looks good to me

[ironprogrammer]

I'm adding some additional testing info here, as this enhancement has been highlighted in the WordPress 6.2 Call for Testing post (also see r55168).

Testing Instructions

Steps to Test

1. Activate the Twenty Twenty-One theme.
2. In the theme’s inc/block-patterns.php file, after the existing calls to register_block_pattern(), add the sample test pattern with the snippet below (Figure 1). Save the file.
3. Open the post editor, and then the browser developer tools console.
4. In the console enter the following to retrieve the registered patterns: wp.apiFetch( { path: '/wp/v2/block-patterns/patterns' } ).then( console.log );
5. Verify that the API response includes the pattern query/template-type-test, and template_types has 404 listed (Figure 2).

Supplemental Artifacts

Figure 1: TT1 Test Code Snippet

register_block_pattern(
    'query/template-type-test',
    array(
        'title'      => __( 'Template type test', 'twentytwentyone' ),
        'templateTypes' => array( '404' ),
        'content'    => '<!-- wp:paragraph {"align":"center","fontSize":"x-large"} -->
                        <p class="has-text-align-center has-x-large-font-size">404</p>
                        <!-- /wp:paragraph -->',
    )
);

Figure 2: API response output in dev tools console

[jorgefilipecosta]

Dev note:

Introduction

The Patterns API is a powerful feature in WordPress that allows developers to create pre-designed blocks of content that can be easily inserted into posts, pages, custom post types, and templates. With the introduction of WordPress 6.2, the Patterns API has been expanded to include a template types property. The property allows pattern developers to specify which templates their patterns fit in. For example, a pattern can declare its purpose is to be used on 404 templates or as author templates, etc. Any template in the WordPress hierarchy is supported.

Right now template_types property has no impact on the behavior and UX of WordPress. But using the API provides WordPress core information on the relationship between a pattern and a template. This information could be used for multiple purposes. The first usage in mind is to show the user some patterns that make sense on a template when the user starts creating a template. Users can start from a pattern instead of "blank" or the fallback template.

Technical details

The Patterns API's register_block_pattern() function was updated to include a new template_types parameter. This parameter is an array of strings containing the names of the templates the template is intended for, e.g., 404, author, etc. The parameter template_types is optional, and using it is not mandatory to register a pattern.

The REST API was also extended to return the template types of a pattern in case there is one defined.

Testing

1. Activate the Twenty Twenty-One theme.
2. In the theme’s inc/block-patterns.php file, after the existing calls to register_block_pattern(), add the sample test pattern with the snippet below (Figure 1). Save the file.
3. Open the post editor, and then the browser developer tools console.
4. In the console enter the following to retrieve the registered patterns: wp.apiFetch( { path: '/wp/v2/block-patterns/patterns' } ).then( console.log );
5. Verify that the API response includes the pattern query/template-type-test, and template_types has 404 listed (Figure 2).

Figure 1: TT1 Test Code Snippet

register_block_pattern(
    'query/template-type-test',
    array(
        'title'      => __( 'Template type test', 'twentytwentyone' ),
        'templateTypes' => array( '404' ),
        'content'    => '<!-- wp:paragraph {"align":"center","fontSize":"x-large"} -->
                        <p class="has-text-align-center has-x-large-font-size">404</p>
                        <!-- /wp:paragraph -->',
    )
);

Figure 2: API response output in dev tools console

Props to @ironprogrammer for writing these detailed instructions.