From 1903b3a7592f990ce5a5e7979261d6ae4f618092 Mon Sep 17 00:00:00 2001 From: Nathan Silveira Date: Mon, 2 Oct 2023 09:59:35 -0300 Subject: [PATCH] Update Product Editor Handbook (#40514) * Rename title * Remove common-tasks section as it's currently made redundant by template API documentation * Create index for reusable blocks doc * Update reference to the handbook * Add references to new documentation to the handbook * Add changelog * Update README.md --- docs/product-editor-development/README.md | 13 +++---- .../common-tasks.md | 34 ------------------- .../product-editor/changelog/doc-handbook-1.1 | 5 +++ .../js/product-editor/src/blocks/README.md | 7 ++++ .../woocommerce/changelog/doc-handbook-1.1 | 5 +++ .../ProductTemplates/README.md | 2 +- 6 files changed, 25 insertions(+), 41 deletions(-) delete mode 100644 docs/product-editor-development/common-tasks.md create mode 100644 packages/js/product-editor/changelog/doc-handbook-1.1 create mode 100644 packages/js/product-editor/src/blocks/README.md create mode 100644 plugins/woocommerce/changelog/doc-handbook-1.1 diff --git a/docs/product-editor-development/README.md b/docs/product-editor-development/README.md index ef66a11de0f..e61d300c983 100644 --- a/docs/product-editor-development/README.md +++ b/docs/product-editor-development/README.md @@ -1,4 +1,4 @@ -# Developing extensions for the product editor +# Product Editor Development Handbook > ⚠️ **Notice:** This documentation is currently a **work in progress**. Please be aware that some sections might be incomplete or subject to change. We appreciate your patience and welcome any contributions! @@ -8,11 +8,12 @@ The product editor's UI consists of Groups (currently rendered as tabs), Section ![Product editor structure](https://woocommerce.files.wordpress.com/2023/09/groups-sections-fields.jpg) -The form's structure is defined in PHP using a Template. The template can be modified by using the Block Template API to add new Groups, Sections, and Fields as well as remove existing ones. +The form's structure is defined in PHP using a Template, which is a tree structure of blocks. The template can be modified by using the Template API to add new Groups, Sections, and Fields as well as remove existing ones. -Many extensibility implementations can be done using only the PHP-based Block Template API. More complex interactivity can be implemented using JavaScript and React (the same library used to implement the core blocks used in the product editor). [@woocommerce/create-product-editor-block](../../packages/js/create-product-editor-block/README.md) can help scaffold a development environment with JavaScript and React. +Many extensibility implementations can be done using only the PHP-based Block Template API alongside our library of [reusable blocks](../../packages/js/product-editor/src/blocks/README.md). More complex interactivity can be implemented using JavaScript and React (the same library used to implement the core blocks used in the product editor). [@woocommerce/create-product-editor-block](../../packages/js/create-product-editor-block/README.md) can help scaffold a development environment with JavaScript and React. +## Related documentation -## Index - -- [Common tasks](common-tasks.md) +- [Examples on Template API usage](../../plugins/woocommerce/src/Admin/Features/ProductBlockEditor/ProductTemplates/README.md) +- [Related hooks and Template API documentation](../../plugins/woocommerce/src/Admin/BlockTemplates/README.md) +- [Reusable blocks documentation](../../packages/js/product-editor/src/blocks/README.md) diff --git a/docs/product-editor-development/common-tasks.md b/docs/product-editor-development/common-tasks.md deleted file mode 100644 index f283a70c685..00000000000 --- a/docs/product-editor-development/common-tasks.md +++ /dev/null @@ -1,34 +0,0 @@ -# Common tasks - -> ⚠️ **Notice:** This documentation is currently a **work in progress**. Please be aware that some sections might be incomplete or subject to change. We appreciate your patience and welcome any contributions! - -## Adding a group/section/field next to an existing one - -Here's a snippet that adds a new block to the catalog section, between the first and second fields (order 15): - -```php -use Automattic\WooCommerce\Admin\BlockTemplates\BlockInterface; - -if ( ! function_exists( 'YOUR_PREFIX_add_block_after_categories' ) ) { - /** - * Add a new block to the template. - */ - function YOUR_PREFIX_add_block_after_categories( BlockInterface $product_categories_field ) { - $product_categories_field->get_parent()->add_block( - [ - 'id' => 'your-prefix-id', - 'blockName' => 'woocommerce/product-checkbox-field', - 'order' => $product_categories_field->get_order() + 5, - 'attributes' => [ - 'label' => 'Your Checkbox', - 'property' => 'your_checkbox_bool_property', - ], - ] - ); - } -} -add_action( 'woocommerce_block_template_area_product-form_after_add_block_product-categories', 'YOUR_PREFIX_add_block_after_categories' ); -``` - -Result: -![Adding field next to other field](https://woocommerce.files.wordpress.com/2023/09/adding-field-next-to-other-field.png) diff --git a/packages/js/product-editor/changelog/doc-handbook-1.1 b/packages/js/product-editor/changelog/doc-handbook-1.1 new file mode 100644 index 00000000000..885d3748f6d --- /dev/null +++ b/packages/js/product-editor/changelog/doc-handbook-1.1 @@ -0,0 +1,5 @@ +Significance: patch +Type: dev +Comment: Add blocks documentation + + diff --git a/packages/js/product-editor/src/blocks/README.md b/packages/js/product-editor/src/blocks/README.md new file mode 100644 index 00000000000..bc00c732f23 --- /dev/null +++ b/packages/js/product-editor/src/blocks/README.md @@ -0,0 +1,7 @@ +# Product Editor Blocks + +This directory contains reusable blocks for the product editor. + +## Reusable blocks + +### [woocommerce/product-checkbox-field](checkbox/README.md) diff --git a/plugins/woocommerce/changelog/doc-handbook-1.1 b/plugins/woocommerce/changelog/doc-handbook-1.1 new file mode 100644 index 00000000000..676960fb9d5 --- /dev/null +++ b/plugins/woocommerce/changelog/doc-handbook-1.1 @@ -0,0 +1,5 @@ +Significance: patch +Type: dev +Comment: Add reference to product editor handbook + + diff --git a/plugins/woocommerce/src/Admin/Features/ProductBlockEditor/ProductTemplates/README.md b/plugins/woocommerce/src/Admin/Features/ProductBlockEditor/ProductTemplates/README.md index c3bbd31558b..3270a7c7770 100644 --- a/plugins/woocommerce/src/Admin/Features/ProductBlockEditor/ProductTemplates/README.md +++ b/plugins/woocommerce/src/Admin/Features/ProductBlockEditor/ProductTemplates/README.md @@ -7,7 +7,7 @@ General interfaces for interacting with block templates are located in the ## Usage -For more examples and best practices, please see the Product Editor Development Handbook. +For more information on how to extend the product editor, please see the [Product Editor Development Handbook](../../../../../../../docs/product-editor-development/README.md). ### Adding a new group to product editor templates after an existing group