BlockTemplateUtils
in package
Utility methods used for serving block templates from WooCommerce Blocks.
Table of Contents
- DEPRECATED_PLUGIN_SLUG = 'woocommerce'
- Deprecated WooCommerce plugin slug
- DIRECTORY_NAMES = array('DEPRECATED_TEMPLATES' => 'block-templates', 'DEPRECATED_TEMPLATE_PARTS' => 'block-template-parts', 'TEMPLATES' => 'templates', 'TEMPLATE_PARTS' => 'parts')
- Directory names for block templates
- PLUGIN_SLUG = 'woocommerce/woocommerce'
- WooCommerce plugin slug
- TEMPLATES_ROOT_DIR = 'templates'
- build_template_result_from_post() : WP_Block_Template|WP_Error
- Build a unified template object based a post Object.
- create_new_block_template_object() : object
- Build a new template object so that we can make Woo Blocks default templates available in the current theme should they not have any.
- flatten_blocks() : array<string|int, mixed>
- Returns an array containing the references of the passed blocks and their inner blocks.
- generate_template_slug_from_path() : string
- Converts template paths into a slug
- get_block_template_area() : string
- Returns area for template parts.
- get_block_template_description() : string
- Returns template description.
- get_block_template_title() : string
- Returns template title.
- get_block_templates_from_db() : array<string|int, int>|array<string|int, WP_Post>
- Gets the templates saved in the database.
- get_fallback_template_from_db() : bool|object
- Gets the `archive-product` fallback template stored on the db for a given slug.
- get_template() : AbstractTemplate|AbstractTemplatePart|null
- Returns the template matching the slug
- get_template_part() : string
- Gets the template part by slug
- get_template_paths() : array<string|int, mixed>
- Finds all nested template part file paths in a theme's directory.
- get_templates_directory() : string
- Gets the directory where templates of a specific template type can be found.
- get_theme_template_path() : string|null
- Gets the first matching template part within themes directories
- inject_theme_attribute_in_content() : string
- Parses wp_template content and injects the current theme's stylesheet as a theme attribute into each wp_template_part
- remove_duplicate_customized_templates() : array<string|int, mixed>
- Removes customized templates that shouldn't be available. That means customized templates based on the WooCommerce default template when there is a customized template based on the theme template.
- remove_theme_templates_with_custom_alternative() : array<string|int, mixed>
- Removes templates that were added to a theme's block-templates directory, but already had a customised version saved in the database.
- set_has_theme_file_if_fallback_is_available() : bool
- Sets the `has_theme_file` to `true` for templates with fallbacks
- should_use_blockified_product_grid_templates() : bool
- Returns whether the blockified templates should be used or not.
- supports_block_templates() : bool
- Checks to see if they are using a compatible version of WP, or if not they have a compatible version of the Gutenberg plugin installed.
- template_has_legacy_template_block() : bool
- Returns whether the passed `$template` has the legacy template block.
- template_is_eligible_for_product_archive_fallback() : bool
- Checks if we can fall back to the `archive-product` template for a given slug.
- template_is_eligible_for_product_archive_fallback_from_db() : bool
- Checks if we can fall back to an `archive-product` template stored on the db for a given slug.
- template_is_eligible_for_product_archive_fallback_from_theme() : bool
- Checks if we can fall back to the `archive-product` file template for a given slug in the current theme.
- theme_has_template() : bool
- Check if the theme has a template. So we know if to load our own in or not.
- theme_has_template_part() : bool
- Check if the theme has a template. So we know if to load our own in or not.
- update_template_data() : WP_Block_Template
- Updates the title, description and area of a template to the correct values and to make them more user-friendly.
Constants
DEPRECATED_PLUGIN_SLUG
Deprecated WooCommerce plugin slug
public
string
DEPRECATED_PLUGIN_SLUG
= 'woocommerce'
For supporting users who have customized templates under the incorrect plugin slug during the first release. More context found here: https://github.com/woocommerce/woocommerce-gutenberg-products-block/issues/5423.
DIRECTORY_NAMES
Directory names for block templates
public
array<string|int, mixed>
DIRECTORY_NAMES
= array('DEPRECATED_TEMPLATES' => 'block-templates', 'DEPRECATED_TEMPLATE_PARTS' => 'block-template-parts', 'TEMPLATES' => 'templates', 'TEMPLATE_PARTS' => 'parts')
Directory names conventions for block templates have changed with Gutenberg 12.1.0,
however, for backwards-compatibility, we also keep the older conventions, prefixed
with DEPRECATED_.
PLUGIN_SLUG
WooCommerce plugin slug
public
string
PLUGIN_SLUG
= 'woocommerce/woocommerce'
This is used to save templates to the DB which are stored against this value in the wp_terms table.
TEMPLATES_ROOT_DIR
public
mixed
TEMPLATES_ROOT_DIR
= 'templates'
Methods
build_template_result_from_post()
Build a unified template object based a post Object.
public
static build_template_result_from_post(WP_Post $post) : WP_Block_Template|WP_Error
Important: This method is an almost identical duplicate from wp-includes/block-template-utils.php as it was not intended for public use. It has been modified to build templates from plugins rather than themes.
Parameters
- $post : WP_Post
-
Template post.
Return values
WP_Block_Template|WP_Error — Template.create_new_block_template_object()
Build a new template object so that we can make Woo Blocks default templates available in the current theme should they not have any.
public
static create_new_block_template_object(string $template_file, string $template_type, string $template_slug[, bool $template_is_from_theme = false ]) : object
Parameters
- $template_file : string
-
Block template file path.
- $template_type : string
-
wp_template or wp_template_part.
- $template_slug : string
-
Block template slug e.g. single-product.
- $template_is_from_theme : bool = false
-
If the block template file is being loaded from the current theme instead of Woo Blocks.
Return values
object — Block template object.flatten_blocks()
Returns an array containing the references of the passed blocks and their inner blocks.
public
static flatten_blocks(array<string|int, mixed> &$blocks) : array<string|int, mixed>
Parameters
- $blocks : array<string|int, mixed>
-
array of blocks.
Return values
array<string|int, mixed> — block references to the passed blocks and their inner blocks.generate_template_slug_from_path()
Converts template paths into a slug
public
static generate_template_slug_from_path(string $path) : string
Parameters
- $path : string
-
The template's path.
Return values
string — slugget_block_template_area()
Returns area for template parts.
public
static get_block_template_area(string $template_slug, string $template_type) : string
Parameters
- $template_slug : string
-
The template part slug (e.g. mini-cart).
- $template_type : string
-
Either
wp_templateorwp_template_part.
Return values
string — Template part area.get_block_template_description()
Returns template description.
public
static get_block_template_description(string $template_slug) : string
Parameters
- $template_slug : string
-
The template slug (e.g. single-product).
Return values
string — Template description.get_block_template_title()
Returns template title.
public
static get_block_template_title(string $template_slug) : string
Parameters
- $template_slug : string
-
The template slug (e.g. single-product).
Return values
string — Human friendly title.get_block_templates_from_db()
Gets the templates saved in the database.
public
static get_block_templates_from_db([array<string|int, mixed> $slugs = array() ][, string $template_type = 'wp_template' ]) : array<string|int, int>|array<string|int, WP_Post>
Parameters
- $slugs : array<string|int, mixed> = array()
-
An array of slugs to retrieve templates for.
- $template_type : string = 'wp_template'
-
wp_template or wp_template_part.
Return values
array<string|int, int>|array<string|int, WP_Post> — An array of found templates.get_fallback_template_from_db()
Gets the `archive-product` fallback template stored on the db for a given slug.
public
static get_fallback_template_from_db(string $template_slug, array<string|int, mixed> $db_templates) : bool|object
Parameters
- $template_slug : string
-
Slug to check for fallbacks.
- $db_templates : array<string|int, mixed>
-
Templates that have already been found on the db.
Return values
bool|object —get_template()
Returns the template matching the slug
public
static get_template(string $template_slug) : AbstractTemplate|AbstractTemplatePart|null
Parameters
- $template_slug : string
-
Slug of the template to retrieve.
Return values
AbstractTemplate|AbstractTemplatePart|null —get_template_part()
Gets the template part by slug
public
static get_template_part(string $slug) : string
Parameters
- $slug : string
-
The template part slug.
Return values
string — The template part content.get_template_paths()
Finds all nested template part file paths in a theme's directory.
public
static get_template_paths(string $template_type) : array<string|int, mixed>
Parameters
- $template_type : string
-
wp_template or wp_template_part.
Return values
array<string|int, mixed> — $path_list A list of paths to all template part files.get_templates_directory()
Gets the directory where templates of a specific template type can be found.
public
static get_templates_directory([string $template_type = 'wp_template' ]) : string
Parameters
- $template_type : string = 'wp_template'
-
wp_template or wp_template_part.
Return values
string —get_theme_template_path()
Gets the first matching template part within themes directories
public
static get_theme_template_path(string $template_slug[, string $template_type = 'wp_template' ]) : string|null
Since Gutenberg 12.1.0, the conventions for
block templates and parts directory has changed from block-templates and block-templates-parts
to templates and parts respectively.
This function traverses all possible combinations of directory paths where a template or part could be located and returns the first one which is readable, prioritizing the new convention over the deprecated one, but maintaining that one for backwards compatibility.
Parameters
- $template_slug : string
-
The slug of the template (i.e. without the file extension).
- $template_type : string = 'wp_template'
-
Either
wp_templateorwp_template_part.
Return values
string|null — The matched path or `null` if no match was found.inject_theme_attribute_in_content()
Parses wp_template content and injects the current theme's stylesheet as a theme attribute into each wp_template_part
public
static inject_theme_attribute_in_content(string $template_content) : string
Parameters
- $template_content : string
-
serialized wp_template content.
Return values
string — Updated wp_template content.remove_duplicate_customized_templates()
Removes customized templates that shouldn't be available. That means customized templates based on the WooCommerce default template when there is a customized template based on the theme template.
public
static remove_duplicate_customized_templates(array<string|int, WP_Block_Template>|array<string|int, stdClass> $templates, string $theme_slug) : array<string|int, mixed>
Parameters
- $templates : array<string|int, WP_Block_Template>|array<string|int, stdClass>
-
List of templates to run the filter on.
- $theme_slug : string
-
Slug of the theme currently active.
Return values
array<string|int, mixed> — Filtered list of templates with only relevant templates available.remove_theme_templates_with_custom_alternative()
Removes templates that were added to a theme's block-templates directory, but already had a customised version saved in the database.
public
static remove_theme_templates_with_custom_alternative(array<string|int, WP_Block_Template>|array<string|int, stdClass> $templates) : array<string|int, mixed>
Parameters
- $templates : array<string|int, WP_Block_Template>|array<string|int, stdClass>
-
List of templates to run the filter on.
Return values
array<string|int, mixed> — List of templates with duplicates removed. The customised alternative is preferred over the theme default.set_has_theme_file_if_fallback_is_available()
Sets the `has_theme_file` to `true` for templates with fallbacks
public
static set_has_theme_file_if_fallback_is_available(array<string|int, mixed> $query_result, object $template) : bool
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).
Note: this function changes the array that has been passed.
It returns true if anything was changed, false otherwise.
Parameters
- $query_result : array<string|int, mixed>
-
Array of template objects.
- $template : object
-
A specific template object which could have a fallback.
Return values
bool —should_use_blockified_product_grid_templates()
Returns whether the blockified templates should be used or not.
public
static should_use_blockified_product_grid_templates() : bool
If the option is not stored on the db, we need to check if the current theme is a block one or not.
Return values
bool —supports_block_templates()
Checks to see if they are using a compatible version of WP, or if not they have a compatible version of the Gutenberg plugin installed.
public
static supports_block_templates([string $template_type = 'wp_template' ]) : bool
Parameters
- $template_type : string = 'wp_template'
-
Optional. Template type:
wp_templateorwp_template_part. Defaultwp_template.
Return values
bool —template_has_legacy_template_block()
Returns whether the passed `$template` has the legacy template block.
public
static template_has_legacy_template_block(object $template) : bool
Parameters
- $template : object
-
The template object.
Return values
bool —template_is_eligible_for_product_archive_fallback()
Checks if we can fall back to the `archive-product` template for a given slug.
public
static template_is_eligible_for_product_archive_fallback(string $template_slug) : bool
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.
Parameters
- $template_slug : string
-
Slug to check for fallbacks.
Return values
bool —template_is_eligible_for_product_archive_fallback_from_db()
Checks if we can fall back to an `archive-product` template stored on the db for a given slug.
public
static template_is_eligible_for_product_archive_fallback_from_db(string $template_slug, array<string|int, mixed> $db_templates) : bool
Parameters
- $template_slug : string
-
Slug to check for fallbacks.
- $db_templates : array<string|int, mixed>
-
Templates that have already been found on the db.
Return values
bool —template_is_eligible_for_product_archive_fallback_from_theme()
Checks if we can fall back to the `archive-product` file template for a given slug in the current theme.
public
static template_is_eligible_for_product_archive_fallback_from_theme(string $template_slug) : bool
taxonomy-product_cat, taxonomy-product_tag, taxonomy-attribute templates can
generally use the archive-product as a fallback if there are no specific overrides.
Parameters
- $template_slug : string
-
Slug to check for fallbacks.
Return values
bool —theme_has_template()
Check if the theme has a template. So we know if to load our own in or not.
public
static theme_has_template(string $template_name) : bool
Parameters
- $template_name : string
-
name of the template file without .html extension e.g. 'single-product'.
Return values
bool —theme_has_template_part()
Check if the theme has a template. So we know if to load our own in or not.
public
static theme_has_template_part(string $template_name) : bool
Parameters
- $template_name : string
-
name of the template file without .html extension e.g. 'single-product'.
Return values
bool —update_template_data()
Updates the title, description and area of a template to the correct values and to make them more user-friendly.
public
static update_template_data(WP_Block_Template $template, string $template_type) : WP_Block_Template
For example, instead of:
- Title:
Tag (product_tag) - Description:
Displays taxonomy: Tag.we display: - Title:
Products by Tag - Description:
Displays products filtered by a tag..
Parameters
- $template : WP_Block_Template
-
The template object.
- $template_type : string
-
wp_template or wp_template_part.