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>
This commit is contained in:
Tom Cafferkey
GitHub
parent
d54383b417
commit
e8855a5af3
|
|
@ -0,0 +1,22 @@
|
|||
# Classic Template Block
|
||||
|
||||
The Classic Template block is a placeholder block for specific WooCommerce block templates which are rendered on the server-side when a block theme is active.
|
||||
|
||||
By assigning a template identifier to the attribute prop, the block will render that specific template on the front-end, and a placeholder for said template in the Site Editor.
|
||||
|
||||
It's worth noting that the placeholder in the Site Editor is merely an approximate representation of a template's front-end view.
|
||||
|
||||
## Usage
|
||||
|
||||
This block does not have any customizable options available, so any style or customization updates will not be reflected on the placeholder.
|
||||
|
||||
### Props
|
||||
|
||||
* `attributes`
|
||||
* `template`: `single-product` | `archive-product` | `taxonomy-product_cat` | `taxonomy-product_tag`
|
||||
|
||||
```html
|
||||
<!-- wp:woocommerce/legacy-template {"template":"single-product"} /-->
|
||||
```
|
||||
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 188 KiB |
|
|
@ -10,6 +10,7 @@ The WooCommerce Blocks Handbook provides documentation for designers and develop
|
|||
| [Store API (REST API)](../src/StoreApi/README.md) | These documents cover the Store API used to get product data on the frontend. |
|
||||
| [Extensibility](extensibility/README.md) | These documents cover extensibility of WooCommerce Blocks. |
|
||||
| [Theming](theming/README.md) | These documents cover theming for blocks, styles, CSS classnames and other theming best practices. |
|
||||
| [Templates](templates/README.md) | These documents provide a technical overview of WooCommerce block template (parts) functionality. |
|
||||
|
||||
<!-- FEEDBACK -->
|
||||
---
|
||||
|
|
|
|||
|
|
@ -0,0 +1,57 @@
|
|||
# WooCommerce Block Templates
|
||||
|
||||
This page includes documentation related to WooCommerce Block Templates.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
* [Overview](#overview)
|
||||
* [Requirements](#requirements)
|
||||
* [Technical Overview](#technical-overview)
|
||||
* [The Problem](#the-problem)
|
||||
* [The Solution](#the-solution)
|
||||
* [Some things to be aware of](#some-things-to-be-aware-of)
|
||||
* [Related Files](#related-files)
|
||||
|
||||
## 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](https://developer.wordpress.org/block-editor/getting-started/full-site-editing/).
|
||||
|
||||
### Requirements
|
||||
|
||||
| Software | Minimum Version |
|
||||
|-----------------|------------------|
|
||||
| WordPress | 5.9 |
|
||||
| WooCommerce | 6.0 |
|
||||
| Theme | Any [block theme](https://developer.wordpress.org/block-editor/how-to-guides/themes/block-theme-overview/#what-is-a-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](https://github.com/woocommerce/woocommerce-gutenberg-products-block/tree/trunk/templates/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](https://github.com/woocommerce/woocommerce-gutenberg-products-block/issues/5423).
|
||||
* 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.
|
||||
|
||||
## Related files
|
||||
|
||||
| File | Description | Source | Docs |
|
||||
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
|
||||
| templates/templates/\* | Location in the filesystem where WooCommerce block template HTML files are stored. | [Source files](https://github.com/woocommerce/woocommerce-gutenberg-products-block/tree/trunk/templates/templates) | |
|
||||
| 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](https://github.com/woocommerce/woocommerce-gutenberg-products-block/tree/trunk/assets/js/blocks/classic-template) | [README](../../assets/js/blocks/classic-template/README.md)|
|
||||
| ClassicTemplate.php | Class used to setup the block on the server-side and render the correct template | [Source file](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/trunk/src/BlockTypes/ClassicTemplate.php) | [README](./classic-template.md) |
|
||||
| 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](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/trunk/src/BlockTemplatesController.php) | [README](./block-template-controller.md) |
|
||||
| BlockTemplateUtils.php | Class containing a collection of useful utility methods. | [Source file](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/trunk/src/Utils/BlockTemplateUtils.php) | |
|
||||
|
||||
BIN
plugins/woocommerce-blocks/docs/templates/assets/classic-template-attributes.png
vendored
Normal file
BIN
plugins/woocommerce-blocks/docs/templates/assets/classic-template-attributes.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 43 KiB |
|
|
@ -0,0 +1,78 @@
|
|||
# BlockTemplateController
|
||||
[Source file](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/trunk/src/BlockTemplatesController.php)
|
||||
|
||||
The BlockTemplateController class 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. Without documenting every method individually, I will look to provide some insight into key functionality.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
* [Overview](#overview)
|
||||
* [add_block_templates( $query_result, $query, $template_type )](#add_block_templates-query_result-query-template_type-)
|
||||
* [get_block_file_template( $template, $id, $template_type )](#get_block_file_template-template-id-template_type-)
|
||||
* [render_block_template()](#render_block_template)
|
||||
|
||||
## Overview
|
||||
|
||||
In the initialization of the class, we hook into the three hooks listed below. These provide us with all of the extensibility points necessary in order to load our own block templates alongside the themes.
|
||||
|
||||
Within each method section, I will explain in what scenarios they are executed.
|
||||
|
||||
* filter: `get_block_templates` with `add_block_templates`.
|
||||
* filter: `pre_get_block_file_template` with `get_block_file_template`.
|
||||
* action: `template_redirect` with `render_block_template`.
|
||||
|
||||
## add_block_templates( $query_result, $query, $template_type )
|
||||
|
||||
This method is applied to the filter `get_block_templates`, which is executed before returning a unified list of template objects based on a query.
|
||||
|
||||
**Typically executed when:**
|
||||
* Loading the "All Templates" view in the Site Editor
|
||||
* Loading one of the templates on the front-end where the query would build a list of relevant templates based on a hierarchy (for example, the product page hierarchy could be an array containing `single-product-[product-name].html`, `single-product.html`, `single.html`).
|
||||
* Loading the "Edit Product" view.
|
||||
|
||||
**This method is responsible for:**
|
||||
|
||||
* 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.
|
||||
* 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
|
||||
|
||||
This method will return an array of `WP_Block_Template` values
|
||||
|
||||
## get_block_file_template( $template, $id, $template_type )
|
||||
|
||||
This method is applied to the filter `pre_get_block_file_template` inside the WordPress core function `get_block_file_template` (not to be confused with this method from the `BlockTemplateController` class, which has the same name).
|
||||
|
||||
The order of execution is as follows:
|
||||
|
||||
1. `get_block_template()` from WordPress core will execute, and attempt to retrieve a customized version of the template from the database.
|
||||
2. If it fails to retrieve one, it will execute the `get_block_file_template()` function from WordPress core which will apply the filter `pre_get_block_file_template`. This is where we hook in to to return our template file, and trigger an early return to prevent WordPress from continuing its query.
|
||||
|
||||
During step 2 it's important we hook into the `pre_get_block_file_template`. If we don't, the function will check if the first part of the template ID (e.g. `woocommerce/woocommerce`) is the same as the current themes ID (e.g. `twentytwentytwo`), which will resolve `false` and return `null` instead of the expected `WP_Block_Template` object.
|
||||
|
||||
**Typically executed when:**
|
||||
* A user clears the customizations of a WooCommerce template.
|
||||
|
||||
**This method is responsible for:**
|
||||
* Loading the template files from the filesystem, and building a `WP_Block_Template` version of it.
|
||||
|
||||
### Return value
|
||||
|
||||
This method will return `WP_Block_Template` or `null`.
|
||||
|
||||
## render_block_template()
|
||||
|
||||
This method is applied to the filter `template_redirect` and executed before WordPress determines which template to load.
|
||||
|
||||
This allows us to hook into WooCommerce core through the filter `woocommerce_has_block_template` where we can determine if a specific block template exists and should be loaded.
|
||||
|
||||
**Typically executed when:**
|
||||
* A user loads a page on the front-end.
|
||||
|
||||
**This method is responsible for:**
|
||||
* Determining if the current page has an appropriate WooCommerce block template available to render.
|
||||
* Checking if the currently loaded page is from WooCommerce. It then checks if the theme has an appropriate template to use: if it does not, then it finally checks if WooCommerce has a default block template available. If so, we override the value through `woocommerce_has_block_template` to resolve `true`.
|
||||
|
||||
### Return value
|
||||
Void. This method does not return a value but rather sets up hooks to render block templates on the front-end.
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
# ClassicTemplate
|
||||
|
||||
[Source file](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/trunk/src/BlockTypes/ClassicTemplate.php)
|
||||
|
||||
The `ClassicTemplate` is a class used to set up the Classic Template block on the server-side, and render the correct template.
|
||||
|
||||
## Overview
|
||||
|
||||
From this file, we enqueue the front-end scripts necessary to enable dynamic functionality, such as the product gallery, add to basket etc.
|
||||
|
||||
From the `render()` method we inspect the `$attributes` object for a `template` property which helps determine which core PHP templating code to execute (e.g. `single-product`) for the front-end views.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue