Skip to content

Add plugin template registration API - #61577

Merged
ntsekouras merged 49 commits into
trunkfrom
add/plugin-template-registration-api
Aug 13, 2024
Merged

ntsekouras merged 49 commits into
trunkfrom
add/plugin-template-registration-api

Conversation

@Aljullu

@Aljullu Aljullu commented May 10, 2024 •

Copy link
Copy Markdown
Contributor

What?

This PR introduces a new API so plugins can easily register templates.

Closes #41401.

Backport PR in core: WordPress/wordpress-develop#7125.

Why?

Currently, it's not easy for plugins to register templates, as they need to hook into several filters.

How?

This PR creates a new function: wp_register_block_template() as well as a WP_Block_Templates_Registry class. They are based on register_block_type() and WP_Block_Type_Registry.

You can read more about the API shape in this comment: #41401 (comment).

Testing Instructions

Basic template customization:

  1. Add this code to an existing plugin or in a code snippet using the Code Snippets plugin:
add_action(
	'init',
	function () {
		wp_register_block_template(
			'gutenberg//plugin-template',
			array(
				'title'       => 'Plugin Template',
				'description' => 'A template registered by a plugin.',
				'content'     => '<!-- wp:template-part {"slug":"header","tagName":"header"} /--><!-- wp:group {"tagName":"main","layout":{"inherit":true}} --><main class="wp-block-group"><!-- wp:paragraph --><p>This is a plugin-registered template.</p><!-- /wp:paragraph --></main><!-- /wp:group -->',
			)
		);
		add_action(
			'category_template_hierarchy',
			function () {
				return array( 'plugin-template' );
			}
		);
	}
);
  1. Go to a post category in the frontend (ie: /category/test-category/) and verify the Plugin Template contents are rendered.
  2. Go to Appearance > Editor > Templates and verify the Plugin Template appears with the correct title and description.
  3. Make some edits to the template. Verify they are applied in the frontend.
  4. Revert the edits and verify edits are reverted in the frontend as well.

With theme customization:

  1. Add a /templates/plugin-template.html template to your active theme and repeat steps 2-5.
  2. Remove /templates/plugin-template.html from your theme before proceeding with the next steps.

Using the template in a post type:

  1. Update the code snippet from step 1 to this:
add_action(
	'init',
	function () {
		wp_register_block_template(
			'gutenberg//plugin-template',
			array(
				'title'       => 'Plugin Template',
				'description' => 'A template registered by a plugin.',
				'content'     => '<!-- wp:template-part {"slug":"header","tagName":"header"} /--><!-- wp:group {"tagName":"main","layout":{"inherit":true}} --><main class="wp-block-group"><!-- wp:paragraph --><p>This is a plugin-registered template.</p><!-- /wp:paragraph --></main><!-- /wp:group -->',
				'post_types'  => array( 'post' ),
			)
		);
	}
);
  1. Create a new post and verify you can use the Plugin Template and it gets applied to the frontend.

Deactivating the plugin:

  1. Go back to Appearance > Editor > Templates and make some edits to the template.
  2. Deactivate the code snippet you added in step 1 and verify you can delete the Plugin Template (in contrast to resetting it, which is the option available when the plugin is active).

Unregistering templates:

  1. Reactivate the code snippet (or add a new one) with this code:
add_action(
	'init',
	function () {
		wp_register_block_template(
			'gutenberg//plugin-unregistered-template',
			array(
				'title'       => 'Plugin Unregistered Template',
				'description' => 'A plugin-registered template that is unregistered.',
				'content'     => '<!-- wp:template-part {"slug":"header","tagName":"header"} /--><!-- wp:group {"tagName":"main","layout":{"inherit":true}} --><main class="wp-block-group"><!-- wp:paragraph --><p>This is a plugin-registered template that is also unregistered.</p><!-- /wp:paragraph --></main><!-- /wp:group -->',
			)
		);
		wp_unregister_block_template( 'gutenberg//plugin-unregistered-template' );
	}
);
  1. Go to Appearance > Editor > Templates and verify there is no Plugin Unregistered Template template.

Registering WP default templates:

  1. Add this code snippet:
