Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add: Template types to the patterns API. #45814

Merged
merged 1 commit into from
Dec 21, 2022

Conversation

jorgefilipecosta
Copy link
Member

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
Copy link

codesandbox bot commented Nov 16, 2022

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

@jorgefilipecosta jorgefilipecosta force-pushed the add/template-types-to-the-patterns-api branch from 11e24ec to c529b8e Compare November 16, 2022 16:38
Copy link
Member

@spacedmonkey spacedmonkey left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please add a unit test

@annezazu annezazu mentioned this pull request Nov 28, 2022
57 tasks
@bph bph added Needs Dev Note Requires a developer note for a major WordPress release cycle [Feature] Patterns A collection of blocks that can be synced (previously reusable blocks) or unsynced labels Nov 30, 2022
@jorgefilipecosta jorgefilipecosta force-pushed the add/template-types-to-the-patterns-api branch 4 times, most recently from 035614b to 9db5c24 Compare December 1, 2022 18:49
@jorgefilipecosta jorgefilipecosta force-pushed the add/template-types-to-the-patterns-api branch 2 times, most recently from 137a626 to c36c29b Compare December 2, 2022 14:46
@jorgefilipecosta
Copy link
Member Author

Please add a unit test

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

'type' => 'array',
'readonly' => true,
'context' => array( 'view', 'edit', 'embed' ),
),
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@jorgefilipecosta jorgefilipecosta force-pushed the add/template-types-to-the-patterns-api branch from c36c29b to 536c39b Compare December 19, 2022 20:25
Copy link
Contributor

@youknowriad youknowriad left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, this looks good to me

@jorgefilipecosta jorgefilipecosta force-pushed the add/template-types-to-the-patterns-api branch 2 times, most recently from 5cded5d to 463e399 Compare December 20, 2022 22:00
@jorgefilipecosta jorgefilipecosta force-pushed the add/template-types-to-the-patterns-api branch from 463e399 to 77b0ae2 Compare December 21, 2022 10:31
@jorgefilipecosta jorgefilipecosta merged commit 4cae3ad into trunk Dec 21, 2022
@jorgefilipecosta jorgefilipecosta deleted the add/template-types-to-the-patterns-api branch December 21, 2022 10:55
@github-actions github-actions bot added this to the Gutenberg 14.9 milestone Dec 21, 2022
@jorgefilipecosta jorgefilipecosta added the Backport to Gutenberg RC Pull request that needs to be backported to a Gutenberg release candidate (RC) label Jan 30, 2023
@ntsekouras ntsekouras removed the Backport to Gutenberg RC Pull request that needs to be backported to a Gutenberg release candidate (RC) label Jan 31, 2023
pento pushed a commit to WordPress/wordpress-develop that referenced this pull request Jan 31, 2023
Backports WordPress/gutenberg#45814 into the core.
This commit 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.

Props youknowriad, ntsekouras, 
spacedmonkey.

git-svn-id: https://develop.svn.wordpress.org/trunk@55168 602fd350-edb4-49c9-b593-d223f7449a82
markjaquith pushed a commit to markjaquith/WordPress that referenced this pull request Jan 31, 2023
Backports WordPress/gutenberg#45814 into the core.
This commit 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.

Props youknowriad, ntsekouras, 
spacedmonkey.
Built from https://develop.svn.wordpress.org/trunk@55168


git-svn-id: http://core.svn.wordpress.org/trunk@54701 1a063a9b-81f0-0310-95a4-ce76da25c4cd
github-actions bot pushed a commit to gilzow/wordpress-performance that referenced this pull request Jan 31, 2023
Backports WordPress/gutenberg#45814 into the core.
This commit 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.

Props youknowriad, ntsekouras, 
spacedmonkey.
Built from https://develop.svn.wordpress.org/trunk@55168


git-svn-id: https://core.svn.wordpress.org/trunk@54701 1a063a9b-81f0-0310-95a4-ce76da25c4cd
@bph bph mentioned this pull request Feb 6, 2023
47 tasks
@ironprogrammer
Copy link
Contributor

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

tt1-template-type-test

@jorgefilipecosta
Copy link
Member Author

jorgefilipecosta commented Mar 7, 2023

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

tt1-template-type-test

Props to @ironprogrammer for writing these detailed instructions.

VenusPR added a commit to VenusPR/Wordpress_Richard that referenced this pull request Mar 9, 2023
Backports WordPress/gutenberg#45814 into the core.
This commit 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.

Props youknowriad, ntsekouras, 
spacedmonkey.
Built from https://develop.svn.wordpress.org/trunk@55168


git-svn-id: http://core.svn.wordpress.org/trunk@54701 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[Feature] Patterns A collection of blocks that can be synced (previously reusable blocks) or unsynced Needs Dev Note Requires a developer note for a major WordPress release cycle [Type] Feature New feature to highlight in changelogs.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants