Editor: Add plugin template registration API and improve theme overrides 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

Author: noisysocks

src/wp-includes/block-template-utils.php

@@ -592,6 +592,15 @@ function _build_block_template_result_from_file( $template_file, $template_type
 	$template->is_custom      = true;
 	$template->modified       = null;
 
+	if ( 'wp_template' === $template_type ) {
+		$registered_template = WP_Block_Templates_Registry::get_instance()->get_by_slug( $template_file['slug'] );
+		if ( $registered_template ) {
+			$template->plugin      = $registered_template->plugin;
+			$template->title       = empty( $template->title ) || $template->title === $template->slug ? $registered_template->title : $template->title;
+			$template->description = empty( $template->description ) ? $registered_template->description : $template->description;
+		}
+	}
+
 	if ( 'wp_template' === $template_type && isset( $default_template_types[ $template_file['slug'] ] ) ) {
 		$template->description = $default_template_types[ $template_file['slug'] ]['description'];
 		$template->title       = $default_template_types[ $template_file['slug'] ]['title'];
@@ -1014,6 +1023,19 @@ function _build_block_template_result_from_post( $post ) {
 		}
 	}
 
+	if ( 'wp_template' === $post->post_type ) {
+		$registered_template = WP_Block_Templates_Registry::get_instance()->get_by_slug( $template->slug );
+		if ( $registered_template ) {
+			$template->plugin      = $registered_template->plugin;
+			$template->origin      =
+				'theme' !== $template->origin && 'theme' !== $template->source ?
+				'plugin' :
+				$template->origin;
+			$template->title       = empty( $template->title ) || $template->title === $template->slug ? $registered_template->title : $template->title;
+			$template->description = empty( $template->description ) ? $registered_template->description : $template->description;
+		}
+	}
+
 	$hooked_blocks = get_hooked_blocks();
 	if ( ! empty( $hooked_blocks ) || has_filter( 'hooked_block_types' ) ) {
 		$before_block_visitor = make_before_block_visitor( $hooked_blocks, $template, 'insert_hooked_blocks_and_set_ignored_hooked_blocks_metadata' );
@@ -1157,6 +1179,23 @@ function get_block_templates( $query = array(), $template_type = 'wp_template' )
 		foreach ( $template_files as $template_file ) {
 			$query_result[] = _build_block_template_result_from_file( $template_file, $template_type );
 		}
+
+		if ( 'wp_template' === $template_type ) {
+			// Add templates registered in the template registry. Filtering out the ones which have a theme file.
+			$registered_templates          = WP_Block_Templates_Registry::get_instance()->get_by_query( $query );
+			$matching_registered_templates = array_filter(
+				$registered_templates,
+				function ( $registered_template ) use ( $template_files ) {
+					foreach ( $template_files as $template_file ) {
+						if ( $template_file['slug'] === $registered_template->slug ) {
+							return false;
+						}
+					}
+					return true;
+				}
+			);
+			$query_result                  = array_merge( $query_result, $matching_registered_templates );
+		}
 	}
 
 	/**
@@ -1287,18 +1326,17 @@ function get_block_file_template( $id, $template_type = 'wp_template' ) {
 	}
 	list( $theme, $slug ) = $parts;
 
-	if ( get_stylesheet() !== $theme ) {
-		/** This filter is documented in wp-includes/block-template-utils.php */
-		return apply_filters( 'get_block_file_template', null, $id, $template_type );
-	}
+	if ( get_stylesheet() === $theme ) {
+		$template_file = _get_block_template_file( $template_type, $slug );
+		if ( null !== $template_file ) {
+			$block_template = _build_block_template_result_from_file( $template_file, $template_type );
 
-	$template_file = _get_block_template_file( $template_type, $slug );
-	if ( null === $template_file ) {
-		/** This filter is documented in wp-includes/block-template-utils.php */
-		return apply_filters( 'get_block_file_template', null, $id, $template_type );
+			/** This filter is documented in wp-includes/block-template-utils.php */
+			return apply_filters( 'get_block_file_template', $block_template, $id, $template_type );
+		}
 	}
 
-	$block_template = _build_block_template_result_from_file( $template_file, $template_type );
+	$block_template = WP_Block_Templates_Registry::get_instance()->get_by_slug( $slug );
 
 	/**
 	 * Filters the block template object after it has been (potentially) fetched from the theme file.
@@ -1665,12 +1703,12 @@ function inject_ignored_hooked_blocks_metadata_attributes( $changes, $deprecated
 			);
 		}
 
-		$content = get_comment_delimited_block_content(
+		$content               = get_comment_delimited_block_content(
 			'core/template-part',
 			$attributes,
 			$changes->post_content
 		);
-		$content = apply_block_hooks_to_content( $content, $template, 'set_ignored_hooked_blocks_metadata' );
+		$content               = apply_block_hooks_to_content( $content, $template, 'set_ignored_hooked_blocks_metadata' );
 		$changes->post_content = remove_serialized_parent_block( $content );
 
 		$wrapper_block_markup  = extract_serialized_parent_block( $content );

src/wp-includes/block-template.php

@@ -358,3 +358,38 @@ function _resolve_template_for_new_post( $wp_query ) {
 		$wp_query->set( 'post_status', 'auto-draft' );
 	}
 }
+
+/**
+ * Register a block template.
+ *
+ * @since 6.7.0
+ *
+ * @param string       $template_name  Template name in the form of `plugin_uri//template_name`.
+ * @param array|string $args           {
+ *     @type string        $title                 Optional. Title of the template as it will be shown in the Site Editor
+ *                                                and other UI elements.
+ *     @type string        $description           Optional. Description of the template as it will be shown in the Site
+ *                                                Editor.
+ *     @type string        $content               Optional. Default content of the template that will be used when the
+ *                                                template is rendered or edited in the editor.
+ *     @type string[]      $post_types            Optional. Array of post types to which the template should be available.
+ *     @type string        $plugin                Optional. Slug of the plugin that registers the template.
+ * }
+ * @return WP_Block_Template|WP_Error The registered template object on success, WP_Error object on failure.
+ */
+function wp_register_block_template( $template_name, $args = array() ) {
+	return WP_Block_Templates_Registry::get_instance()->register( $template_name, $args );
+}
+
+/**
+ * Unregister a block template.
+ *
+ * @since 6.7.0
+ *
+ * @param string $template_name Template name in the form of `plugin_uri//template_name`.
+ * @return WP_Block_Template|WP_Error The unregistered template object on success, WP_Error object on failure or if the
+ *                                    template doesn't exist.
+ */
+function wp_unregister_block_template( $template_name ) {
+	return WP_Block_Templates_Registry::get_instance()->unregister( $template_name );
+}

src/wp-includes/class-wp-block-template.php

@@ -131,6 +131,14 @@ class WP_Block_Template {
 	 */
 	public $author;
 
+	/**
+	 * Plugin.
+	 *
+	 * @since 6.7.0
+	 * @var string|null
+	 */
+	public $plugin;
+
 	/**
 	 * Post types.
 	 *