Make Products by category/tag/attribute fallback to the Product catalog template (#7712)

* Add archive-product to the hierarchy

* Fallback to archive-product and get titles from blocks if the templates from theme don't have one

* Rename function

* Fix comment

* Add fallbacks to the db and blocks versions

* Add missing product attribute blockified template

* Update docs

* Add comment and fix comment type on wp_template

* Replate template name if we know the template in blocks

* Add comment and fix linting error

* Fix archive-product template

* Clone the fallback template from db to show them in the template lsit

* Return the fallback template when querying for a single template

* Remove unneeded condition

* Use wp function instead of gutenberg one

* Fix tests

* Fix tests on Product Catalog templates

It was checking a single product for the customization, but it should check the /shop page

* Disable tests related with deleteAllTemplates function

Author: albarin

docs/internal-developers/templates/block-template-controller.md

@@ -36,7 +36,7 @@ This method is applied to the filter `get_block_templates`, which is executed be
 
 -   Giving our templates a user-friendly title (e.g. turning "single-product" into "Product Page").
 -   It collects all the WooCommerce templates from both the filesystem and the database (customized templates are stored in the database as posts) and adds them to the returned list.
--   In the event the theme has a `archive-product.html` template file, but not category/tag template files, it is eligible to use the `archive-product.html` file in their place. So we trick Gutenberg in thinking some templates (e.g. category/tag) have a theme file available if it is using the `archive-product.html` template, even though _technically_ the theme does not have a specific file for them.
+-   In the event the theme has a `archive-product.html` template file, but not category/tag/attribute template files, it is eligible to use the `archive-product.html` file in their place. So we trick Gutenberg in thinking some templates (e.g. category/tag/attribute) have a theme file available if it is using the `archive-product.html` template, even though _technically_ the theme does not have a specific file for them.
 -   Ensuring we do not add irrelevant WooCommerce templates in the returned list. For example, if `$query['post_type']` has a value (e.g. `product`) this means the query is requesting templates related to that specific post type, so we filter out any irrelevant ones. This _could_ be used to show/hide templates from the template dropdown on the "Edit Product" screen in WP Admin.
 
 ### Return value

src/BlockTemplatesController.php

@@ -62,15 +62,93 @@ public function __construct( Package $package ) {
 	 */
 	protected function init() {
 		add_action( 'template_redirect', array( $this, 'render_block_template' ) );
+		add_filter( 'pre_get_block_template', array( $this, 'get_block_template_fallback' ), 10, 3 );
 		add_filter( 'pre_get_block_file_template', array( $this, 'get_block_file_template' ), 10, 3 );
 		add_filter( 'get_block_templates', array( $this, 'add_block_templates' ), 10, 3 );
 		add_filter( 'current_theme_supports-block-templates', array( $this, 'remove_block_template_support_for_shop_page' ) );
+		add_filter( 'taxonomy_template_hierarchy', array( $this, 'add_archive_product_to_eligible_for_fallback_templates' ), 10, 1 );
 
 		if ( $this->package->is_experimental_build() ) {
 			add_action( 'after_switch_theme', array( $this, 'check_should_use_blockified_product_grid_templates' ), 10, 2 );
 		}
 	}
 
+	/**
+	 * This function is used on the `pre_get_block_template` hook to return the fallback template from the db in case
+	 * the template is eligible for it.
+	 *
+	 * @param \WP_Block_Template|null $template Block template object to short-circuit the default query,
+	 *                                          or null to allow WP to run its normal queries.
+	 * @param string                  $id Template unique identifier (example: theme_slug//template_slug).
+	 * @param string                  $template_type wp_template or wp_template_part.
+	 *
+	 * @return object|null
+	 */
+	public function get_block_template_fallback( $template, $id, $template_type ) {
+		$template_name_parts  = explode( '//', $id );
+		list( $theme, $slug ) = $template_name_parts;
+
+		if ( ! BlockTemplateUtils::template_is_eligible_for_product_archive_fallback( $slug ) ) {
+			return null;
+		}
+
+		$wp_query_args  = array(
+			'post_name__in'  => array( 'archive-product' ),
+			'post_type'      => $template_type,
+			'post_status'    => array( 'auto-draft', 'draft', 'publish', 'trash' ),
+			'posts_per_page' => 1,
+			'no_found_rows'  => true,
+			'tax_query'      => array( // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_tax_query
+				array(
+					'taxonomy' => 'wp_theme',
+					'field'    => 'name',
+					'terms'    => $theme,
+				),
+			),
+		);
+		$template_query = new \WP_Query( $wp_query_args );
+		$posts          = $template_query->posts;
+
+		if ( count( $posts ) > 0 ) {
+			$template = _build_block_template_result_from_post( $posts[0] );
+
+			if ( ! is_wp_error( $template ) ) {
+				$template->id          = $theme . '//' . $slug;
+				$template->slug        = $slug;
+				$template->title       = BlockTemplateUtils::get_block_template_title( $slug );
+				$template->description = BlockTemplateUtils::get_block_template_description( $slug );
+
+				return $template;
+			}
+		}
+
+		return $template;
+	}
+
+	/**
+	 * Adds the `archive-product` template to the `taxonomy-product_cat`, `taxonomy-product_tag`, `taxonomy-attribute`
+	 * templates to be able to fall back to it.
+	 *
+	 * @param array $template_hierarchy A list of template candidates, in descending order of priority.
+	 */
+	public function add_archive_product_to_eligible_for_fallback_templates( $template_hierarchy ) {
+		$template_slugs = array_map(
+			'_strip_template_file_suffix',
+			$template_hierarchy
+		);
+
+		$templates_eligible_for_fallback = array_filter(
+			$template_slugs,
+			array( BlockTemplateUtils::class, 'template_is_eligible_for_product_archive_fallback' )
+		);
+
+		if ( count( $templates_eligible_for_fallback ) > 0 ) {
+			$template_hierarchy[] = 'archive-product';
+		}
+
+		return $template_hierarchy;
+	}
+
 	/**
 	 * Checks the old and current themes and determines if the "wc_blocks_use_blockified_product_grid_block_as_template"
 	 * option need to be updated accordingly.
@@ -112,7 +190,7 @@ public function get_block_file_template( $template, $id, $template_type ) {
 		list( $template_id, $template_slug ) = $template_name_parts;
 
 		// If the theme has an archive-product.html template, but not a taxonomy-product_cat/tag/attribute.html template let's use the themes archive-product.html template.
-		if ( BlockTemplateUtils::template_is_eligible_for_product_archive_fallback( $template_slug ) ) {
+		if ( BlockTemplateUtils::template_is_eligible_for_product_archive_fallback_from_theme( $template_slug ) ) {
 			$template_path   = BlockTemplateUtils::get_theme_template_path( 'archive-product' );
 			$template_object = BlockTemplateUtils::create_new_block_template_object( $template_path, $template_type, $template_slug, true );
 			return BlockTemplateUtils::build_template_result_from_file( $template_object, $template_type );
@@ -158,9 +236,9 @@ public function get_block_file_template( $template, $id, $template_type ) {
 	/**
 	 * Add the block template objects to be used.
 	 *
-	 * @param array $query_result Array of template objects.
-	 * @param array $query Optional. Arguments to retrieve templates.
-	 * @param array $template_type wp_template or wp_template_part.
+	 * @param array  $query_result Array of template objects.
+	 * @param array  $query Optional. Arguments to retrieve templates.
+	 * @param string $template_type wp_template or wp_template_part.
 	 * @return array
 	 */
 	public function add_block_templates( $query_result, $query, $template_type ) {
@@ -229,7 +307,7 @@ public function add_block_templates( $query_result, $query, $template_type ) {
 		 */
 		$query_result = array_map(
 			function( $template ) {
-				if ( 'theme' === $template->origin ) {
+				if ( 'theme' === $template->origin && BlockTemplateUtils::template_has_title( $template ) ) {
 					return $template;
 				}
 				if ( $template->title === $template->slug ) {
@@ -249,8 +327,8 @@ function( $template ) {
 	/**
 	 * Gets the templates saved in the database.
 	 *
-	 * @param array $slugs An array of slugs to retrieve templates for.
-	 * @param array $template_type wp_template or wp_template_part.
+	 * @param array  $slugs An array of slugs to retrieve templates for.
+	 * @param string $template_type wp_template or wp_template_part.
 	 *
 	 * @return int[]|\WP_Post[] An array of found templates.
 	 */
@@ -331,13 +409,32 @@ function ( $template ) use ( $template_slug ) {
 				continue;
 			}
 
+			if ( BlockTemplateUtils::template_is_eligible_for_product_archive_fallback_from_db( $template_slug, $already_found_templates ) ) {
+				$template              = clone BlockTemplateUtils::get_fallback_template_from_db( $template_slug, $already_found_templates );
+				$template_id           = explode( '//', $template->id );
+				$template->id          = $template_id[0] . '//' . $template_slug;
+				$template->slug        = $template_slug;
+				$template->title       = BlockTemplateUtils::get_block_template_title( $template_slug );
+				$template->description = BlockTemplateUtils::get_block_template_description( $template_slug );
+				$templates[]           = $template;
+				continue;
+			}
+
 			// If the theme has an archive-product.html template, but not a taxonomy-product_cat/tag/attribute.html template let's use the themes archive-product.html template.
-			if ( BlockTemplateUtils::template_is_eligible_for_product_archive_fallback( $template_slug ) ) {
+			if ( BlockTemplateUtils::template_is_eligible_for_product_archive_fallback_from_theme( $template_slug ) ) {
 				$template_file = BlockTemplateUtils::get_theme_template_path( 'archive-product' );
 				$templates[]   = BlockTemplateUtils::create_new_block_template_object( $template_file, $template_type, $template_slug, true );
 				continue;
 			}
 
+			// At this point the template only exists in the Blocks filesystem, if is a taxonomy-product_cat/tag/attribute.html template
+			// let's use the archive-product.html template from Blocks.
+			if ( BlockTemplateUtils::template_is_eligible_for_product_archive_fallback( $template_slug ) ) {
+				$template_file = $this->get_template_path_from_woocommerce( 'archive-product' );
+				$templates[]   = BlockTemplateUtils::create_new_block_template_object( $template_file, $template_type, $template_slug, false );
+				continue;
+			}
+
 			// At this point the template only exists in the Blocks filesystem and has not been saved in the DB,
 			// or superseded by the theme.
 			$templates[] = BlockTemplateUtils::create_new_block_template_object( $template_file, $template_type, $template_slug );
@@ -349,23 +446,23 @@ function ( $template ) use ( $template_slug ) {
 	/**
 	 * Get and build the block template objects from the block template files.
 	 *
-	 * @param array $slugs An array of slugs to retrieve templates for.
-	 * @param array $template_type wp_template or wp_template_part.
+	 * @param array  $slugs An array of slugs to retrieve templates for.
+	 * @param string $template_type wp_template or wp_template_part.
 	 *
 	 * @return array WP_Block_Template[] An array of block template objects.
 	 */
 	public function get_block_templates( $slugs = array(), $template_type = 'wp_template' ) {
 		$templates_from_db  = $this->get_block_templates_from_db( $slugs, $template_type );
 		$templates_from_woo = $this->get_block_templates_from_woocommerce( $slugs, $templates_from_db, $template_type );
 		$templates          = array_merge( $templates_from_db, $templates_from_woo );
-		return BlockTemplateUtils::filter_block_templates_by_feature_flag( $templates );
 
+		return BlockTemplateUtils::filter_block_templates_by_feature_flag( $templates );
 	}
 
 	/**
 	 * Gets the directory where templates of a specific template type can be found.
 	 *
-	 * @param array $template_type wp_template or wp_template_part.
+	 * @param string $template_type wp_template or wp_template_part.
 	 *
 	 * @return string
 	 */
@@ -382,6 +479,18 @@ protected function get_templates_directory( $template_type = 'wp_template' ) {
 		return $this->templates_directory;
 	}
 
+	/**
+	 * Returns the path of a template on the Blocks template folder.
+	 *
+	 * @param string $template_slug Block template slug e.g. single-product.
+	 * @param string $template_type wp_template or wp_template_part.
+	 *
+	 * @return string
+	 */
+	public function get_template_path_from_woocommerce( $template_slug, $template_type = 'wp_template' ) {
+		return $this->get_templates_directory( $template_type ) . '/' . $template_slug . '.html';
+	}
+
 	/**
 	 * Checks whether a block template with that name exists in Woo Blocks
 	 *

src/Templates/ProductAttributeTemplate.php

@@ -21,7 +21,7 @@ public function __construct() {
 	 * Initialization method.
 	 */
 	protected function init() {
-		add_filter( 'taxonomy_template_hierarchy', array( $this, 'update_taxonomy_template_hierarchy' ), 10, 3 );
+		add_filter( 'taxonomy_template_hierarchy', array( $this, 'update_taxonomy_template_hierarchy' ), 1, 3 );
 	}
 
 	/**

src/Utils/BlockTemplateUtils.php

@@ -12,6 +12,7 @@
  * {@internal This class and its methods should only be used within the BlockTemplateController.php and is not intended for public use.}
  */
 class BlockTemplateUtils {
+	const ELIGIBLE_FOR_ARCHIVE_PRODUCT_FALLBACK = array( 'taxonomy-product_cat', 'taxonomy-product_tag', ProductAttributeTemplate::SLUG );
 	/**
 	 * Directory names for block templates
 	 *
@@ -452,26 +453,82 @@ public static function get_block_template( $id, $template_type ) {
 	}
 
 	/**
-	 * Checks if we can fallback to the `archive-product` template for a given slug
+	 * Checks if we can fall back to the `archive-product` template for a given slug.
 	 *
-	 * `taxonomy-product_cat`, `taxonomy-product_tag`, `taxonomy-attribute` templates can
+	 * `taxonomy-product_cat`, `taxonomy-product_tag`, `taxonomy-product_attribute` templates can
 	 *  generally use the `archive-product` as a fallback if there are no specific overrides.
 	 *
 	 * @param string $template_slug Slug to check for fallbacks.
 	 * @return boolean
 	 */
 	public static function template_is_eligible_for_product_archive_fallback( $template_slug ) {
-		$eligible_for_fallbacks = array( 'taxonomy-product_cat', 'taxonomy-product_tag', ProductAttributeTemplate::SLUG );
+		return in_array( $template_slug, self::ELIGIBLE_FOR_ARCHIVE_PRODUCT_FALLBACK, true );
+	}
+
+	/**
+	 * Checks if we can fall back to an `archive-product` template stored on the db for a given slug.
+	 *
+	 * @param string $template_slug Slug to check for fallbacks.
+	 * @param array  $db_templates Templates that have already been found on the db.
+	 * @return boolean
+	 */
+	public static function template_is_eligible_for_product_archive_fallback_from_db( $template_slug, $db_templates ) {
+		$eligible_for_fallback = self::template_is_eligible_for_product_archive_fallback( $template_slug );
+		if ( ! $eligible_for_fallback ) {
+			return false;
+		}
+
+		$array_filter = array_filter(
+			$db_templates,
+			function ( $template ) use ( $template_slug ) {
+				return 'archive-product' === $template->slug;
+			}
+		);
+
+		return count( $array_filter ) > 0;
+	}
+
+	/**
+	 * Gets the `archive-product` fallback template stored on the db for a given slug.
+	 *
+	 * @param string $template_slug Slug to check for fallbacks.
+	 * @param array  $db_templates Templates that have already been found on the db.
+	 * @return boolean|object
+	 */
+	public static function get_fallback_template_from_db( $template_slug, $db_templates ) {
+		$eligible_for_fallback = self::template_is_eligible_for_product_archive_fallback( $template_slug );
+		if ( ! $eligible_for_fallback ) {
+			return false;
+		}
+
+		foreach ( $db_templates as $template ) {
+			if ( 'archive-product' === $template->slug ) {
+				return $template;
+			}
+		}
 
-		return in_array( $template_slug, $eligible_for_fallbacks, true )
+		return false;
+	}
+
+	/**
+	 * Checks if we can fall back to the `archive-product` file template for a given slug in the current theme.
+	 *
+	 * `taxonomy-product_cat`, `taxonomy-product_tag`, `taxonomy-attribute` templates can
+	 *  generally use the `archive-product` as a fallback if there are no specific overrides.
+	 *
+	 * @param string $template_slug Slug to check for fallbacks.
+	 * @return boolean
+	 */
+	public static function template_is_eligible_for_product_archive_fallback_from_theme( $template_slug ) {
+		return self::template_is_eligible_for_product_archive_fallback( $template_slug )
 			&& ! self::theme_has_template( $template_slug )
 			&& self::theme_has_template( 'archive-product' );
 	}
 
 	/**
 	 * Sets the `has_theme_file` to `true` for templates with fallbacks
 	 *
-	 * There are cases (such as tags and categories) in which fallback templates
+	 * There are cases (such as tags, categories and attributes) in which fallback templates
 	 * can be used; so, while *technically* the theme doesn't have a specific file
 	 * for them, it is important that we tell Gutenberg that we do, in fact,
 	 * have a theme file (i.e. the fallback one).
@@ -491,7 +548,7 @@ public static function set_has_theme_file_if_fallback_is_available( $query_resul
 				$query_result_template->slug === $template->slug
 				&& $query_result_template->theme === $template->theme
 			) {
-				if ( self::template_is_eligible_for_product_archive_fallback( $template->slug ) ) {
+				if ( self::template_is_eligible_for_product_archive_fallback_from_theme( $template->slug ) ) {
 					$query_result_template->has_theme_file = true;
 				}
 
@@ -586,4 +643,14 @@ public static function should_use_blockified_product_grid_templates() {
 
 		return wc_string_to_bool( $use_blockified_templates );
 	}
+
+	/**
+	 * Returns whether the passed `$template` has a title, and it's different from the slug.
+	 *
+	 * @param object $template The template object.
+	 * @return boolean
+	 */
+	public static function template_has_title( $template ) {
+		return ! empty( $template->title ) && $template->title !== $template->slug;
+	}
 }

templates/templates/blockified/taxonomy-product_attribute.html

@@ -0,0 +1,8 @@
+<!-- wp:template-part {"slug":"header"} /-->
+<!-- wp:group {"layout":{"inherit":true}} -->
+<div class="wp-block-group">
+	<!-- wp:paragraph -->
+	<p>Products by Attribute blockified</p>
+	<!-- /wp:paragraph --></div>
+<!-- /wp:group -->
+<!-- wp:template-part {"slug":"footer"} /-->