Document template parts used by the Classic Template block (#48183)
* Document template parts used by the Classic Template block * Add changelog file * More changes * Change image * More changes (II) * Update plugins/woocommerce-blocks/docs/internal-developers/templates/README.md Co-authored-by: Manish Menaria <the.manish.menaria@gmail.com> * Update plugins/woocommerce-blocks/docs/internal-developers/templates/classic-template.md Co-authored-by: Manish Menaria <the.manish.menaria@gmail.com> * Make image smaller and centered * Change PHP template parts section format --------- Co-authored-by: Manish Menaria <the.manish.menaria@gmail.com>
This commit is contained in:
Albert Juhé Lluveras
GitHub
parent
1fe724b6ef
commit
54854f16cf
|
|
@ -4,12 +4,27 @@
|
|||
|
||||
- [Usage](#usage)
|
||||
- [Props](#props)
|
||||
- [Internals](#internals)
|
||||
- [Extensibility](#extensibility)
|
||||
- [PHP actions and filters](#php-actions-and-filters)
|
||||
- [PHP template parts](#php-template-parts)
|
||||
|
||||
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.
|
||||
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. In the editor UI, it's presented with these names:
|
||||
|
||||
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.
|
||||
- `Product (Classic)`,
|
||||
- `Product Attribute (Classic)`,
|
||||
- `Product Taxonomy (Classic)`,
|
||||
- `Product Tag (Classic)`,
|
||||
- `Product Search Results (Classic)`,
|
||||
- `Product Grid (Classic)`.
|
||||
|
||||
It's worth noting that the placeholder in the Site Editor is merely an approximate representation of a template's front-end view.
|
||||
When the Classic Template block is clicked, a button appears to 'Transform into blocks'. Clicking it updates the template so it's composed of more granular blocks. That's what we commonly refer to as the 'blockified template'. The blockified template has several advantages over using the Classic Template block, like allowing users to hide some blocks from the template, changing their order or making more granular modifications.
|
||||
|
||||
<p align="center"><!-- markdownlint-disable-line no-inline-html -->
|
||||
<img src="https://github.com/woocommerce/woocommerce/assets/3616980/c996d4e8-8839-4542-b6a3-9f01627c482d" alt="Classic Template block in the Single Product template" width="400"/><!-- markdownlint-disable-line no-inline-html -->
|
||||
</p><!-- markdownlint-disable-line no-inline-html -->
|
||||
|
||||
Once the user has switched to the blockified template, a button will appear on the 'Template' sidebar allowing them to revert to the classic template, which adds back the Classic Template block.
|
||||
|
||||
## Usage
|
||||
|
||||
|
|
@ -25,7 +40,48 @@ This block does not have any customizable options available, so any style or cus
|
|||
<!-- wp:woocommerce/legacy-template {"template":"single-product"} /-->
|
||||
```
|
||||
|
||||
|
||||
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.
|
||||
|
||||
## Internals
|
||||
|
||||
The `ClassicTemplate` class is used to set up the Classic Template block server-side. This class takes care of rendering the correct template and is also responsible of enqueuing the front-end scripts necessary to enable dynamic functionality, such as the product gallery, add to cart, 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.
|
||||
|
||||
## Extensibility
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Before customizing or extending the Classic Template block, keep in mind that users can easily switch from the Classic Template block to the blockified version of the templates, so any customizations or extensibility changes should cover both paradigms.
|
||||
|
||||
### PHP actions and filters
|
||||
|
||||
> [!NOTE]
|
||||
> Using PHP actions and filters to customize the look-and-feel of a store with a block theme is discouraged. We recommend using [blocks](https://developer.wordpress.org/block-editor/), [global styles](https://developer.wordpress.org/themes/global-settings-and-styles/), [block hooks](https://make.wordpress.org/core/2023/10/15/introducing-block-hooks-for-dynamic-blocks/), and other block-based APIs. However, these filters can be useful to port some customizations from the blocks into the Classic Template block.
|
||||
|
||||
Internally, the `ClassicTemplate` class triggers several PHP hooks that are shared with classic themes. Those are:
|
||||
|
||||
- `woocommerce_before_main_content`
|
||||
- [`woocommerce_show_page_title`](https://github.com/woocommerce/woocommerce/blob/f040e3acf7df9420a09d37b84358ac7d2e03b8a3/plugins/woocommerce/src/Blocks/BlockTypes/ClassicTemplate.php#L264) (only in Product archive templates)
|
||||
- [`woocommerce_archive_description`](https://github.com/woocommerce/woocommerce/blob/f040e3acf7df9420a09d37b84358ac7d2e03b8a3/plugins/woocommerce/src/Blocks/BlockTypes/ClassicTemplate.php#L281) (only in Product archive templates)
|
||||
- [`woocommerce_before_shop_loop`](https://github.com/woocommerce/woocommerce/blob/f040e3acf7df9420a09d37b84358ac7d2e03b8a3/plugins/woocommerce/src/Blocks/BlockTypes/ClassicTemplate.php#L296) (only in Product archive templates)
|
||||
- [`woocommerce_shop_loop`](https://github.com/woocommerce/woocommerce/blob/f040e3acf7df9420a09d37b84358ac7d2e03b8a3/plugins/woocommerce/src/Blocks/BlockTypes/ClassicTemplate.php#L309) (only in Product archive templates)
|
||||
- [`woocommerce_after_shop_loop`](https://github.com/woocommerce/woocommerce/blob/f040e3acf7df9420a09d37b84358ac7d2e03b8a3/plugins/woocommerce/src/Blocks/BlockTypes/ClassicTemplate.php#L324) (only in Product archive templates)
|
||||
- [`woocommerce_no_products_found`](https://github.com/woocommerce/woocommerce/blob/f040e3acf7df9420a09d37b84358ac7d2e03b8a3/plugins/woocommerce/src/Blocks/BlockTypes/ClassicTemplate.php#L333) (only in Product archive templates)
|
||||
- `woocommerce_after_main_content`
|
||||
|
||||
Those hooks except `woocommerce_show_page_title` and `woocommerce_shop_loop` are also applied to the blockified version of templates thanks to the [compatibility layer](../../../../docs/internal-developers/blockified-templates/compatibility-layer.md).
|
||||
|
||||
### PHP template parts
|
||||
|
||||
> [!NOTE]
|
||||
> Using PHP template parts to customize the look-and-feel of a store with a block theme is discouraged. We recommend using [blocks](https://developer.wordpress.org/block-editor/), [global styles](https://developer.wordpress.org/themes/global-settings-and-styles/), [block hooks](https://make.wordpress.org/core/2023/10/15/introducing-block-hooks-for-dynamic-blocks/), and other block-based APIs. However, these template parts can be useful to port some customizations from the blocks into the Classic Template block.
|
||||
|
||||
> [!CAUTION]
|
||||
> Unlike most PHP actions and filters mentioned above, the PHP template parts are not applied in the blockified version of the templates, so you should make sure to build a version of the same changes that works with blocks.
|
||||
|
||||
The `ClassicTemplate` class renders a couple of PHP template parts. Those are [`content-single-product` template part](https://github.com/woocommerce/woocommerce/blob/f040e3acf7df9420a09d37b84358ac7d2e03b8a3/plugins/woocommerce/src/Blocks/BlockTypes/ClassicTemplate.php#L213) in the Single Product version of the Classic Template block and the [`content-product` template part](https://github.com/woocommerce/woocommerce/blob/f040e3acf7df9420a09d37b84358ac7d2e03b8a3/plugins/woocommerce/src/Blocks/BlockTypes/ClassicTemplate.php#L311) when rendering the Product archive templates. Themes can override those template parts as they would normally do in classic themes, with `content-single-product.php` and `content-product.php` files. However, remember that these templates parts are not used in the blockified version of the templates, so any changes to them won't be applied to the granular blocks.
|
||||
|
||||
<!-- FEEDBACK -->
|
||||
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 188 KiB |
|
|
@ -50,7 +50,7 @@ The BlockTemplateController.php is primarily responsible for hooking into both W
|
|||
|-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------|
|
||||
| templates/templates/\* | Location in the filesystem where WooCommerce block template HTML files are stored. | [Source files](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/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/tree/trunk/plugins/woocommerce-blocks/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/blob/trunk/plugins/woocommerce/src/Blocks/BlockTypes/ClassicTemplate.php) | [README](./classic-template.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/blob/trunk/plugins/woocommerce/src/Blocks/BlockTypes/ClassicTemplate.php) | [README](../../../assets/js/blocks/classic-template/README.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/blob/trunk/plugins/woocommerce/src/Blocks/BlockTemplatesController.php) | [README](./block-template-controller.md) |
|
||||
| BlockTemplateUtils.php | Class containing a collection of useful utility methods. | [Source file](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Blocks/Utils/BlockTemplateUtils.php) | |
|
||||
| BlockTemplatesRegistry.php | Class used as a registry of WooCommerce templates. | [Source file](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Blocks/BlockTemplatesRegistry.php) | |
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 43 KiB |
|
|
@ -1,11 +1,3 @@
|
|||
# ClassicTemplate.php <!-- omit in toc -->
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Please read the [Classic Template block docs](../../../assets/js/blocks/classic-template/README.md) for information about the `ClassicTemplate.php` file.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,5 @@
|
|||
Significance: patch
|
||||
Type: tweak
|
||||
Comment: Document template parts used by the Classic Template block
|
||||
|
||||
|
||||
Loading…
Reference in New Issue