From e3f350cffc47c5d2f7f59909998c2c0f84b15120 Mon Sep 17 00:00:00 2001 From: Nathan Schneider Date: Fri, 6 Oct 2023 11:08:58 -0300 Subject: [PATCH 1/8] Add Product Editor Extensibility Guidelines --- docs/product-editor-development/README.md | 2 +- ...product-editor-extensibility-guidelines.md | 97 +++++++++++++++++++ 2 files changed, 98 insertions(+), 1 deletion(-) create mode 100644 docs/product-editor-development/product-editor-extensibility-guidelines.md diff --git a/docs/product-editor-development/README.md b/docs/product-editor-development/README.md index 5882c1cfd4a..1c76c815348 100644 --- a/docs/product-editor-development/README.md +++ b/docs/product-editor-development/README.md @@ -4,7 +4,7 @@ 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. +The product editor's UI consists of Groups (currently rendered as tabs), Sections, and Fields, which are all blocks. For guidelines on how to extend the product editor (e.g. where to add blocks), please refer to the [Product Editor Extensibility Guidelines](./product-editor-extensibility-guidelines.md). ![Product editor structure](https://woocommerce.files.wordpress.com/2023/09/groups-sections-fields.jpg) diff --git a/docs/product-editor-development/product-editor-extensibility-guidelines.md b/docs/product-editor-development/product-editor-extensibility-guidelines.md new file mode 100644 index 00000000000..8bdbb89f561 --- /dev/null +++ b/docs/product-editor-development/product-editor-extensibility-guidelines.md @@ -0,0 +1,97 @@ +# Product Editor Extensibility Guidelines + +## Form Extensibility + +Our research shows that merchants think in terms of tasks and goals while creating new products in Woo. For example, adding or editing a product price is a separate task from uploading images or managing inventory. + +For this reason, the new product form features tabs that correspond with these tasks. Simply speaking, they are separate views where different form features live. As a developer, you can add your extension to any of these views and offer merchants the information and tools they need to create better, more successful products. + +There are several ways to extend the new product form: from a single field to a whole section containing multiple fields and tables. These extension points are tightly linked to the form structure, giving you plenty of freedom to create a great user experience. + +Like everything in the new product form, each extension point is a separate block. However, each existing block can be extended the same as the Block Editor, so for the sake of a consistent and smooth user experience, try to integrate your extension into an existing block before creating a new one. + +## Product form tabs + +The new product form consists of areas displayed as tabs. Each is a separate view and may contain any number of sections. All areas serve a specific purpose, allowing merchants to quickly find the information they’re looking for (both in default Woo features and extensions). + +* **General**: Essential product information, including the name, image, and description. This tab is also where key features live for non-standard product types: downloads, groups, links, etc. + +* **Organization**: This tab contains all the data used to organize and categorize product information: from categories to attributes. Best for extensions that provide new ways to describe products, e.g., product identifiers, statuses, special tags, etc. + +* **Pricing**: List price, sale price, and tax options. Best for extensions that allow merchants to set up additional payment methods (e.g., Subscriptions) or add advanced pricing schemes, like wholesale. + +* **Inventory**: Basic inventory settings and stock management options. Here merchants come to update the quantity at hand or mark the product as out of stock. Best for extensions that enable conditional inventory management, dropshipping options, or various restrictions. + +* **Shipping**: All the information merchants need to enter to present customers with accurate shipping rates at checkout. Best for physical product details that may impact shipping (e.g. capacity or volume), additional shipping carrier settings, or custom shipping options. + +* **Variations**: Contains product options and variations. It is the only tab that doesn’t support extensibility in its current form (you can add your extension to the variation details page as well as provide custom update actions triggered from the table view or the bulk editor). + +## Where should your extension go? + +Depending on the type of your extension (and your use case), you can pick an interface location that best suits how users will interact with it. + +To choose, put yourself in the merchant’s shoes: where would you go to find this feature? What is it related to? Adding your extension to a group of similar features will help merchants navigate the form and make it easier for them to find your extension. + +### Field + +Field extensions are the simplest type of extension. They can add new, replace, and expand existing form fields in any section, hide fields, and change form defaults. + +#### ✅ What they are for: + +* Single-field, supplementary features +* Showing or hiding form elements depending on specific conditions + +#### ❌ What they aren’t for: + +* Multi-field or multi-step forms +* Complex tables + +#### Use cases + +* Adding extra product details, f.e. volume under Shipping +* Entering custom data, f.e. color or date and time +* Selecting from a third-party system, f.e. warranty type + +### Group + +Groups add extra fields to existing form sections. They are small forms with a low to medium level of complexity. This interface location works best for extensions that add extra features that build off an existing Woo functionality. + +#### ✅ What they are for: + +* Relevant features that can be crucial to merchants’ product creation flow +* 2-5 field forms with limited functionality, f.e. dimensions or tax settings +* Lists of items, f.e. attachments, channels, or accounts + +#### ❌ What they aren’t for: + +* Simple extensions with 1-2 fields +* Multi-step forms and complex tables +* Read-only descriptions, setup guides, and advertisements + +#### Use cases + +* Adding extra product details, f.e. measurements under Shipping +* Setting up social channels in the Visibility section in the General tab +* Changing the VAT tax settings in the Pricing tab + +### Section + +Sections are significant parts of the form that may consist of multiple groups and fields. They should be used sparsely throughout the form, so merchants are not overwhelmed with options while filling out the information about their products. + +#### ✅ What they are for: + +* Complex forms with multiple fields, tables, and list items +* Standalone features that that doesn’t build off of anything else +* Extensions that rely on user-created items, such as tags or attributes + +#### ❌ What they aren’t for: + +* Simple extensions with 1-2 fields +* Read-only descriptions, setup guides, and advertisements +* Multi-step setup wizards and external content + +#### Use cases + +* Adding product labels with a robust interactive preview +* Managing product warranty options +* Creating product packages and bundles From 4a97065da239189f11aea90778f5a86fb3ad1b21 Mon Sep 17 00:00:00 2001 From: Nathan Schneider Date: Fri, 6 Oct 2023 11:49:10 -0300 Subject: [PATCH 2/8] Fix markdown lint issues --- .../product-editor-extensibility-guidelines.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/product-editor-development/product-editor-extensibility-guidelines.md b/docs/product-editor-development/product-editor-extensibility-guidelines.md index 8bdbb89f561..be3afd47b70 100644 --- a/docs/product-editor-development/product-editor-extensibility-guidelines.md +++ b/docs/product-editor-development/product-editor-extensibility-guidelines.md @@ -36,12 +36,12 @@ To choose, put yourself in the merchant’s shoes: where would you go to find th Field extensions are the simplest type of extension. They can add new, replace, and expand existing form fields in any section, hide fields, and change form defaults. -#### ✅ What they are for: +#### ✅ What they are for * Single-field, supplementary features * Showing or hiding form elements depending on specific conditions -#### ❌ What they aren’t for: +#### ❌ What they aren’t for * Multi-field or multi-step forms * Complex tables @@ -56,13 +56,13 @@ Field extensions are the simplest type of extension. They can add new, replace, Groups add extra fields to existing form sections. They are small forms with a low to medium level of complexity. This interface location works best for extensions that add extra features that build off an existing Woo functionality. -#### ✅ What they are for: +#### ✅ What they are for * Relevant features that can be crucial to merchants’ product creation flow * 2-5 field forms with limited functionality, f.e. dimensions or tax settings * Lists of items, f.e. attachments, channels, or accounts -#### ❌ What they aren’t for: +#### ❌ What they aren’t for * Simple extensions with 1-2 fields * Multi-step forms and complex tables @@ -78,13 +78,13 @@ Groups add extra fields to existing form sections. They are small forms with a l Sections are significant parts of the form that may consist of multiple groups and fields. They should be used sparsely throughout the form, so merchants are not overwhelmed with options while filling out the information about their products. -#### ✅ What they are for: +#### ✅ What they are for * Complex forms with multiple fields, tables, and list items * Standalone features that that doesn’t build off of anything else * Extensions that rely on user-created items, such as tags or attributes -#### ❌ What they aren’t for: +#### ❌ What they aren’t for * Simple extensions with 1-2 fields * Read-only descriptions, setup guides, and advertisements From d512e6efbbe8ec7f4477405a9f6bec95975d3cb0 Mon Sep 17 00:00:00 2001 From: Nathan Schneider Date: Wed, 11 Oct 2023 16:16:32 -0300 Subject: [PATCH 3/8] Increment doc based on feedback --- ...product-editor-extensibility-guidelines.md | 36 ++++--------------- 1 file changed, 6 insertions(+), 30 deletions(-) diff --git a/docs/product-editor-development/product-editor-extensibility-guidelines.md b/docs/product-editor-development/product-editor-extensibility-guidelines.md index be3afd47b70..7b8944af374 100644 --- a/docs/product-editor-development/product-editor-extensibility-guidelines.md +++ b/docs/product-editor-development/product-editor-extensibility-guidelines.md @@ -8,11 +8,9 @@ For this reason, the new product form features tabs that correspond with these t There are several ways to extend the new product form: from a single field to a whole section containing multiple fields and tables. These extension points are tightly linked to the form structure, giving you plenty of freedom to create a great user experience. -Like everything in the new product form, each extension point is a separate block. However, each existing block can be extended the same as the Block Editor, so for the sake of a consistent and smooth user experience, try to integrate your extension into an existing block before creating a new one. - ## Product form tabs -The new product form consists of areas displayed as tabs. Each is a separate view and may contain any number of sections. All areas serve a specific purpose, allowing merchants to quickly find the information they’re looking for (both in default Woo features and extensions). +The new product form consists of groups displayed as tabs. Each is a separate view and may contain any number of sections. All groups serve a specific purpose, allowing merchants to quickly find the information they’re looking for (both in default Woo features and extensions). * **General**: Essential product information, including the name, image, and description. This tab is also where key features live for non-standard product types: downloads, groups, links, etc. @@ -24,7 +22,7 @@ The new product form consists of areas displayed as tabs. Each is a separate vie * **Shipping**: All the information merchants need to enter to present customers with accurate shipping rates at checkout. Best for physical product details that may impact shipping (e.g. capacity or volume), additional shipping carrier settings, or custom shipping options. -* **Variations**: Contains product options and variations. It is the only tab that doesn’t support extensibility in its current form (you can add your extension to the variation details page as well as provide custom update actions triggered from the table view or the bulk editor). +* **Variations**: Contains product options and variations. Allows merchants to create variations and set up their attributes, such as color, size, or material. Best for extensions that add new types of variations or allow merchants to manage them in a different way. ## Where should your extension go? @@ -32,9 +30,9 @@ Depending on the type of your extension (and your use case), you can pick an int To choose, put yourself in the merchant’s shoes: where would you go to find this feature? What is it related to? Adding your extension to a group of similar features will help merchants navigate the form and make it easier for them to find your extension. -### Field +### Fields -Field extensions are the simplest type of extension. They can add new, replace, and expand existing form fields in any section, hide fields, and change form defaults. +Field extensions are the simplest type of extension. They can add new, replace, and expand existing form fields in any section, and hide fields. #### ✅ What they are for @@ -52,31 +50,9 @@ Field extensions are the simplest type of extension. They can add new, replace, * Entering custom data, f.e. color or date and time * Selecting from a third-party system, f.e. warranty type -### Group +### Sections -Groups add extra fields to existing form sections. They are small forms with a low to medium level of complexity. This interface location works best for extensions that add extra features that build off an existing Woo functionality. - -#### ✅ What they are for - -* Relevant features that can be crucial to merchants’ product creation flow -* 2-5 field forms with limited functionality, f.e. dimensions or tax settings -* Lists of items, f.e. attachments, channels, or accounts - -#### ❌ What they aren’t for - -* Simple extensions with 1-2 fields -* Multi-step forms and complex tables -* Read-only descriptions, setup guides, and advertisements - -#### Use cases - -* Adding extra product details, f.e. measurements under Shipping -* Setting up social channels in the Visibility section in the General tab -* Changing the VAT tax settings in the Pricing tab - -### Section - -Sections are significant parts of the form that may consist of multiple groups and fields. They should be used sparsely throughout the form, so merchants are not overwhelmed with options while filling out the information about their products. +Sections are significant parts of the form that may consist of multiple fields. They should be used sparsely throughout the form, so merchants are not overwhelmed with options while filling out the information about their products. #### ✅ What they are for From d4da4898b9af35cf86cdb65a6205f42405be9da0 Mon Sep 17 00:00:00 2001 From: Nathan Schneider Date: Wed, 25 Oct 2023 16:14:10 -0300 Subject: [PATCH 4/8] Update extensibility guidelines --- ...product-editor-extensibility-guidelines.md | 42 +++++++++++++++++-- 1 file changed, 38 insertions(+), 4 deletions(-) diff --git a/docs/product-editor-development/product-editor-extensibility-guidelines.md b/docs/product-editor-development/product-editor-extensibility-guidelines.md index 7b8944af374..9a52e3bf306 100644 --- a/docs/product-editor-development/product-editor-extensibility-guidelines.md +++ b/docs/product-editor-development/product-editor-extensibility-guidelines.md @@ -10,6 +10,8 @@ There are several ways to extend the new product form: from a single field to a ## Product form tabs +![Product form tabs](https://woocommerce.files.wordpress.com/2023/10/product-form-tabs.gif) + The new product form consists of groups displayed as tabs. Each is a separate view and may contain any number of sections. All groups serve a specific purpose, allowing merchants to quickly find the information they’re looking for (both in default Woo features and extensions). * **General**: Essential product information, including the name, image, and description. This tab is also where key features live for non-standard product types: downloads, groups, links, etc. @@ -32,7 +34,7 @@ To choose, put yourself in the merchant’s shoes: where would you go to find th ### Fields -Field extensions are the simplest type of extension. They can add new, replace, and expand existing form fields in any section, and hide fields. +Fields are the simplest type of extension. They let users add extra product information, replace or manage the visibility of other fields assigned to a specific product type, and control the contents of other fields. #### ✅ What they are for @@ -44,6 +46,8 @@ Field extensions are the simplest type of extension. They can add new, replace, * Multi-field or multi-step forms * Complex tables +Field extensions should always be logically related to the form area they are in. For example, if you’re building a dropshipping plugin, your warehouse selection field should live in the first section of the Inventory group. To ensure an excellent experience for our merchants, we do not recommend placing it in a separate group, subgroup, or section. + #### Use cases * Adding extra product details, f.e. volume under Shipping @@ -52,12 +56,38 @@ Field extensions are the simplest type of extension. They can add new, replace, ### Sections -Sections are significant parts of the form that may consist of multiple fields. They should be used sparsely throughout the form, so merchants are not overwhelmed with options while filling out the information about their products. +Sections add extra fields to existing form sections. They are small forms with a low to medium level of complexity. This interface location works best for extensions that add extra features that build off an existing Woo functionality. + +#### ✅ What they are for + +* Relevant features that can be crucial to merchants’ product creation flow +* 2-5 field forms with simple functionality, e.g., dimensions or tax settings +* Lists of items, e.g., attachments, channels, or accounts + +#### ❌ What they aren’t for + +* Simple extensions with 1-2 fields +* Multi-step forms and complex tables +* Read-only descriptions, setup guides, and advertisements + +#### 💡Example + +If you’re developing an extension that allows merchants to upload 360 images or videos, you could add it as a field or a button in the Images section in the General tab. This way, merchants can create the perfect product gallery without jumping between multiple tabs. + +#### Other use cases include + +* Adding extra product details, e.g., measurements under Shipping +* Setting up social channels in the Visibility section in the General tab +* Changing the VAT tax settings in the Pricing tab + +# Subgroups + +Subgroups are significant parts of the form that may consist of multiple groups and fields. They should be used sparsely throughout the form, so merchants are not overwhelmed with options while filling out the information about their products. #### ✅ What they are for * Complex forms with multiple fields, tables, and list items -* Standalone features that that doesn’t build off of anything else +* Standalone features that don’t build off of anything else * Extensions that rely on user-created items, such as tags or attributes #### ❌ What they aren’t for @@ -66,7 +96,11 @@ Sections are significant parts of the form that may consist of multiple fields. * Read-only descriptions, setup guides, and advertisements * Multi-step setup wizards and external content -#### Use cases +#### 💡Example + +If you’re working on a plugin that allows merchants to offer discounts based on the number of purchased items, you may consider adding a new section in the Pricing tab. This will give you enough space to present the information in a legible, easy-to-navigate manner. + +#### Other use cases include * Adding product labels with a robust interactive preview * Managing product warranty options From 6d10a7e9eeb8c058dcbcfa4ec9844a537599c250 Mon Sep 17 00:00:00 2001 From: Nathan Silveira Date: Mon, 30 Oct 2023 17:28:05 -0300 Subject: [PATCH 5/8] Update product-editor-extensibility-guidelines.md --- .../product-editor-extensibility-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/product-editor-development/product-editor-extensibility-guidelines.md b/docs/product-editor-development/product-editor-extensibility-guidelines.md index 9a52e3bf306..3266acd8fc4 100644 --- a/docs/product-editor-development/product-editor-extensibility-guidelines.md +++ b/docs/product-editor-development/product-editor-extensibility-guidelines.md @@ -80,7 +80,7 @@ If you’re developing an extension that allows merchants to upload 360 images o * Setting up social channels in the Visibility section in the General tab * Changing the VAT tax settings in the Pricing tab -# Subgroups +### Subgroups Subgroups are significant parts of the form that may consist of multiple groups and fields. They should be used sparsely throughout the form, so merchants are not overwhelmed with options while filling out the information about their products. From 7c44e6d67097a7ad97a59e4de84c6259bb482f1a Mon Sep 17 00:00:00 2001 From: Matt Sherman Date: Thu, 16 Nov 2023 21:02:03 -0500 Subject: [PATCH 6/8] Updates based on latest guidelines draft --- ...product-editor-extensibility-guidelines.md | 243 ++++++++++++++---- 1 file changed, 186 insertions(+), 57 deletions(-) diff --git a/docs/product-editor-development/product-editor-extensibility-guidelines.md b/docs/product-editor-development/product-editor-extensibility-guidelines.md index 3266acd8fc4..be1188733e6 100644 --- a/docs/product-editor-development/product-editor-extensibility-guidelines.md +++ b/docs/product-editor-development/product-editor-extensibility-guidelines.md @@ -1,107 +1,236 @@ # Product Editor Extensibility Guidelines +> ⚠️ **Notice:** These guidelines are currently a **work in progress**. Please be aware that some details might be incomplete or subject to change. We appreciate your patience and welcome any contributions! + +Changelog: + +- 2021-11-17: Initial version + ## Form Extensibility -Our research shows that merchants think in terms of tasks and goals while creating new products in Woo. For example, adding or editing a product price is a separate task from uploading images or managing inventory. +**Our research shows that merchants think in terms of tasks and goals while creating new products in Woo.** For example, adding or editing a product price is a separate task from uploading images or managing inventory. -For this reason, the new product form features tabs that correspond with these tasks. Simply speaking, they are separate views where different form features live. As a developer, you can add your extension to any of these views and offer merchants the information and tools they need to create better, more successful products. +For this reason, the new product form features groups (tabs) that correspond with these tasks. Simply speaking, they are separate views where different form features live. As a developer, you can extend any of these views and offer merchants the information and tools they need to create better, more successful products. -There are several ways to extend the new product form: from a single field to a whole section containing multiple fields and tables. These extension points are tightly linked to the form structure, giving you plenty of freedom to create a great user experience. +There are several ways to extend the new product form: from a single field to a whole group or section containing multiple fields and tables. These extension points are tightly linked to the form structure, giving you plenty of freedom to create a great user experience. -## Product form tabs +- Product form + - Group + - Section + - Subsection + - Field + - Field + - … + - Subsection + - Field + - Field + - … + - … + - Section + - Subsection + - Field + - Field + - … + - Subsection + - Field + - Field + - … + - … + - … + - Group + … -![Product form tabs](https://woocommerce.files.wordpress.com/2023/10/product-form-tabs.gif) +Like everything in the new product form, each extension point is a separate block. For the sake of a consistent and smooth user experience, try to integrate your extension into an existing group or section before creating a new one. -The new product form consists of groups displayed as tabs. Each is a separate view and may contain any number of sections. All groups serve a specific purpose, allowing merchants to quickly find the information they’re looking for (both in default Woo features and extensions). +### Product form groups (tabs) -* **General**: Essential product information, including the name, image, and description. This tab is also where key features live for non-standard product types: downloads, groups, links, etc. +The new product form consists of groups currently displayed as tabs. Each is a separate view and may contain any number of sections and subsections. All areas serve a specific purpose, allowing merchants to quickly find the information they’re looking for (both in default Woo features and extensions). -* **Organization**: This tab contains all the data used to organize and categorize product information: from categories to attributes. Best for extensions that provide new ways to describe products, e.g., product identifiers, statuses, special tags, etc. +![Product form groups](https://woocommerce.files.wordpress.com/2023/11/product-editor-ext-guidelines-form-groups.gif) -* **Pricing**: List price, sale price, and tax options. Best for extensions that allow merchants to set up additional payment methods (e.g., Subscriptions) or add advanced pricing schemes, like wholesale. +If a tab doesn’t contain any sections, it won’t be shown to merchants. -* **Inventory**: Basic inventory settings and stock management options. Here merchants come to update the quantity at hand or mark the product as out of stock. Best for extensions that enable conditional inventory management, dropshipping options, or various restrictions. +- **General:** Essential product information, including the name, image, and description. This tab is also where key features live for non-standard product types: downloads, groups, links, etc. +- **Organization:** This tab contains all the data used to organize and categorize product information: from categories to attributes. Best for extensions that provide new ways to describe products, e.g., product identifiers, statuses, special tags, etc. +- **Pricing:** List price, sale price, and tax options. Best for extensions that allow merchants to set up additional payment methods (e.g., Subscriptions) or add advanced pricing schemes, like wholesale. +- **Inventory:** Basic inventory settings and stock management options. Here merchants come to update the quantity at hand or mark the product as out of stock. Best for extensions that enable conditional inventory management, dropshipping options, or various restrictions. +- **Shipping:** All the information merchants need to enter to present customers with accurate shipping rates at checkout. Best for physical product details that may impact shipping (e.g. capacity or volume), additional shipping carrier settings, or custom shipping options. +- **Variations:** Contains variation options and product variations. -* **Shipping**: All the information merchants need to enter to present customers with accurate shipping rates at checkout. Best for physical product details that may impact shipping (e.g. capacity or volume), additional shipping carrier settings, or custom shipping options. +Custom product types manage the visibility of the default groups and add new ones. This is particularly useful if a custom product has a unique structure and requires extra information that isn’t included in the default groups. -* **Variations**: Contains product options and variations. Allows merchants to create variations and set up their attributes, such as color, size, or material. Best for extensions that add new types of variations or allow merchants to manage them in a different way. +[Learn more about custom product types](#custom-product-types) -## Where should your extension go? +### Where should your extension go? -Depending on the type of your extension (and your use case), you can pick an interface location that best suits how users will interact with it. +Depending on the type of your extension (and your use case), you can pick the interface location that best suits how users will interact with it. -To choose, put yourself in the merchant’s shoes: where would you go to find this feature? What is it related to? Adding your extension to a group of similar features will help merchants navigate the form and make it easier for them to find your extension. +To choose, put yourself in the merchant’s shoes: where would you go to find this feature? What is it related to? Adding your extension to a group of similar features will help make it easier for merchants to find your extension. + +See the guide below for some practical examples. + +#### Product code extension + +##### What it does + +The extension allows merchants to enter a product identifier, such as ISBN, EAN, or UPC. + +##### Our recommendations + +The identifier is a single piece of information that helps merchants describe and categorize the product across their store and other sales channels. It’s best suited to be added as a field in the Product catalog section in the Organization group. + +[Learn more about fields](#fields) + +#### Ticket extension + +##### What it does + +Merchants can set up and sell tickets with advanced settings, such as unique input fields, expiration dates, restrictions, tiers, and more. + +##### Our recommendations + +With so much advanced functionality, the plugin would best register a new product type and define the structure and appearance of the product form. This could include the tabs at the top of the screen, the subgroups and sections inside, and the default values. + +[Learn more about custom product types](#custom-product-types) ### Fields +![Fields example](https://woocommerce.files.wordpress.com/2023/11/product-editor-ext-guidelines-fields.png) + Fields are the simplest type of extension. They let users add extra product information, replace or manage the visibility of other fields assigned to a specific product type, and control the contents of other fields. -#### ✅ What they are for +✅ **What they *are* for:** -* Single-field, supplementary features -* Showing or hiding form elements depending on specific conditions +- Single-field, supplementary features +- Showing or hiding form elements depending on specific conditions -#### ❌ What they aren’t for +❌ **What they *aren’t* for:** -* Multi-field or multi-step forms -* Complex tables +- Multi-field or multi-step forms +- Complex tables, e.g., permissions, restrictions, shipping volumes, etc +- Embedded third-party experiences and websites -Field extensions should always be logically related to the form area they are in. For example, if you’re building a dropshipping plugin, your warehouse selection field should live in the first section of the Inventory group. To ensure an excellent experience for our merchants, we do not recommend placing it in a separate group, subgroup, or section. +Field extensions should always be logically related to the form area they are in. For example, if you’re building a dropshipping extension, your warehouse selection field should live in the first section of the Inventory group. To ensure an excellent experience for our merchants, we do not recommend placing it in a separate group, section, or subsection. -#### Use cases +**Other use cases include:** -* Adding extra product details, f.e. volume under Shipping -* Entering custom data, f.e. color or date and time -* Selecting from a third-party system, f.e. warranty type +- Adding extra product details, f.e. volume under Shipping +- Entering custom data, f.e. color or date and time +- Selecting from a third-party system, f.e. warranty type -### Sections +### Subsections -Sections add extra fields to existing form sections. They are small forms with a low to medium level of complexity. This interface location works best for extensions that add extra features that build off an existing Woo functionality. +![Subsections example](https://woocommerce.files.wordpress.com/2023/11/product-editor-ext-guidelines-subsections.png) -#### ✅ What they are for +Subsections add extra fields to existing form groups. They are small forms with a low to medium level of complexity. This interface location works best for extensions that add extra features that build off an existing Woo functionality. -* Relevant features that can be crucial to merchants’ product creation flow -* 2-5 field forms with simple functionality, e.g., dimensions or tax settings -* Lists of items, e.g., attachments, channels, or accounts +✅ **What they *are* for:** -#### ❌ What they aren’t for +- Relevant features that can be crucial to merchants’ product creation flow +- 2-5 field forms with simple functionality, e.g., dimensions or tax settings +- Lists of items, e.g., attachments, channels, or accounts -* Simple extensions with 1-2 fields -* Multi-step forms and complex tables -* Read-only descriptions, setup guides, and advertisements +❌ **What they *aren’t* for:** -#### 💡Example +- Simple extensions with 1-2 fields +- Multi-step forms and complex tables +- Read-only descriptions, setup guides, and advertisements + +💡 **Example:** If you’re developing an extension that allows merchants to upload 360 images or videos, you could add it as a field or a button in the Images section in the General tab. This way, merchants can create the perfect product gallery without jumping between multiple tabs. -#### Other use cases include +**Other use cases include:** -* Adding extra product details, e.g., measurements under Shipping -* Setting up social channels in the Visibility section in the General tab -* Changing the VAT tax settings in the Pricing tab +- Adding extra product details, e.g., measurements under Shipping +- Setting up social channels in the Visibility section in the General tab +- Changing the VAT tax settings in the Pricing tab -### Subgroups +### Sections -Subgroups are significant parts of the form that may consist of multiple groups and fields. They should be used sparsely throughout the form, so merchants are not overwhelmed with options while filling out the information about their products. +![Sections example](https://woocommerce.files.wordpress.com/2023/11/product-editor-ext-guidelines-sections.png) -#### ✅ What they are for +Sections are significant parts of the form that may consist of multiple subsections and fields. They should be used sparsely throughout the form, so merchants are not overwhelmed with options while filling out the information about their products. -* Complex forms with multiple fields, tables, and list items -* Standalone features that don’t build off of anything else -* Extensions that rely on user-created items, such as tags or attributes +✅ **What they *are* for:** -#### ❌ What they aren’t for +- Complex forms with multiple fields, tables, and list items +- Standalone features that don’t build off of anything else +- Extensions that rely on user-created items, such as tags or attributes -* Simple extensions with 1-2 fields -* Read-only descriptions, setup guides, and advertisements -* Multi-step setup wizards and external content +❌ **What they *aren’t* for:** -#### 💡Example +- Simple extensions with 1-2 fields +- Read-only descriptions, setup guides, and advertisements +- Multi-step setup wizards and external content -If you’re working on a plugin that allows merchants to offer discounts based on the number of purchased items, you may consider adding a new section in the Pricing tab. This will give you enough space to present the information in a legible, easy-to-navigate manner. +💡 **Example:** -#### Other use cases include +If you’re working on an extension that allows merchants to offer discounts based on the number of purchased items, you may consider adding a new section in the Pricing tab. This will give you enough space to present the information in a legible, easy-to-navigate manner. + +**Other use cases include:** + +- Adding product labels with a robust interactive preview +- Managing product warranty options +- Creating product packages and bundles + +### Top bar (header) *(future feature)* + +![Top bar example](https://woocommerce.files.wordpress.com/2023/11/product-editor-ext-guidelines-top-bar.png) + +Top bar extensions offer supplementary experiences **not vital** to the critical product creation flows. They’re secondary, meaning that they shouldn’t contain information that may impact the product’s overall quality or completeness. + +Each top bar extension has its unique icon in the top navigation bar. Note that when the number of extensions exceeds 4, they’re truncated in a dropdown menu. + +For example, top bar extensions can be used to: + +- Provide product scheduling or extra visibility options, +- Let merchants view additional SEO metadata +- Offer easy access to documentation or step-by-step guides + +Depending on their roles, top bar extensions can be displayed in either a **popover** or a **modal**. + +### Dialog extensions *(future feature)* + +![Dialog example](https://woocommerce.files.wordpress.com/2023/11/product-editor-ext-guidelines-dialog-extensions.png) + +Dialog extensions differ from other extensions as they are unrelated to any section or functionality within the product form. They can connect to third-party systems or come with complex interfaces that require a separate, focused experience. + +Dialogs can have different sizes (small, medium, large, or custom) and trigger locations (text or icon button anywhere in the form or in the form’s top bar). + +✅ **What they *are* for:** + +- Focused experiences that require taking over most of the screen +- Advanced configuration and setup flows +- Dedicated content embedded from a third-party service + +❌ **What they *aren’t* for:** + +- Single-field features or simple settings screens +- Small functionalities that could fit within the form +- Onboarding experiences, product demos, and advertisements + +**Example use cases:** + +- Third-party fulfillment, warehousing, and accounting service integration +- Robust image editing tool with complex interactions +- Media-heavy knowledge base with plenty of videos and interactive tutorials + +## Custom product types + +Custom product types allow you to design a custom form and completely control its structure. They are convenient for extensions that enable merchants to create products from start to finish. + +With custom product types, you can: + +- Add, hide, and reorder groups +- Add and hide sections within a group +- Add and hide subsections and fields + - Includes core fields + - Can be set up conditionally based on a custom field’s value + +Custom product types include niche and specific use cases, such as bookings, tickets, gift cards, rentals, etc. Here’s when we suggest you should consider creating a custom product type: + +- Your extension consists of several different form sections scattered across several different tabs +- Using just your extension, merchants can completely a product +- You want to help merchants create products faster and automate some of their work -* Adding product labels with a robust interactive preview -* Managing product warranty options -* Creating product packages and bundles From f5bd33e083630c12ca41f53124236d5755cf9156 Mon Sep 17 00:00:00 2001 From: Matt Sherman Date: Fri, 17 Nov 2023 10:21:59 -0500 Subject: [PATCH 7/8] Correct changelog date --- .../product-editor-extensibility-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/product-editor-development/product-editor-extensibility-guidelines.md b/docs/product-editor-development/product-editor-extensibility-guidelines.md index be1188733e6..71aa4183d55 100644 --- a/docs/product-editor-development/product-editor-extensibility-guidelines.md +++ b/docs/product-editor-development/product-editor-extensibility-guidelines.md @@ -4,7 +4,7 @@ Changelog: -- 2021-11-17: Initial version +- 2023-11-17: Initial version ## Form Extensibility From f33352591f1ec70d0ac7c9a2cef688ff1e0efa98 Mon Sep 17 00:00:00 2001 From: Matt Sherman Date: Fri, 17 Nov 2023 10:23:26 -0500 Subject: [PATCH 8/8] Slight rewording of extensibility intro --- .../product-editor-extensibility-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/product-editor-development/product-editor-extensibility-guidelines.md b/docs/product-editor-development/product-editor-extensibility-guidelines.md index 71aa4183d55..b9bb372b445 100644 --- a/docs/product-editor-development/product-editor-extensibility-guidelines.md +++ b/docs/product-editor-development/product-editor-extensibility-guidelines.md @@ -12,7 +12,7 @@ Changelog: For this reason, the new product form features groups (tabs) that correspond with these tasks. Simply speaking, they are separate views where different form features live. As a developer, you can extend any of these views and offer merchants the information and tools they need to create better, more successful products. -There are several ways to extend the new product form: from a single field to a whole group or section containing multiple fields and tables. These extension points are tightly linked to the form structure, giving you plenty of freedom to create a great user experience. +There are several ways to extend the new product form: from a single field to a whole group or section containing multiple fields and tables. These extension points are linked to the form structure, giving you plenty of freedom to create a great user experience. - Product form - Group