From 2ed9eadaeb7665f92dc3885217a6f8e5d86b34e8 Mon Sep 17 00:00:00 2001 From: Nathan Silveira Date: Thu, 28 Sep 2023 15:40:50 -0300 Subject: [PATCH] Create initial version of Product Editor Development Handbook (#40309) * Add markdown for testing * Revert "Add markdown for testing" This reverts commit 63a9fc9f441b97db15bb9ee40c46c38033f2e235. * Add new folder with block product editor docs * Iterate over the documentation * Iterate over documentation * Add screenshot * Iterate over doc * Iterate over documentation * Iterate over documentation * Add sample comment * Rename folder * Add FAQ and comments * More changes * Remove unused README * Iterate over documentation * Implement lint changes * Implement lint changes * Add changelog * Remove placeholder readmes * Remove stale references * Remove _media folder and add images to developer.woocommerce.com * Remove placeholder docs * Improve wording for 'non-standard applications' * Convert example to new template API hook * Fix snippet * Iterate over code review suggestions * Replace product editor structure image * Update image reference * Increment example in common-tasks * Update add a field next to an existing one sample --- docs/product-editor-development/README.md | 18 ++++++++++ .../common-tasks.md | 34 +++++++++++++++++++ 2 files changed, 52 insertions(+) create mode 100644 docs/product-editor-development/README.md create mode 100644 docs/product-editor-development/common-tasks.md diff --git a/docs/product-editor-development/README.md b/docs/product-editor-development/README.md new file mode 100644 index 00000000000..ef66a11de0f --- /dev/null +++ b/docs/product-editor-development/README.md @@ -0,0 +1,18 @@ +# Developing extensions for the product editor + +> ⚠️ **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! + +This handbook is a guide for extension developers looking to add support for the new product editor in their extensions. The product editor uses [Gutenberg's Block Editor](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-editor), which is going to help WooCommerce evolve alongside the WordPress ecosystem. + +The product editor's UI consists of Groups (currently rendered as tabs), Sections, and Fields, which are all blocks. + +![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. + +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. + + +## Index + +- [Common tasks](common-tasks.md) diff --git a/docs/product-editor-development/common-tasks.md b/docs/product-editor-development/common-tasks.md new file mode 100644 index 00000000000..f283a70c685 --- /dev/null +++ b/docs/product-editor-development/common-tasks.md @@ -0,0 +1,34 @@ +# 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)