add_action(
	'init',
	function () {
		wp_register_block_template(
			'gutenberg//category',
			array(
				'title'          => 'Custom Category template',
				'description'    => 'This is a custom category template.',
				'content'        => '<!-- wp:template-part {"slug":"header","tagName":"header"} /--><!-- wp:group {"tagName":"main","layout":{"inherit":true}} --><main class="wp-block-group"><!-- wp:paragraph --><p>This is a plugin registered category template.</p><!-- /wp:paragraph --></main><!-- /wp:group --><!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->',
			)
		);
	}
);
  1. In the frontend, go to any category page (ie: /category/test-category/).
  2. Go to Appearance > Site Editor > Templates. Click on Add New Template > Category Archives and verify you are not allowed to create an All Categories template (because it's already registered in the code snippet from step 1 🙂 ).
  3. Go back to the list of templates and make some edits to the "Custom Category Template".
  4. Verify the edits are applied to the frontend.
  5. Reset the edits and verify they are reset in the frontend as well.
  6. Now add a category.html template to your theme.
  7. Go to the frontend and verify the theme template has priority.
  8. Go to Appearance > Editor and verify there is no "Custom Category Template" template, the theme template is listed instead.

Registering templates already customized by the user:

  1. Go to Appearance > Editor > Templates > Add New Template and create a default WordPress template (ie: Author Archives > Author > admin). Make some edits to the template and save it.
  2. After saving, verify you have the option to delete the template from the editor. Verify also that the changes are applied in the frontend (/author/admin/).
  3. Add this code snippet that would simulate installing an extension that registers the same template you just created manually:
add_action(
	'init',
	function () {
		wp_register_block_template(
			'gutenberg//author-admin',
			array(
				'title'          => 'Enhanced Author Admin template',
				'description'    => 'An enhanced version of the Author Admin template.',
				'content'        => '<!-- wp:template-part {"slug":"header","tagName":"header"} /--><!-- wp:group {"tagName":"main","layout":{"inherit":true}} --><main class="wp-block-group"><!-- wp:paragraph --><p>This is an enhanced author template.</p><!-- /wp:paragraph --></main><!-- /wp:group --><!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->',
			)
		);
	}
);
  1. Go back to Appearance > Editor > Templates and verify there is no "Enhanced Author Admin template". You should still see "Author: admin" (the one you created manually).
  2. Open it and verify it matches the edits you did in step 1. Open the page in the frontend and verify the changes from step 1 are still applied in the frontend as well.
  3. In the Site Editor, reset the "Author: admin" template.
  4. Verify the template name changes to "Enhanced Author Admin template".
  5. Verify the contents were refreshed to the ones from the code snippet (step 3).
  6. Verify in the frontend the contents from step 3 are shown.

Devnote

@Aljullu Aljullu self-assigned this May 10, 2024
@github-actions

github-actions Bot commented May 10, 2024 •

Copy link
Copy Markdown

Size Change: +45 B (0%)

Total Size: 1.77 MB

Filename Size Change
build/edit-site/index.min.js 217 kB +21 B (+0.01%)
build/editor/index.min.js 101 kB +24 B (+0.02%)
ℹ️ View Unchanged
Filename Size
build/a11y/index.min.js 951 B
build/annotations/index.min.js 2.26 kB
build/api-fetch/index.min.js 2.31 kB
build/autop/index.min.js 2.12 kB
build/blob/index.min.js 579 B
build/block-directory/index.min.js 7.29 kB
build/block-directory/style-rtl.css 1.01 kB
build/block-directory/style.css 1.01 kB
build/block-editor/content-rtl.css 4.58 kB
build/block-editor/content.css 4.58 kB
build/block-editor/default-editor-styles-rtl.css 394 B
build/block-editor/default-editor-styles.css 394 B
build/block-editor/index.min.js 255 kB
build/block-editor/style-rtl.css 16.3 kB
build/block-editor/style.css 16.3 kB
build/block-library/blocks/archives/editor-rtl.css 61 B
build/block-library/blocks/archives/editor.css 60 B
build/block-library/blocks/archives/style-rtl.css 90 B
build/block-library/blocks/archives/style.css 90 B
build/block-library/blocks/audio/editor-rtl.css 149 B
build/block-library/blocks/audio/editor.css 151 B
build/block-library/blocks/audio/style-rtl.css 132 B
build/block-library/blocks/audio/style.css 132 B
build/block-library/blocks/audio/theme-rtl.css 134 B
build/block-library/blocks/audio/theme.css 134 B
build/block-library/blocks/avatar/editor-rtl.css 115 B
build/block-library/blocks/avatar/editor.css 115 B
build/block-library/blocks/avatar/style-rtl.css 104 B
build/block-library/blocks/avatar/style.css 104 B
build/block-library/blocks/button/editor-rtl.css 310 B
build/block-library/blocks/button/editor.css 310 B
build/block-library/blocks/button/style-rtl.css 538 B
build/block-library/blocks/button/style.css 538 B
build/block-library/blocks/buttons/editor-rtl.css 336 B
build/block-library/blocks/buttons/editor.css 336 B
build/block-library/blocks/buttons/style-rtl.css 328 B
build/block-library/blocks/buttons/style.css 328 B
build/block-library/blocks/calendar/style-rtl.css 240 B
build/block-library/blocks/calendar/style.css 240 B
build/block-library/blocks/categories/editor-rtl.css 132 B
build/block-library/blocks/categories/editor.css 131 B
build/block-library/blocks/categories/style-rtl.css 152 B
build/block-library/blocks/categories/style.css 152 B
build/block-library/blocks/code/editor-rtl.css 53 B
build/block-library/blocks/code/editor.css 53 B
build/block-library/blocks/code/style-rtl.css 121 B
build/block-library/blocks/code/style.css 121 B
build/block-library/blocks/code/theme-rtl.css 122 B
build/block-library/blocks/code/theme.css 122 B
build/block-library/blocks/columns/editor-rtl.css 108 B
build/block-library/blocks/columns/editor.css 108 B
build/block-library/blocks/columns/style-rtl.css 420 B
build/block-library/blocks/columns/style.css 420 B
build/block-library/blocks/comment-author-avatar/editor-rtl.css 124 B
build/block-library/blocks/comment-author-avatar/editor.css 124 B
build/block-library/blocks/comment-content/style-rtl.css 90 B
build/block-library/blocks/comment-content/style.css 90 B
build/block-library/blocks/comment-date/style-rtl.css 65 B
build/block-library/blocks/comment-date/style.css 65 B
build/block-library/blocks/comment-template/style-rtl.css 200 B
build/block-library/blocks/comment-template/style.css 199 B
build/block-library/blocks/comments-pagination-numbers/editor-rtl.css 122 B
build/block-library/blocks/comments-pagination-numbers/editor.css 121 B
build/block-library/blocks/comments-pagination/editor-rtl.css 221 B
build/block-library/blocks/comments-pagination/editor.css 211 B
build/block-library/blocks/comments-pagination/style-rtl.css 234 B
build/block-library/blocks/comments-pagination/style.css 231 B
build/block-library/blocks/comments-title/editor-rtl.css 75 B
build/block-library/blocks/comments-title/editor.css 75 B
build/block-library/blocks/comments/editor-rtl.css 832 B
build/block-library/blocks/comments/editor.css 832 B
build/block-library/blocks/comments/style-rtl.css 632 B
build/block-library/blocks/comments/style.css 631 B
build/block-library/blocks/cover/editor-rtl.css 668 B
build/block-library/blocks/cover/editor.css 669 B
build/block-library/blocks/cover/style-rtl.css 1.62 kB
build/block-library/blocks/cover/style.css 1.6 kB
build/block-library/blocks/details/editor-rtl.css 65 B
build/block-library/blocks/details/editor.css 65 B
build/block-library/blocks/details/style-rtl.css 86 B
build/block-library/blocks/details/style.css 86 B
build/block-library/blocks/embed/editor-rtl.css 314 B
build/block-library/blocks/embed/editor.css 314 B
build/block-library/blocks/embed/style-rtl.css 419 B
build/block-library/blocks/embed/style.css 419 B
build/block-library/blocks/embed/theme-rtl.css 133 B
build/block-library/blocks/embed/theme.css 133 B
build/block-library/blocks/file/editor-rtl.css 326 B
build/block-library/blocks/file/editor.css 326 B
build/block-library/blocks/file/style-rtl.css 278 B
build/block-library/blocks/file/style.css 279 B
build/block-library/blocks/file/view.min.js 324 B
build/block-library/blocks/footnotes/style-rtl.css 198 B
build/block-library/blocks/footnotes/style.css 197 B
build/block-library/blocks/form-input/editor-rtl.css 229 B
build/block-library/blocks/form-input/editor.css 229 B
build/block-library/blocks/form-input/style-rtl.css 342 B
build/block-library/blocks/form-input/style.css 342 B
build/block-library/blocks/form-submission-notification/editor-rtl.css 344 B
build/block-library/blocks/form-submission-notification/editor.css 341 B
build/block-library/blocks/form-submit-button/style-rtl.css 69 B
build/block-library/blocks/form-submit-button/style.css 69 B
build/block-library/blocks/form/view.min.js 470 B
build/block-library/blocks/freeform/editor-rtl.css 2.6 kB
build/block-library/blocks/freeform/editor.css 2.6 kB
build/block-library/blocks/gallery/editor-rtl.css 955 B
build/block-library/blocks/gallery/editor.css 958 B
build/block-library/blocks/gallery/style-rtl.css 1.71 kB
build/block-library/blocks/gallery/style.css 1.71 kB
build/block-library/blocks/gallery/theme-rtl.css 108 B
build/block-library/blocks/gallery/theme.css 108 B
build/block-library/blocks/group/editor-rtl.css 344 B
build/block-library/blocks/group/editor.css 344 B
build/block-library/blocks/group/style-rtl.css 103 B
build/block-library/blocks/group/style.css 103 B
build/block-library/blocks/group/theme-rtl.css 79 B
build/block-library/blocks/group/theme.css 79 B
build/block-library/blocks/heading/style-rtl.css 188 B
build/block-library/blocks/heading/style.css 188 B
build/block-library/blocks/html/editor-rtl.css 346 B
build/block-library/blocks/html/editor.css 347 B
build/block-library/blocks/image/editor-rtl.css 894 B
build/block-library/blocks/image/editor.css 892 B
build/block-library/blocks/image/style-rtl.css 1.59 kB
build/block-library/blocks/image/style.css 1.59 kB
build/block-library/blocks/image/theme-rtl.css 137 B
build/block-library/blocks/image/theme.css 137 B
build/block-library/blocks/image/view.min.js 1.65 kB
build/block-library/blocks/latest-comments/style-rtl.css 355 B
build/block-library/blocks/latest-comments/style.css 354 B
build/block-library/blocks/latest-posts/editor-rtl.css 139 B
build/block-library/blocks/latest-posts/editor.css 138 B
build/block-library/blocks/latest-posts/style-rtl.css 509 B
build/block-library/blocks/latest-posts/style.css 510 B
build/block-library/blocks/list/style-rtl.css 107 B
build/block-library/blocks/list/style.css 107 B
build/block-library/blocks/loginout/style-rtl.css 61 B
build/block-library/blocks/loginout/style.css 61 B
build/block-library/blocks/media-text/editor-rtl.css 304 B
build/block-library/blocks/media-text/editor.css 303 B
build/block-library/blocks/media-text/style-rtl.css 516 B
build/block-library/blocks/media-text/style.css 515 B
build/block-library/blocks/more/editor-rtl.css 427 B
build/block-library/blocks/more/editor.css 427 B
build/block-library/blocks/navigation-link/editor-rtl.css 663 B
build/block-library/blocks/navigation-link/editor.css 664 B
build/block-library/blocks/navigation-link/style-rtl.css 192 B
build/block-library/blocks/navigation-link/style.css 191 B
build/block-library/blocks/navigation-submenu/editor-rtl.css 295 B
build/block-library/blocks/navigation-submenu/editor.css 294 B
build/block-library/blocks/navigation/editor-rtl.css 2.18 kB
build/block-library/blocks/navigation/editor.css 2.19 kB
build/block-library/blocks/navigation/style-rtl.css 2.25 kB
build/block-library/blocks/navigation/style.css 2.23 kB
build/block-library/blocks/navigation/view.min.js 1.03 kB
build/block-library/blocks/nextpage/editor-rtl.css 392 B
build/block-library/blocks/nextpage/editor.css 392 B
build/block-library/blocks/page-list/editor-rtl.css 378 B
build/block-library/blocks/page-list/editor.css 378 B
build/block-library/blocks/page-list/style-rtl.css 175 B
build/block-library/blocks/page-list/style.css 175 B
build/block-library/blocks/paragraph/editor-rtl.css 236 B
build/block-library/blocks/paragraph/editor.css 236 B
build/block-library/blocks/paragraph/style-rtl.css 341 B
build/block-library/blocks/paragraph/style.css 340 B
build/block-library/blocks/post-author/style-rtl.css 175 B
build/block-library/blocks/post-author/style.css 176 B
build/block-library/blocks/post-comments-form/editor-rtl.css 96 B
build/block-library/blocks/post-comments-form/editor.css 96 B
build/block-library/blocks/post-comments-form/style-rtl.css 527 B
build/block-library/blocks/post-comments-form/style.css 528 B
build/block-library/blocks/post-content/editor-rtl.css 74 B
build/block-library/blocks/post-content/editor.css 74 B
build/block-library/blocks/post-content/style-rtl.css 79 B
build/block-library/blocks/post-content/style.css 79 B
build/block-library/blocks/post-date/style-rtl.css 62 B
build/block-library/blocks/post-date/style.css 62 B
build/block-library/blocks/post-excerpt/editor-rtl.css 71 B
build/block-library/blocks/post-excerpt/editor.css 71 B
build/block-library/blocks/post-excerpt/style-rtl.css 155 B
build/block-library/blocks/post-excerpt/style.css 155 B
build/block-library/blocks/post-featured-image/editor-rtl.css 729 B
build/block-library/blocks/post-featured-image/editor.css 726 B
build/block-library/blocks/post-featured-image/style-rtl.css 341 B
build/block-library/blocks/post-featured-image/style.css 341 B
build/block-library/blocks/post-navigation-link/style-rtl.css 215 B
build/block-library/blocks/post-navigation-link/style.css 214 B
build/block-library/blocks/post-template/editor-rtl.css 99 B
build/block-library/blocks/post-template/editor.css 98 B
build/block-library/blocks/post-template/style-rtl.css 399 B
build/block-library/blocks/post-template/style.css 398 B
build/block-library/blocks/post-terms/style-rtl.css 96 B
build/block-library/blocks/post-terms/style.css 96 B
build/block-library/blocks/post-time-to-read/style-rtl.css 70 B
build/block-library/blocks/post-time-to-read/style.css 70 B
build/block-library/blocks/post-title/style-rtl.css 100 B
build/block-library/blocks/post-title/style.css 100 B
build/block-library/blocks/preformatted/style-rtl.css 125 B
build/block-library/blocks/preformatted/style.css 125 B
build/block-library/blocks/pullquote/editor-rtl.css 134 B
build/block-library/blocks/pullquote/editor.css 134 B
build/block-library/blocks/pullquote/style-rtl.css 342 B
build/block-library/blocks/pullquote/style.css 342 B
build/block-library/blocks/pullquote/theme-rtl.css 167 B
build/block-library/blocks/pullquote/theme.css 167 B
build/block-library/blocks/query-pagination-numbers/editor-rtl.css 121 B
build/block-library/blocks/query-pagination-numbers/editor.css 118 B
build/block-library/blocks/query-pagination/editor-rtl.css 220 B
build/block-library/blocks/query-pagination/editor.css 208 B
build/block-library/blocks/query-pagination/style-rtl.css 287 B
build/block-library/blocks/query-pagination/style.css 283 B
build/block-library/blocks/query-title/style-rtl.css 64 B
build/block-library/blocks/query-title/style.css 64 B
build/block-library/blocks/query/editor-rtl.css 452 B
build/block-library/blocks/query/editor.css 451 B
build/block-library/blocks/query/view.min.js 958 B
build/block-library/blocks/quote/style-rtl.css 238 B
build/block-library/blocks/quote/style.css 238 B
build/block-library/blocks/quote/theme-rtl.css 233 B
build/block-library/blocks/quote/theme.css 236 B
build/block-library/blocks/read-more/style-rtl.css 138 B
build/block-library/blocks/read-more/style.css 138 B
build/block-library/blocks/rss/editor-rtl.css 101 B
build/block-library/blocks/rss/editor.css 101 B
build/block-library/blocks/rss/style-rtl.css 288 B
build/block-library/blocks/rss/style.css 287 B
build/block-library/blocks/search/editor-rtl.css 199 B
build/block-library/blocks/search/editor.css 199 B
build/block-library/blocks/search/style-rtl.css 672 B
build/block-library/blocks/search/style.css 671 B
build/block-library/blocks/search/theme-rtl.css 113 B
build/block-library/blocks/search/theme.css 113 B
build/block-library/blocks/search/view.min.js 475 B
build/block-library/blocks/separator/editor-rtl.css 100 B
build/block-library/blocks/separator/editor.css 100 B
build/block-library/blocks/separator/style-rtl.css 248 B
build/block-library/blocks/separator/style.css 248 B
build/block-library/blocks/separator/theme-rtl.css 195 B
build/block-library/blocks/separator/theme.css 195 B
build/block-library/blocks/shortcode/editor-rtl.css 286 B
build/block-library/blocks/shortcode/editor.css 286 B
build/block-library/blocks/site-logo/editor-rtl.css 806 B
build/block-library/blocks/site-logo/editor.css 803 B
build/block-library/blocks/site-logo/style-rtl.css 218 B
build/block-library/blocks/site-logo/style.css 218 B
build/block-library/blocks/site-tagline/editor-rtl.css 87 B
build/block-library/blocks/site-tagline/editor.css 87 B
build/block-library/blocks/site-tagline/style-rtl.css 65 B
build/block-library/blocks/site-tagline/style.css 65 B
build/block-library/blocks/site-title/editor-rtl.css 123 B
build/block-library/blocks/site-title/editor.css 123 B
build/block-library/blocks/site-title/style-rtl.css 90 B
build/block-library/blocks/site-title/style.css 90 B
build/block-library/blocks/social-link/editor-rtl.css 338 B
build/block-library/blocks/social-link/editor.css 338 B
build/block-library/blocks/social-links/editor-rtl.css 676 B
build/block-library/blocks/social-links/editor.css 675 B
build/block-library/blocks/social-links/style-rtl.css 1.51 kB
build/block-library/blocks/social-links/style.css 1.5 kB
build/block-library/blocks/spacer/editor-rtl.css 346 B
build/block-library/blocks/spacer/editor.css 346 B
build/block-library/blocks/spacer/style-rtl.css 48 B
build/block-library/blocks/spacer/style.css 48 B
build/block-library/blocks/table-of-contents/style-rtl.css 83 B
build/block-library/blocks/table-of-contents/style.css 83 B
build/block-library/blocks/table/editor-rtl.css 394 B
build/block-library/blocks/table/editor.css 394 B
build/block-library/blocks/table/style-rtl.css 640 B
build/block-library/blocks/table/style.css 639 B
build/block-library/blocks/table/theme-rtl.css 152 B
build/block-library/blocks/table/theme.css 152 B
build/block-library/blocks/tag-cloud/editor-rtl.css 144 B
build/block-library/blocks/tag-cloud/editor.css 144 B
build/block-library/blocks/tag-cloud/style-rtl.css 266 B
build/block-library/blocks/tag-cloud/style.css 265 B
build/block-library/blocks/template-part/editor-rtl.css 393 B
build/block-library/blocks/template-part/editor.css 393 B
build/block-library/blocks/template-part/theme-rtl.css 113 B
build/block-library/blocks/template-part/theme.css 113 B
build/block-library/blocks/term-description/style-rtl.css 126 B
build/block-library/blocks/term-description/style.css 126 B
build/block-library/blocks/text-columns/editor-rtl.css 95 B
build/block-library/blocks/text-columns/editor.css 95 B
build/block-library/blocks/text-columns/style-rtl.css 165 B
build/block-library/blocks/text-columns/style.css 165 B
build/block-library/blocks/verse/style-rtl.css 98 B
build/block-library/blocks/verse/style.css 98 B
build/block-library/blocks/video/editor-rtl.css 541 B
build/block-library/blocks/video/editor.css 542 B
build/block-library/blocks/video/style-rtl.css 192 B
build/block-library/blocks/video/style.css 192 B
build/block-library/blocks/video/theme-rtl.css 134 B
build/block-library/blocks/video/theme.css 134 B
build/block-library/classic-rtl.css 179 B
build/block-library/classic.css 179 B
build/block-library/common-rtl.css 1.1 kB
build/block-library/common.css 1.1 kB
build/block-library/editor-elements-rtl.css 75 B
build/block-library/editor-elements.css 75 B
build/block-library/editor-rtl.css 11.9 kB
build/block-library/editor.css 11.9 kB
build/block-library/elements-rtl.css 54 B
build/block-library/elements.css 54 B
build/block-library/index.min.js 217 kB
build/block-library/reset-rtl.css 472 B
build/block-library/reset.css 472 B
build/block-library/style-rtl.css 14.7 kB
build/block-library/style.css 14.7 kB
build/block-library/theme-rtl.css 708 B
build/block-library/theme.css 712 B
build/block-serialization-default-parser/index.min.js 1.12 kB
build/block-serialization-spec-parser/index.min.js 2.87 kB
build/blocks/index.min.js 52.4 kB
build/commands/index.min.js 16.1 kB
build/commands/style-rtl.css 955 B
build/commands/style.css 952 B
build/components/index.min.js 223 kB
build/components/style-rtl.css 12.1 kB
build/components/style.css 12.1 kB
build/compose/index.min.js 12.9 kB
build/core-commands/index.min.js 2.82 kB
build/core-data/index.min.js 73.1 kB
build/customize-widgets/index.min.js 11 kB
build/customize-widgets/style-rtl.css 1.35 kB
build/customize-widgets/style.css 1.35 kB
build/data-controls/index.min.js 641 B
build/data/index.min.js 8.98 kB
build/date/index.min.js 18 kB
build/deprecated/index.min.js 458 B
build/dom-ready/index.min.js 325 B
build/dom/index.min.js 4.65 kB
build/edit-post/classic-rtl.css 578 B
build/edit-post/classic.css 580 B
build/edit-post/index.min.js 12.6 kB
build/edit-post/style-rtl.css 2.31 kB
build/edit-post/style.css 2.31 kB
build/edit-site/posts-rtl.css 7.41 kB
build/edit-site/posts.css 7.41 kB
build/edit-site/style-rtl.css 12.7 kB
build/edit-site/style.css 12.7 kB
build/edit-widgets/index.min.js 17.7 kB
build/edit-widgets/style-rtl.css 4.2 kB
build/edit-widgets/style.css 4.2 kB
build/editor/style-rtl.css 9.36 kB
build/editor/style.css 9.35 kB
build/element/index.min.js 4.83 kB
build/escape-html/index.min.js 537 B
build/format-library/index.min.js 8.09 kB
build/format-library/style-rtl.css 476 B
build/format-library/style.css 476 B
build/hooks/index.min.js 1.54 kB
build/html-entities/index.min.js 445 B
build/i18n/index.min.js 3.58 kB
build/interactivity/debug.min.js 16.3 kB
build/interactivity/file.min.js 447 B
build/interactivity/image.min.js 1.78 kB
build/interactivity/index.min.js 13.2 kB
build/interactivity/navigation.min.js 1.16 kB
build/interactivity/query.min.js 742 B
build/interactivity/router.min.js 2.8 kB
build/interactivity/search.min.js 615 B
build/is-shallow-equal/index.min.js 526 B
build/keyboard-shortcuts/index.min.js 1.31 kB
build/keycodes/index.min.js 1.46 kB
build/list-reusable-blocks/index.min.js 2.16 kB
build/list-reusable-blocks/style-rtl.css 846 B
build/list-reusable-blocks/style.css 846 B
build/media-utils/index.min.js 2.92 kB
build/modules/importmap-polyfill.min.js 12.3 kB
build/notices/index.min.js 946 B
build/nux/index.min.js 1.59 kB
build/nux/style-rtl.css 749 B
build/nux/style.css 745 B
build/patterns/index.min.js 7.37 kB
build/patterns/style-rtl.css 687 B
build/patterns/style.css 685 B
build/plugins/index.min.js 1.81 kB
build/preferences-persistence/index.min.js 2.06 kB
build/preferences/index.min.js 2.9 kB
build/preferences/style-rtl.css 554 B
build/preferences/style.css 554 B
build/primitives/index.min.js 829 B
build/priority-queue/index.min.js 1.54 kB
build/private-apis/index.min.js 1.01 kB
build/react-i18n/index.min.js 630 B
build/react-refresh-entry/index.min.js 9.47 kB
build/react-refresh-runtime/index.min.js 6.76 kB
build/redux-routine/index.min.js 2.69 kB
build/reusable-blocks/index.min.js 2.54 kB
build/reusable-blocks/style-rtl.css 256 B
build/reusable-blocks/style.css 256 B
build/rich-text/index.min.js 10.1 kB
build/router/index.min.js 1.96 kB
build/server-side-render/index.min.js 1.94 kB
build/shortcode/index.min.js 1.4 kB
build/style-engine/index.min.js 2.03 kB
build/token-list/index.min.js 581 B
build/url/index.min.js 3.85 kB
build/vendors/react-dom.min.js 41.7 kB
build/vendors/react-jsx-runtime.min.js 560 B
build/vendors/react.min.js 4.02 kB
build/viewport/index.min.js 965 B
build/warning/index.min.js 250 B
build/widgets/index.min.js 7.19 kB
build/widgets/style-rtl.css 1.16 kB
build/widgets/style.css 1.16 kB
build/wordcount/index.min.js 1.03 kB

compressed-size-action

@Aljullu
Aljullu force-pushed the add/plugin-template-registration-api branch 6 times, most recently from f3d4e5a to 03c90ff Compare May 10, 2024 16:15
@Aljullu
Aljullu force-pushed the add/plugin-template-registration-api branch 2 times, most recently from 2fa0a91 to 1390923 Compare May 15, 2024 13:49
@github-actions

github-actions Bot commented May 15, 2024 •

Copy link
Copy Markdown

This pull request has changed or added PHP files. Please confirm whether these changes need to be synced to WordPress Core, and therefore featured in the next release of WordPress.

If so, it is recommended to create a new Trac ticket and submit a pull request to the WordPress Core Github repository soon after this pull request is merged.

If you're unsure, you can always ask for help in the #core-editor channel in WordPress Slack.

Thank you! ❤️

View changed files
❔ lib/block-templates.php
❔ lib/class-wp-block-templates-registry.php
❔ lib/compat/wordpress-6.7/class-gutenberg-rest-templates-controller-6-7.php
❔ lib/compat/wordpress-6.7/compat.php
❔ lib/compat/wordpress-6.7/rest-api.php
❔ lib/load.php

@Aljullu
Aljullu force-pushed the add/plugin-template-registration-api branch 2 times, most recently from da50079 to b244dc9 Compare May 21, 2024 12:29
@github-actions

github-actions Bot commented May 21, 2024 •

Copy link
Copy Markdown

Flaky tests detected in ae59c2c.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/9682409402
📝 Reported issues:

@Aljullu
Aljullu force-pushed the add/plugin-template-registration-api branch 2 times, most recently from 1c13545 to 54d2199 Compare May 21, 2024 13:30
@Aljullu

Aljullu commented May 21, 2024

Copy link
Copy Markdown
Contributor Author

@youknowriad @ntsekouras this PR is still missing tests and documentation, but feature-wise everything should be working, so I would really appreciate it if you could take a look and tell me whether this approach looks good or not. 🙏

In #41401, there were some proposals of next steps, but for now I'm keeping the PR small, only introducing the basic API. This way we can iterate on it in the future.

@youknowriad

Copy link
Copy Markdown
Contributor

Looking at the shape of the API. The first thing that comes to my mind is whether we should keep the "path" argument or replace it with a "content" argument instead that could be more flexible? I didn't give it too much thoughts though, and would appreciate opinions.

@youknowriad

Copy link
Copy Markdown
Contributor

It would be great to get a lot of eyes on this PR, specially from folks familiar with Core and PHP @WordPress/gutenberg-core

@youknowriad

Copy link
Copy Markdown
Contributor

I would love if we can think of a declarative way to actually absorb the category_template_hierarchy and similar hooks.

@youknowriad youknowriad added [Feature] Extensibility The ability to extend blocks or the editing experience [Type] New API New API to be used by plugin developers or package users. labels May 21, 2024
@Aljullu

Aljullu commented May 22, 2024

Copy link
Copy Markdown
Contributor Author

Thanks for taking a look, @youknowriad!

Looking at the shape of the API. The first thing that comes to my mind is whether we should keep the "path" argument or replace it with a "content" argument instead that could be more flexible? I didn't give it too much thoughts though, and would appreciate opinions.

Good point! I initially started with the path approach, but the more I progressed the less convinced I was about it. I also think content is a better approach as it gives more flexibility to the consumer. I just made the change in the last commit and updated the PR testing steps.

I would love if we can think of a declarative way to actually absorb the category_template_hierarchy and similar hooks.

You mean doing it as part of the template registration API or as a follow-up? I'm a bit wary of having a big scope for the first version of the API.

Even though in the testing steps I added a template_hierarchy filter to test, it's not really required in order to use the template registration API. A valid use case is a consumer registering a template with specific post_types, without the need of hooking into template_hierarchy.

@youknowriad

Copy link
Copy Markdown
Contributor

I guess it's fine as a follow-up, so you're saying that by default these registered templates will serve as "custom templates" you can assign to posts/pages... right?

@ellatrix

Copy link
Copy Markdown
Member

Is this meant to be a GB only experimental API for now?

@youknowriad

Copy link
Copy Markdown
Contributor

@ellatrix For me at least, this shouldn't land in 6.6, we need a bit of time to iron things out properly.

@Aljullu

Aljullu commented May 23, 2024

Copy link
Copy Markdown
Contributor Author

I guess it's fine as a follow-up, so you're saying that by default these registered templates will serve as "custom templates" you can assign to posts/pages... right?

Yes, exactly. With the example code defining 'post_types' => array( 'post' ), the template can be selected from the Swap template screen in the post editor:

image

@fabiankaegy fabiankaegy mentioned this pull request Oct 1, 2024
95 of 97 tasks
@daviedR

daviedR commented Oct 3, 2024

Copy link
Copy Markdown
Contributor

I am just curious, why is it named wp_register_block_template instead of register_block_template?

We have other APIs with similar naming, such as: register_block_type, register_block_pattern, register_block_style, etc.

I think register_block_template sounds more consistent.

@widoz

widoz commented Oct 3, 2024 •

Copy link
Copy Markdown
Contributor

I am just curious, why is it named wp_register_block_template instead of register_block_template?

We have other APIs with similar naming, such as: register_block_type, register_block_pattern, register_block_style, etc.

I think register_block_template sounds more consistent.

Since WP do not use Namespaces shouldn't all functions be prefixed with wp_ ?

@ajgagnon

ajgagnon commented Oct 4, 2024

Copy link
Copy Markdown

I think the wp_ namespace should definitely be dropped to fall in line with the other functions.

@youknowriad

Copy link
Copy Markdown
Contributor

I agree it feels weird that the wp_ exists in these functions but not the other block related registration functions (styles, patterns, blocks...). I don't recall the exact reasoning for that? Any ideas @peterwilsoncc @ntsekouras @mcsf and do we still have time to try and remove that?

@peterwilsoncc

Copy link
Copy Markdown
Contributor

I agree it's best to be consistent. I think we have time to drop the prefix.

@youknowriad It's possible I suggested it (can't remember but it's the sort of thing I'd do 😄) but that would have been ignorance of convention if I did so. It would be nice if they all had the wp_ prefix but the opportunity has been missed.

