From 50396961b0fb280583d9f14f655eb403d0835e70 Mon Sep 17 00:00:00 2001 From: Brent MacKinnon Date: Thu, 30 May 2024 16:22:39 -0300 Subject: [PATCH] Adding tutorials for Extensible Product Type Onboarding and Tour Guide (#48024) --- docs/docs-manifest.json | 20 ++++- ...roducts-to-add-products-onboarding-list.md | 76 ++++++++++++++++++ .../creating-custom-product-tours.md | 77 +++++++++++++++++++ 3 files changed, 172 insertions(+), 1 deletion(-) create mode 100644 docs/extension-development/adding-custom-products-to-add-products-onboarding-list.md create mode 100644 docs/extension-development/creating-custom-product-tours.md diff --git a/docs/docs-manifest.json b/docs/docs-manifest.json index 1d45bbc6d48..d303c37e787 100644 --- a/docs/docs-manifest.json +++ b/docs/docs-manifest.json @@ -432,6 +432,15 @@ "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/extension-development/data-storage.md", "id": "b3e0b17ca74596e858c26887c1e4c8ee6c8f6102" }, + { + "post_title": "How to create custom product tours", + "menu_title": "How to create custom product tours", + "tags": "how-to", + "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/extension-development/creating-custom-product-tours.md", + "hash": "0c92334bb1ac4da6f3e60c9d8ad7fbe8e0854c4c808049ce116df1e4d6f70329", + "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/extension-development/creating-custom-product-tours.md", + "id": "7b6e4726678c0280f050dba86b9f7ea1fc417dea" + }, { "post_title": "Classes in WooCommerce", "menu_title": "Classes in WooCommerce", @@ -459,6 +468,15 @@ "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/extension-development/building-your-first-extension.md", "id": "278c2822fe06f1ab72499a757ef0c4981cfbffb5" }, + { + "post_title": "How to add custom product types to Add Products onboarding list", + "menu_title": "Add custom product types to Add Products onboarding list", + "tags": "how-to", + "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/extension-development/adding-custom-products-to-add-products-onboarding-list.md", + "hash": "60e50ef5d7e2ac6d0745c31031140df1dbb3c1b8724230cab1eaedebe3814688", + "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/extension-development/adding-custom-products-to-add-products-onboarding-list.md", + "id": "747321d7fd2eb5c9c3351ea38374dfc80d3ec968" + }, { "post_title": "How to add actions and filters", "menu_title": "Add actions and filters", @@ -1305,5 +1323,5 @@ "categories": [] } ], - "hash": "4b21f13102730165225dfb14ca0e448f66be236867a000e807d4b5327ec02aa5" + "hash": "4a7c8981de659b226972039904b0c41aa9451f7501ffd52f0c216084cdf093b6" } \ No newline at end of file diff --git a/docs/extension-development/adding-custom-products-to-add-products-onboarding-list.md b/docs/extension-development/adding-custom-products-to-add-products-onboarding-list.md new file mode 100644 index 00000000000..4d50b8e4d31 --- /dev/null +++ b/docs/extension-development/adding-custom-products-to-add-products-onboarding-list.md @@ -0,0 +1,76 @@ +--- +post_title: How to add custom product types to Add Products onboarding list +menu_title: Add custom product types to Add Products onboarding list +tags: how-to +--- + +## Introduction + +WooCommerce allows developers to extend the product type onboarding list, offering a more customizable and engaging experience during the Add Products onboarding task. This tutorial will guide you through adding custom product types to your WooCommerce store using the `experimental_woocommerce_tasklist_product_types` JavaScript filter. + +## Prerequisites + +- A basic understanding of JavaScript and PHP. +- WooCommerce 8.8 or later installed on your WordPress site. + +## Step 1: Adding a JavaScript Filter + +To add a new product type to the onboarding list, we'll utilize the `@wordpress/hooks` package, specifically the addFilter function. If you're not already familiar, `@wordpress/hooks` allows you to modify or extend features within the WordPress and WooCommerce ecosystem without altering the core code. + +First, ensure you have the `@wordpress/hooks` package installed. If not, you can add it to your project using `npm` or `yarn`: + +`npm install @wordpress/hooks` + +or: + +`yarn add @wordpress/hooks` + +Next, add the following JavaScript code to your project. This code snippet demonstrates how to add a "custom product" type to the onboarding list: + +```javascript +/** +* External dependencies +*/ +import { addFilter } from '@wordpress/hooks'; +import { Icon, chevronRight } from '@wordpress/icons'; +import { __ } from '@wordpress/i18n'; +import FolderMultipleIcon from 'gridicons/dist/folder-multiple'; + +addFilter( + 'experimental_woocommerce_tasklist_product_types', + 'custom-product', + (productTypes) => [ + ...productTypes, + { + key: 'custom-product', + title: __('Custom product', 'custom-product'), + content: __('Create an awesome custom product.', 'custom-product'), + before: , + after: , + onClick: () => { + } + }, + ] +); +``` + +This filter adds a new product type called "Custom Product" with a brief description and icons before and after the title for a visually appealing presentation. + +## Step 2: Optional - Customizing the onClick Handler + +By default, if no onClick handler is supplied, the onboarding task will utilize the default CSV template handler. To customize this behavior, you can specify your own onClick handler within the product type object. + +## Step 3: Modifying the CSV Template Path (Optional) + +If you wish to use a different CSV template for your custom product type, you can modify the template path using the woocommerce_product_template_csv_file_path filter in PHP. Here's an example of how to change the template path: + +```php +add_filter('woocommerce_product_template_csv_file_path', function($path) { + // Specify your custom template path here + return $newPath; +}); +``` + +## Conclusion + +With WooCommerce, extending the product type onboarding list is straightforward and offers significant flexibility for customizing the onboarding experience. By following the steps outlined in this tutorial, you can enhance your WooCommerce store and make the Add Products task more relevant and helpful to your specific needs. diff --git a/docs/extension-development/creating-custom-product-tours.md b/docs/extension-development/creating-custom-product-tours.md new file mode 100644 index 00000000000..6b41146363e --- /dev/null +++ b/docs/extension-development/creating-custom-product-tours.md @@ -0,0 +1,77 @@ +--- +post_title: How to create custom product tours +menu_title: How to create custom product tours +tags: how-to +--- + +## Introduction + +WooCommerce allows developers to extend or replace the product tour, offering a more customizable and engaging experience during product creation. This tutorial will guide you through adding a custom product tour to your WooCommerce store using the `experimental_woocommerce_admin_product_tour_steps` JavaScript filter. + +This works in conjunction with the ability to customize the product type onboarding list. + +## Prerequisites + +- A basic understanding of JavaScript and PHP. +- WooCommerce 8.8 or later installed on your WordPress site. + +## Adding a JavaScript Filter + +To alter or create a product tour, we'll utilize the `@wordpress/hooks` package, specifically the `addFilter` function. If you're not already familiar, `@wordpress/hooks` allows you to modify or extend features within the WordPress and WooCommerce ecosystem without altering the core code. + +First, ensure you have the `@wordpress/hooks` package installed. If not, you can add it to your project using `npm` or `yarn`: + +`npm install @wordpress/hooks` + +or: + +`yarn add @wordpress/hooks` + +Next, add the following JavaScript code to your project. This code snippet demonstrates how to replace the product tour with an entire custom one: + +```javascript +/** +* External dependencies +*/ +import { addFilter } from '@wordpress/hooks'; +import { __ } from '@wordpress/i18n'; + +addFilter( + experimental_woocommerce_admin_product_tour_steps, + 'custom-product', + (tourSteps, tourType) => { + if ('custom-product' !== tourType) { + return tourSteps; +} + + return [ + { + referenceElements: { + desktop: '#title',// The element to highlight + }, + focusElement: { + desktop: '#title',// A form element to be focused + }, + meta: { + name: 'product-name', // Step name + heading: __( 'Product name', 'custom-product' ), + descriptions: { + desktop: __( + 'Start typing your new product name here. This will be what your customers will see in your store.', + 'custom-product' + ), + }, + }, + }, + ]; + } +); +``` + +This filter replaces the entire product tour for a `custom-product` product type. Using built-in JavaScript array manipulation functions, you can also customize the default tour (by altering, adding, or removing steps). + +The `tourType` is set by the `tutorial_type` GET parameter. + +## Conclusion + +With WooCommerce, extending and customizing the product tour is straightforward and offers significant flexibility for customizing the onboarding experience. By following the steps outlined in this tutorial, you can enhance your WooCommerce store and make the Add Products tour more relevant and helpful to your specific needs.