woocommerce/plugins/woocommerce-blocks/docs/templates
Tom Cafferkey e8855a5af3 Full Store Editing: Technical documentation (https://github.com/woocommerce/woocommerce-blocks/pull/5939)
* templates README and block-template-controller README

* Add execution scenario to block template controller readme

* Amend return value to block template controller readme

* Add source file link to block template controller docs

* LegacyTemplate.php overview

* Legacy Template JavaScript block README

* Update requirements of templates feature

* Doc updates based on feedback, and change Legacy Template references to Classic Template in anticipation of naming convention updates

* Update classic-template.md README

* Reword part of the add_block_templates section

* Update assets/js/blocks/legacy-template/README.md

Co-authored-by: Michael P. Pfeiffer <frontdevde@users.noreply.github.com>

* Update docs/readme.md

Co-authored-by: Michael P. Pfeiffer <frontdevde@users.noreply.github.com>

* Update docs/templates/README.md

Co-authored-by: Michael P. Pfeiffer <frontdevde@users.noreply.github.com>

* Update docs/templates/README.md

Co-authored-by: Michael P. Pfeiffer <frontdevde@users.noreply.github.com>

* Update README for blocktemplatecontroller

* Review feedback for Woo FSE technical documentation

Co-authored-by: Michael P. Pfeiffer <frontdevde@users.noreply.github.com>
2022-03-02 08:57:53 +00:00
..
assets Full Store Editing: Technical documentation (https://github.com/woocommerce/woocommerce-blocks/pull/5939) 2022-03-02 08:57:53 +00:00
README.md Full Store Editing: Technical documentation (https://github.com/woocommerce/woocommerce-blocks/pull/5939) 2022-03-02 08:57:53 +00:00
block-template-controller.md Full Store Editing: Technical documentation (https://github.com/woocommerce/woocommerce-blocks/pull/5939) 2022-03-02 08:57:53 +00:00
classic-template.md Full Store Editing: Technical documentation (https://github.com/woocommerce/woocommerce-blocks/pull/5939) 2022-03-02 08:57:53 +00:00

README.md

WooCommerce Block Templates

This page includes documentation related to WooCommerce Block Templates.

Table of Contents

Overview

WooCommerce Block Templates are a collection of WooCommerce Core templates for the WordPress Full Site Editing experience introduced in WordPress 5.9. You can customize these templates in the Site Editor.

You can read more about the Full Site Editing (FSE) experience here.

Requirements

Software Minimum Version
WordPress 5.9
WooCommerce 6.0
Theme Any block theme

Technical Overview

The Problem

Currently, the FSE feature does not accommodate loading block templates from plugins such as WooCommerce (or WooCommerce Blocks). Instead, all template files loaded natively must be present within the active theme's templates folder. When the active block theme doesn't come with WooCommerce specific templates, we want to be able to provide sensible defaults, though.

The Solution

We created a custom solution which involves a handful of files (listed in the below table) that are responsible for both making the templates available as a block template, and rendering it on the front-end.

The BlockTemplateController class is primarily responsible for hooking into both WordPress core, and WooCommerce core filters to load WooCommerce templates in the Site Editor and on the front-end. It is in this class where the majority of the logic is handled.

Some things to be aware of

  • Individual templates are represented by a placeholder block within the Site Editor until we can 'block-ify' these. This is the long-term goal. Until then users will be able to customize templates by adding blocks above and below the placeholder.
  • At the beginning of the project, we unintentionally used the incorrect WooCommerce plugin slug. This has resulted in us maintaining both the incorrect and correct slugs. We reference these via BlockTemplateUtils::DEPRECATED_PLUGIN_SLUG and BlockTemplateUtils::PLUGIN_SLUG. More information on that here.
  • If a theme has a archive-product.html template file, but does not have any taxonomy related files. We will automatically duplicate their themes archive-product.html file in place of these taxonomy files within BlockTemplateController->get_block_file_template().
  • In BlockTemplateController->get_block_templates() we filter out templates in production that are behind a feature flag. These will be available in development, but will be absent in production unless the feature flag is removed.
File Description Source Docs
templates/templates/* Location in the filesystem where WooCommerce block template HTML files are stored. Source files
classic-template/* The JavaScript block rendered in the Site Editor. This is a server-side rendered component which is handled by ClassicTemplate.php Source file README
ClassicTemplate.php Class used to setup the block on the server-side and render the correct template Source file README
BlockTemplateController.php Class which contains all the business logic which loads the templates into the Site Editor or on the front-end through various hooks available in WordPress & WooCommerce core. Source file README
BlockTemplateUtils.php Class containing a collection of useful utility methods. Source file