@getdave

getdave commented Oct 8, 2024

Copy link
Copy Markdown
Contributor

Possibly due to this documentation

https://github.com/WordPress/gutenberg/blob/trunk/lib/README.md#using-gutenberg-suffixesprefixes-vs-wp-prefixes

Specifically

When porting new functions into Core, the function must be renamed to use the wp_ prefix for functions or a WP_ prefix for classes.

Do we need to update that documentation or add qualifiers/exceptions to the rules?

@ajgagnon

ajgagnon commented Oct 8, 2024 •

Copy link
Copy Markdown

Is it possible to register a wp_template_part or is this just for wp_templates?

@youknowriad

Copy link
Copy Markdown
Contributor

Do we need to update that documentation or add qualifiers/exceptions to the rules?

It's very hard to come up with a good rule. But yeah for this case (registration functions) it seems better to avoid the prefix.

Is it possible to register a wp_template_part or is this just for wp_templates?

We want to ultimately absorb template parts in patterns and patterns already have registration API.


Can anyone help with the renaming work?

@Aljullu

Aljullu commented Oct 8, 2024

Copy link
Copy Markdown
Contributor Author

Thanks for the feedback, folks!

Can anyone help with the renaming work?

I opened a PR in Gutenberg (#65958) and WP core (WordPress/wordpress-develop#7543). I'm not sure how backwards compatibility needs to be handled in this case, considering this wasn't released in WP core. I assume we don't need to worry about backwards compatibility in WP, but what about Gutenberg, is it safe to simply rename the function, or should we keep the old names and mark them as deprecated?

@andrewserong

Copy link
Copy Markdown
Contributor

I assume we don't need to worry about backwards compatibility in WP, but what about Gutenberg, is it safe to simply rename the function, or should we keep the old names and mark them as deprecated?

Keeping the old names and deprecating in Gutenberg (but simply renaming in core) sounds like a good approach to me! Here's an example of another place in Gutenberg where there are deprecated functions, in case it helps:

/**
* Unmarks the module so it is not longer enqueued in the page.
*
* @deprecated 17.6.0 gutenberg_dequeue_module is deprecated. Please use wp_dequeue_script_module instead.
*
* @param string $module_identifier The identifier of the module.
*/
function gutenberg_dequeue_module( $module_identifier ) {
_deprecated_function( __FUNCTION__, 'Gutenberg 17.6.0', 'wp_dequeue_script_module' );
wp_script_modules()->dequeue( $module_identifier );
}

@Aljullu

Aljullu commented Oct 8, 2024

Copy link
Copy Markdown
Contributor Author

Thanks, @andrewserong! I updated #65958 accordingly. 🙂

@daviedR

daviedR commented Oct 9, 2024

Copy link
Copy Markdown
Contributor

Is it possible to register a wp_template_part or is this just for wp_templates?

@ajgagnon I created a separate issue for this here: #65861

The core has the get_block_templates function (and the get_block_templates filter) which works for both wp_template and wp_template_part types. So, it looks like wp_template and wp_template_part have similar data structures.

It might be possible to use the new register_block_template API to also register wp_template_part type as well.


We want to ultimately absorb template parts in patterns and patterns already have registration API.

@youknowriad Do you mean that template parts will become patterns in the future?

@youknowriad

Copy link
Copy Markdown
Contributor

Do you mean that template parts will become patterns in the future?

For me, yes, Read this following link where I detail my thinking.

#62566 (comment)

@mcsf

mcsf commented Oct 9, 2024

Copy link
Copy Markdown
Contributor

I agree it feels weird that the wp_ exists in these functions but not the other block related registration functions (styles, patterns, blocks...). I don't recall the exact reasoning for that? Any ideas peterwilsoncc ntsekouras mcsf and do we still have time to try and remove that?

Agreed with dropping the wp_, and it seems there's still time.

@helgatheviking

Copy link
Copy Markdown
Contributor

Does register_block_template() also include registering template parts? Is there a distinction?

@youknowriad

Copy link
Copy Markdown
Contributor

@helgatheviking See answer above #61577 (comment)

aslamdoctor pushed a commit to aslamdoctor/wordpress-develop that referenced this pull request Dec 28, 2024
…des for plugin-registered templates

This commit introduces a new API to allow plugins to easily register block
templates with `wp_register_block_template()` and the
`WP_Block_Templates_Registry` class, addressing the complexity of hooking into
multiple filters. It also ensures plugin-registered templates overridden by
themes fall back to the plugin-provided title and description when the theme
doesn't define them.

See WordPress/gutenberg#61577.
See WordPress/gutenberg#64610.

Fixes #61804.
Props aljullu, peterwilsoncc, antonvlasenko, azaozz, youknowriad, noisysocks.


git-svn-id: https://develop.svn.wordpress.org/trunk@59073 602fd350-edb4-49c9-b593-d223f7449a82
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Feature] Extensibility The ability to extend blocks or the editing experience has dev note when dev note is done (for upcoming WordPress release) [Type] New API New API to be used by plugin developers or package users.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Extending available templates via plugins