Documentation for v.9.9.0

Last updated: Aug 27th, 2021

About the plugin

The WooCommerce Products Wizard plugin enables mass-customization features for your store and gives your customers the opportunity to personalize their purchase.

The main task of this plugin is to create a form, which step by step helps customers to choose a kit from all products and categories.

This is possible to show only appropriate products according to the previous steps answers. This way your customer will not be confused while selecting his own configuration.

Also, using the plugin you can create composite products with static children or selected by customers from defined ones.

Moreover, this is possible to get the user selection via email or PDF file while or instead of the usual products ordering workflow.

Plugin thumbnail

Get the plugin Try the lite version

Quick start

Installation

Download the zip file of the plugin from the repository. After go to the admin part of your site to the Plugins - Add New page.

To open the file uploading form click the "Upload Plugin" button on the top.

Installation

After select the downloaded zip file in the form lower, submit it and click "Activate" button.

If you have no activated WooCommerce plugin you will see a notice about this. Products Wizard requires WooCommerce plugin on the site for work.

Creating a wizard

To create a new wizard go to "WooCommerce - Products Wizard" page and click "Add New" button.

Create a wizard

Input a wizard name just for more easy management. Afterm create a few steps using the "Add step" button and save the wizard.

Save the wizard

Output the wizard

Copy the shortcode of the wizard and place it on any page or post you want to see the first results.

Shortcode using

At the results, you should see a similar wizard with a little content within. After you can start to fill the steps by products and text content. Let's going further!

Wizard output

Wizard Settings

Basic settings

Set the post content to use it as a description of the first step.

Click "Add step" button to create the required steps number. You also can sort them using drag and drop.

"Set default cart content from your session" option allows to define the default wizard cart content for the first launch. Open the wizard and go through it selecting products, which should be in a default kit, and stop on the last step. After click "Set default cart" button in admin part to save these products as default. To reset this selection click "Reset default cart" button.

Default wizard behavior removes products from the steps, which are after the active one. To avoid this disable the "Strict cart workflow" setting of the "Behavior" group.

Basic settings

Behavior settings

"Work mode" is an important setting which changes the main wizard's view and behavior. Possible values are:

  • Step by step - output the steps as tabs and doesn't allow to jump from the firsts steps to the lasts. The only way to skip steps is to use the "Skip" or "Go to results" buttons;
  • Free walk - output the steps as tabs and allows to open any step you want;
  • Single step - output all steps at once vertically;
  • Sequence - output all steps vertically but one by one according to the current state.

"Nav action" helps to change the event after the click on a nav button. This is possible to submit and get step, just to get step, do nothing, or use auto smart mode.

"Final redirect URL" is a url to the page, which will be opened after the wizard selection confirmation.

"Check availability rules" setting allow to enable/disable ALL availability rules though the wizard - from steps to generated thumbnail areas.

"Strict cart workflow" removes all products from the steps after the active one. That might be helpful if you have complicated availability rules for products.

"Scrolling to top on the form update" will scroll the page to the top on going next through the wizard.

"The gap on scrolling up (px)" is a top gap after scrolling the page to the top.

"Hide prices" setting can hide the product prices for the plugin's views and output. But keep in mind the prices and Woocommerce cart will stay.

For the products bought using a wizard the "Price discount" setting makes a discount in percentage. Might be overwritten with a product category discount setting or individual product setting for a specific product.

"Price discount type setting controls how the discounted price will be shown. It can be just replaced by a reduced one or shown as a sale.

Behavior settings

Cart settings

"Clear main cart on the wizard confirms" will always truncate the cart of WooCommerce on any wizard confirmation.

"Show steps names in the cart" setting output steps names in the results/PDF table and widget. You can show only selected or all steps.

If you're showing all steps names you can use them in the widget for navigation.

"Reflect products in the main cart immediately" will add and remove products in WooCommerce cart as in the opened wizard.

"Minimum/Maximum products selected" settings defines the limits of the selected products to complete the wizard order.

"Minimum/Maximum total products quantity" settings defines the limits of total quantities of selected products to complete the wizard order.

"Minimum/Maximum products price" settings defines the limits of the selected products total price to complete the wizard order.

Cart settings

Kits settings

"Group products into kits after adding to the main cart" makes products bonded to each other in WooCommerce cart.

"Kits type" change the final view of a kit. With value "Separated lines" It might be separated products, but still bonded. Alternatively, "Combined products" shows only the first product in the cart with other products as sub-lines of this product. You can use the wizard's thumbnail as a product thumbnail instead of the first product's one.

You can select a "Kit base product" to use it as a root product of kits. It will no influence the final price. If the base product is variable then you need to select a variation with all defined attributes. Otherwise, the first product of the wizard's cart will be taken as a root.

You can define a "Base kit price" which will be included to the kit's price by default and have no way to avoid it.

You can define a static "Kit price" value for the combined kit type. This setting overwrites the base kit price and all products prices in the wizard.

This is possible to not calculate kit child products in the cart and calculate the kit as the only cart item.

Enable kit edit button link in the main cart to allow the user to go back to the wizard's page and change the selection. The wizard will be opened with on the last step filled by the kit products and data.

Kits settings

Thumbnail settings

This is possible to show customers how their chosen product combinations might look like. That requires a preliminary configuring of the image canvas. The generated thumbnail will be used as a thumbnail of combined type kits and kits with a pre-defined base product. It also can be output while the wizard workflow.

First of all tick the Generate thumbnail setting and define its Width and Height.

Then this is necessary to place areas on the thumbnail's canvas for further use of them. Click Add item button to add one. The total number of added areas is on the right side of the row near the Clear canvas button.

You can change areas placement using drag and drop, also change their sizes. Open the area settings modal to change its z-index order too. That affects the overlapping areas by each other.

Each area can have a name. This name might be used later to place appropriate images in the area.

Using uploaded images for thumbnail generation

Use the same area name as the name of the [wcpw-step-input type="file"] shortcode to print the uploaded image in the generated thumbnail. For example, you can add a custom logo or photo into the thumbnail.

Also, this is possible to define a default image for an area. It can be replaced later or kept as is. It's better to use a transparent PNG image for better overlapping.

When the canvas is ready it's time to configure products or categories.

Generated thumbnail will be show in widget then any of products is in the cart. To output the thumbnail somewhere else use the [wcpw-generated-thumbnail-url] shortcode to get the thumbnail's link. It can be used, for example, on the results step or results PDF file.

An example of shortcode usage:

<a href="[wcpw-generated-thumbnail-url]" data-rel="prettyPhoto" rel="lightbox">
   <img src="[wcpw-generated-thumbnail-url]" alt="">
</a>
Thumbnail settings

Thumbnail settings

Thumbnail area settings modal

Thumbnail area settings modal

Layout settings

With the "Nav template" setting you can choose how the tabbed views navigation should look like.

"Show sidebar" setting rule the appearance of wizard sidebar.

"Sidebar position" setting allows to place the sidebar left, right or top.

Use the Expand widget by default setting to output the cart widget opened.

This is possible to on/off "Sticky sidebar"

"Sticky sidebar offset top" tunes the gap between the top of the screen and stuck sidebar.

You can show/hide the header and footer.

This is possible to on/off "Sticky header"

"Sticky header offset top" tunes the gap between the top of the screen and stuck header.

"Show steps names" setting output the steps names before forms on one-screen modes.

For single and sequence step modes you can output steps name.

"Table layout strings" defines captions of the "layout" form view.

Layout settings

Steps settings

"Enable description step" enables/disables the first step with description text.

"Description step title" setting sets the description tabs nav item text.

"Enable results step" enables/disables the last step with selection results.

"Results step title" setting sets the results step nav item text.

"Results step description" setting sets the results step description before the table.

"Show results step table" setting on/off the cart table on the result step. For example, might be disabled to use the widget instead.

"Results step contact form" setting sets what ContactForm7 form will be output on the results step lower the products selection table. Using this form you can send emails with the cart content PDF.

PDF attachment

If there is no attached PDF file in the email then add the [wcpw-result-pdf] shortcode in the File attachments field.

Use "Results strings" setting to change result page captions on the result step and PDF.

This is possible to have the inner checkout step. It will be very last of the wizard and allows to send the order right from the wizard without extra page navigation.

Be sure the checkout step description has the [woocommerce_checkout] shortcode to output the default WooCommerce checkout form.

Steps settings

Strings settings

Strings settings allows changing output strings through the workflow.

Strings settings

Controls settings

Controls settings allows to choose which buttons are used in the wizard and their labels.

Moreover, all controls might have different classes for their styling and behavior. As the main plugin styles are based on the Bootstrap 5 framework you can use any from the available styling classes of buttons.

Also, there are a few classes to control buttons text and icons appearing:

  • hide-text - hides text of the button but keeps it for screen readers;
  • hide-text-on-mobile - hides text of the button on small screens but keeps it for screen readers;
  • icon-left - define on which side of the button the icon should appear;
  • icon-right - define on which side of the button the icon should appear;
  • show-icon - always shows a pre-defined button icon. Requires icon-left/right class for work;
  • show-icon-on-mobile - shows a pre-defined button icon on small screens. Requires icon-left/right class for work;

Controls settings

Result PDF settings

PDF customization

To modify the PDF template make a copy of views/result-pdf.php to your active theme (or child theme) directory to woocommerce-products-wizard/result-pdf.php

Result PDF header height in cm allows to define the top header size for each page.

Result PDF header content will be used as the header for each page. Its color and inner padding might be configured right there using CSS. There are a few native shortcodes available for using:

  • [wcpw-result-pdf-page-number] - The current page number;
  • [wcpw-result-pdf-page-total] - Total pages count.

You also can use the ContactForm7 mail shortcodes in case you're using it via "Results step contact form" setting.

Result PDF top description content will be placed before the results table.

Result PDF footer height in cm allows to define the top header size for each page.

Result PDF footer content will be used as the footer for each page. Its color and inner padding might be configured right there using CSS. This is possible to use special shortcodes to output the current page number and total pages number.

Result PDF bottom description content will be placed after the results table.

Result PDF settings

Filter settings

Filter settings allows change strings of the steps filters.

Filter settings

Step settings

Captions

"Title" option allows changing the title of the step.

"Thumbnail" of the step will be used in the navigation of the wizard.

"Top and bottom description" settings help to add the text on the current step before and after products.

You can add custom fields in the description to collect extra data from the customers while they walking through the wizard.

Use [wcpw-step-input name="%SOME-NAME-HERE%"] shortcode for this. It outputs only an input or textarea HTML tag, so you can add the label and other tags manually.

Not all input types are supported

Unsupported field types are: "button", "image", "reset", "submit".

"Name" attribute is required for saving the data. All other required input attributes might be passed the same inline way.

Keep in mind you can get these custom fields data from the customers only through the PDF order file or combined kit type because they will not be saved among the ordinary products in the WooCommerce cart.

You can Handle description with auto tags around and between lines as it is for the page content field.

"Item description source" changes the source of content for the item description. You can output long or short product description or output nothing.

Step captions settings

Query

Select the product categories for using in this step. Products of selected categories will appear on the step.

Also, you can select the product attributes for using in this step. Products of selected attributes will appear on the step. That might be helpful to filter products by an attribute before output. Use product attribute availability rules setting for this.

"Included products" allows output only selected products for this step. This settings overwrites the "categories" setting. So this isn't necessary to set both these settings.

You also can keep these settings empty just to output a blank step with description and custom fields. This also will work.

"Excluded products" allow for removal of the output selected products for this step.

"Exclude already added products of steps" setting might contain steps IDs separated with a comma. If some products of these steps are already in the cart then they will not be shown on the current step.

"Availability rules" is a unified and complex setting to control the step appearance in the wizard. The source of a rule might be a product, product variation, product attribute, product category or custom input value.

There are two possible conditions for a rule: "in cart" and "not in the cart". So this is possible to check if a product, category, or custom field is added or not added to the cart to show the step.

This is possible to choose a few products, attributes or categories per one rule. There is a setting to control the relation within the items. The rule can be met when all or any of these items are in or not in the cart.

For using the product attribute select it at first in the dropdown field and define attribute values terms IDs (not slugs) separated by a comma in the next text input. Here how you can find them.

Moreover, there is a setting to control the relationship of the rule with the next rule, namely any of the rules should be met or few at once.

The number of these rules is unlimited.

"Order" and "Order by" settings allows changing the sorting of products on the output.

"Enable 'Order by' dropdown" setting outputs the usual WooCommerce dropdown to change the products order.

"Products per page" setting changes the products per page quantity.

"Products per page items" setting allows to output a dropdown to change products per page number. Place a numeric value in each line.

Step query settings

Cart

"Individual controls" settings enables/disables add-to-cart/remove buttons on each product block.

«Add to cart» button behavior setting changes what action should be fired after individual add-to-cart action.

"Hide choose element" settings allow hide the radio/checkbox input of each product. The only way to choose a product will be the use of individual controls.

There is a possibility to add to cart by quantity which is more than zero, so this way the "choose" element might be hidden to simplify the interface and use the products quantity input only. "Sold individually" setting shouldn't be enabled this way.

This is possible to don't add products of this step to the cart using special options. You can skip all products of a step or only specific ones. They will be visible in the wizard's workflow but skipped on the passing to the main cart.

"Can select several products" setting allows users to add more than one product of single step and replaced radio buttons by checkboxes.

"Can select several variations per one product" setting changes the variable product behavior. With the "Can select several products" setting it doesn't replace another variation of the same product while adding to the cart.

"Sold individually" setting enables/disable product quantity input.

"Selected items by default" change the default selected products for the step. You can select specific products to output them checked and specific product variations to make them selected by default.

Also, you can set "All items are selected by default" for a step.

"No selected items by default" overwrites the previous two settings at all.

"Default product quantity" settings changes products quantity input default value.

"Minimum products selected" setting indicates how many products should be selected to move to the next step.

"Maximum products selected" setting limits how many products might be selected to move to the next step.

"Minimum product quantity" settings change the minimum product quantity input value.

"Maximum product quantity" settings change the maximum product quantity input value.

Hide the quantity input

If these two settings have equal values then the quantity input might be hidden at all.

"Minimum total products quantity" settings indicates how many products quantity must be selected to move to the next step, i.e. the sum of selected product quantities.

"Maximum total products quantity" settings indicates how many products quantity can be selected to move to the next step, i.e. the sum of selected product quantities.

callout-title

These six min/max options might have one of five possible types:

  • Simple count - a static count value;
  • Count of selected products of step - count of selected products from the other steps;
  • Least product quantity of step - the smallest quantity input value from the other steps products;
  • Greatest product quantity of step - the greatest quantity input value from the other steps products;
  • Sum of products quantities of step - the sum of quantity input values from the other steps products.

To use other steps types set steps IDs separated by a comma as an option's value. You can find these IDs before the titles of steps list in the "Basic" settings group.

Step cart settings

View

"Template" setting change layout of products in the current step. The list is formed of the php-files in the "plugin_directory/views/form/layouts" and "theme_directory/woocommerce-products-wizard/form/layouts" folders.

"Grid column size" setting changes "grid" template settings for different screen size. It based on 12 columns system and four sizes and each value is the part of these 12 columns. For example, for three columns value should be 4 (is 12/3).

"Grid column size then the sidebar is showed" is the same as "Grid column size" but then the sidebar is apparent.

"Item template" setting change view of products in the current step. The list is formed of the php-files in the "plugin_directory/views/form/item" and "theme_directory/woocommerce-products-wizard/form/item" folders.

Merge thumbnail with gallery setting removes the galleries from item views and shows gallery images within thumbnail using carousel.

"Gallery column size" setting is the same as "Grid column size" but for item's gallery grid.

"Variation template" setting change the layout of the variable products options list.

"Enable title link" setting wraps product titles by their links to single pages.

Also, you can show/hide specific product elements using the special settings.

Step view settings

Filters

"Filters" setting allows adding different product filters to the step. You can add any number of filters to the step. Select one of prepared sources at first and then one of the suggested views.

There is a possibility to select "range" view for a product attribute, but keep in mind it will work well only with numeric attribute values.

Each filter will be labeled automatically or you can pre-define its name.

This is possible to include/exclude specific value for taxonomy-based filters, like categories, tags and attributes. Define the required terms IDs separated by a comma.

Also, you can define the default selected filter values the same way.

You can apply the default filer values to the products before user passed the filter.

"Filter position" might be right before the products or in the sidebar. But keep in mind sidebar filter will work only for the tabs mode.

"Expand filter by default" output the filter opened then the step is shown.

For the image viewed filters set the thumbnail size setting. It might be one of the registered named sizes or a pair of integers separated by a comma, like "50,50".

Step filters settings

Step filters settings

Step filter settings modal

Step filter settings modal

Product Settings

"Availability rules" is a unified and complex setting to control the product appearance in the wizard. The source of a rule might be a product, product variation, product attribute, product category or custom input value.

There are two possible conditions for a rule: "in cart" and "not in the cart". So this is possible to check if a product, category, or custom field is added or not added to the cart to show the product.

This is possible to choose a few products, attributes or categories per one rule. There is a setting to control the relation within the items. The rule can be met when all or any of these items are in or not in the cart.

For using the product attribute select it at first in the dropdown field and define attribute values terms IDs (not slugs) separated by a comma in the next text input. Here how you can find them.

Moreover, there is a setting to control the relationship of the rule with the next rule, namely any of the rules should be met or few at once.

You can also set availability rules for each variation of a variable product.

"Variation template" setting change layout of the variable product options list above category settings.

You can add a Discount to the product bought using a wizard. Possible values are:

  • Percentage - define a value from 1 to 100 in percents to make appropriate discount;
  • Fixed - define a value on which product price will be reduced;
  • Precise price - overwrites product's price by the defined one.

This is possible to Attach a wizard to the product to make it works as a usual composite product.

Attached wizard place allows to output the wizard:

  • Before add-to-cart form;
  • After add-to-cart form;
  • In a special separate tab.

Set the Separate tab title if you need.

You can use a special feature to intercept the added to cart product and continue the workflow in a wizard on another page immediately.

First of all, select a value of the Redirect to the wizard on add to cart event setting.

Secondly, define a Redirect link which will be opened after add to cart event for this product.

Set a Wizard's step ID in which the product should be added. If you want the product will be out of any step then set it to any out of steps IDs value.

Generate thumbnail areas data is used to replace generated thumbnail areas with specific images then the product is in the cart. It's necessary to define the area name to be used and the image for pasting. It's also possible to set the availability rules to apply the image to an area. The number of these rules is unlimited.

You can also set the areas data of each variation of a variable product.

More info about the thumbnail generation is here.

Product settings

Category Settings

"Availability rules" is a unified and complex setting to control category products appearance in the wizard. The source of a rule might be a product, product variation, product attribute, product category or custom input value.

There are two possible conditions for a rule: "in cart" and "not in the cart". So this is possible to check if a product, attribute, category, or custom field is added or not added to the cart to show the category products.

This is possible to choose a few products, attributes or categories per one rule. There is a setting to control the relation within the items. The rule can be met when all or any of these items are in or not in the cart.

For using the product attribute select it at first in the dropdown field and define attribute values terms IDs (not slugs) separated by a comma in the next text input. Here how you can find them.

Moreover, there is a setting to control the relationship of the rule with the next rule, namely any of the rules should be met or few at once.

You can add a Discount to category products bought using a wizard. Possible values are:

  • Percentage - define a value from 1 to 100 in percents to make appropriate discount;
  • Fixed - define a value on which products prices will be reduced;
  • Precise price - overwrites products prices by the defined one.

This is possible to Attach a wizard to the product to make it works as a usual composite product.

Attached wizard place allows to output the wizard:

  • Before add-to-cart form;
  • After add-to-cart form;
  • In a special separate tab.

Set the Separate tab title if you need.

You can use a special feature to intercept the added to cart product and continue the workflow in a wizard on another page immediately.

First of all, select a value of the Redirect to the wizard on add to cart event setting.

Secondly, define a Redirect link which will be opened after add to cart event for this category.

Set a Wizard's step ID in which the product should be added. If you want the product will be out of any step then set it to any out of steps IDs value.

Generate thumbnail areas data is used to replace generated thumbnail areas with specific images then any product of the category is in the cart. It's necessary to define the area name to be used and the image for pasting. It's also possible to set the availability rules to apply the image to an area. The number of these rules is unlimited.

More info about the thumbnail generation is here.

Category settings

Plugin Settings

Main Settings

General settings page

You can choose what styles should be included from the plugin.

  • Full is the self-sufficient style file. It applied all required styles to the plugin's elements.
  • Basic styles should be fine if your active theme is based on the "Bootstrap 3/4/5" framework, then the wizard will be styled the same as your active theme. Or if you need some basic styles applied to the wizard's elements and want to add your own extra-styles.
  • None value doesn't include any styles at all. This way you can make a complete custom style from the plugin sources and tools or use your own approach for styling.
  • Custom full styles include the file with your custom styles such as colors, font-size, and so on. To modify it go to the Custom styles sub-page.

If for some reasons you need to disable some of plugin's scripts, change "Scripts including type" setting to "Multiple files" and de-select them in the list lower.

Sometimes server's configuration might have problems with storing sessions. For example, if the wizard can't go next through the steps or loses the cart content on the page update. In this case tick "Store session in the DB" setting which works much reliable but probably a little bit slower.

If you have a cache plugin on your site it might make the wizard's work unpredictable. This way the "Send current state hash via AJAX" setting might help to fix it.

Custom styles

Custom styles settings page

This is possible to reconfigure the plugin's styles according to your needs. Don't forget to choose Custom full styles file value of the Styles including type setting.

In a case of required styles debug disable the Minify custom styles setting to get them more readable. In other cases keep this setting enabled to make the file less and save your customers traffic.

There are two modes of custom styling. The simple mode provides only a few main variables to change, while the advanced one allows to change much more variables and do this more flexible but requires SCSS knowledge. There are all plugin variables available for changing using the text editor.

Sometimes the wizard's font looks very small on specific themes. Adjust the font size setting this way. You can use any CSS units there, like "rem", "px", "pc" and so on. Separately you can change product title and price font sizes.

In a case of a style error you will see the message about it while saving and the styles will not be generated.

In a case you need to return all styles to the initial state click Reset to default button once.

FAQ (frequently asked questions)

The wizard doesn't want to move further through the steps

Some server configurations might have problems with the current session storing. Mostly the “Store session in the DB” setting fixes this problem.

The wizard looks work but returns a static or random output.

Much probably you’re using a caching plugin on your site which makes page content freeze and the wizard output also. In this case, tick the “Send current state hash via AJAX” global setting to change the page URL for each wizard’s state. Mostly, that will help to solve the problem.

I want to collect custom data from users (text or file)

There are two ways to achieve this. Both of them have their own pros and cons.

  • Extra Product Options plugin
  • Step custom fields

Get more information

I want to get products selection via email

This is possible to do. Select a ContactForm7 for use on the results step of the wizard. The email will have an attached PDF file of the user selection.

Get more information

Is there a way to filter the products or steps, based on the user’s choice from the previous step?

This is possible using the unified “Availability rules” setting for steps, categories, products, or variations.

Get more information

Product thumbnail opens a new page instead of a lightbox

Install any good lightbox plugin which supports AJAX actions. For example Responsive Lightbox & Gallery

How to add custom products/steps fields

Sometimes you might need to get some custom data passed by the customers, e.g. custom text, number, file, and so on. There are a couple of different ways to achieve this.

Extra Product Options plugin

The first one is using the Extra Product Options plugin which is compatible with the wizard. It allows to add custom fields to any product. This is necessary to check a couple of settings to make it work.

To make the wizard work with Extra Product Options plugin be sure its settings are:

  • General - Various - Enable plugin for WooCommerce shortcodes is on;
  • Global - Product page - Reset option values after the product is added to the cart is off;

Step custom fields

The second way is to add custom fields to a step using the wizard’s possibilities. Take a look at the Description setting section. For usual WooCommerce order workflow this is necessary to combine the products to kits to save this custom data in orders. Otherwise, if you get your orders using a contact form with the PDF you don't need to use kits, because custom data will be disclosed in the PDF.

Templates Customization

If you want to customize some views of the plugin and don't lose these changes while updating the plugin create the "woocommerce-products-wizard" folder in your active theme (or child theme) directory and copy into it files from the plugin's "views" directory saving the sub-directory hierarchy.

The plugin is trying to get a view from the theme at first, and if it doesn't find this view, it gets the view from the own directory.

PHP Snippets

PHP actions and filters

Actions
Action Description
do_action('wcpw_init', $this) The plugin is init
do_action('wcpw_step_settings_form', $this, $args) Before step settings form HTML in the admin part
do_action('wcpw_get_cart', $postId, $args) Before cart get
do_action('wcpw_before_add_to_cart', $postId, $cartItemKey, $cartItem) Before item is added to cart
do_action('wcpw_after_add_to_cart', $postId, $cartItemKey, $cartItem) After item is added to cart
do_action('wcpw_before_remove_by_product_id', $postId, $productId, $stepId) Before removing a product from cart by ID
do_action('wcpw_after_remove_by_product_id', $postId, $productId, $stepId) After removing a product from cart by ID
do_action('wcpw_before_remove_by_variation', $postId, $variationId, $variation, $stepId) Before removing product from cart by variation
do_action('wcpw_after_remove_by_variation', $postId, $variationId, $variation, $stepId) After removing product from cart by variation
do_action('wcpw_before_remove_by_product_key', $postId, $key) Before removing a product from cart by key
do_action('wcpw_after_remove_by_product_key', $postId, $key) After removing a product from cart by key
do_action('wcpw_before_remove_by_step_id', $postId, $stepId) Before removing an item from cart by step ID
do_action('wcpw_after_remove_by_step_id', $postId, $stepId) After removing an item from cart by step ID
do_action('wcpw_before_truncate', $postId) Before truncating of the cart
do_action('wcpw_after_truncate', $postId) After truncating of the cart
do_action('wcpw_before_output', $args) Before wizard's output via shortcode, view or PDF
do_action('wcpw_dompdf_options', $options, $args) DomPDF options instance
do_action('wcpw_dompdf_instance', $dompdf, $args) DomPDF instance
do_action('wcpw_after_output', $args) After wizard's output via shortcode, view or PDF
do_action('wcpw_before_submit_form', $args) Before main form submit
do_action('wcpw_after_submit_form', $args) After main form submit
do_action('wcpw_before_get_form', $args) Before main form get
do_action('wcpw_after_get_form', $args) After main form get
do_action('wcpw_before_skip_form', $args) Before main form skip
do_action('wcpw_after_skip_form', $args) After main form skip
do_action('wcpw_before_skip_all', $args) Before main form "skip all"
do_action('wcpw_after_skip_all', $args) After main form "skip all"
do_action('wcpw_before_submit_and_skip_all', $args) Before main form "submit and skip all"
do_action('wcpw_after_submit_and_skip_all', $args) After main form "submit and skip all"
do_action('wcpw_before_reset_form', $args) Before main form reset
do_action('wcpw_after_reset_form', $args) After main form reset
do_action('wcpw_before_add_cart_product', $args) Before add product to cart
do_action('wcpw_before_remove_cart_product', $args) Before removing a product from cart
do_action('wcpw_before_update_cart_product', $args) Before update product in cart
do_action('wcpw_before_add_all_to_main_cart', $postId, $cart) Before passing the products to Woocommerce cart
do_action('wcpw_after_add_all_to_main_cart', $postId, $cart, $productsAdded) After passing the products to Woocommerce cart
do_action('wcpw_before_add_to_main_cart', $args) Before passing the product to Woocommerce cart
Filters
Action Description
apply_filters('wcpw_post_type_args', $args); Wizard post type arguments
apply_filters('wcpw_custom_styles_variables', $customVariables); Style custom variables array for overwriting and compiling
apply_filters('wcpw_scss_variables_string', $output); The string of the _variables.scss file of the front part
apply_filters('wcpw_custom_styles_scss_string', $scssString); Custom SCSS string to compile
apply_filters('wcpw_default_cart_content', $defaultCartContent, $postId, $args); Getting default cart content
apply_filters('wcpw_cart', $cart, $postId, $args); Getting cart content
apply_filters('wcpw_cart_step_data', $item, $postId, $key); Getting cart step data item
apply_filters('wcpw_cart_step_data_image_attributes', $attributes, $postId, $item, $key); Image attributes of a cart step data item
apply_filters('wcpw_cart_products_and_variations_ids', $output, $postId, $args); Getting products and variations IDs from the cart
apply_filters('wcpw_cart_categories_ids', $output, $postId, $args); Getting categories IDs from the cart
apply_filters('wcpw_cart_attribute_values', $output, $postId, $attribute, $args); Getting product attribute values IDs from the cart
apply_filters('wcpw_cart_by_step_id', $output, $postId, $stepId); Getting cart content by step ID
apply_filters('wcpw_cart_item_by_key', $output, $postId, $key); Getting cart item by key
apply_filters('wcpw_cart_product_by_id', $output, $postId, $productId, $stepId); Getting a product from cart by ID and optionally by step ID
apply_filters('wcpw_cart_product_meta', $output, $cartItem); Cart product meta data string
apply_filters('wcpw_cart_step_data_by_key', $output, $postId, $key, $stepId); Getting a custom field from cart by key and optionally by step ID
apply_filters('wcpw_add_to_cart_item', $cartItem, $postId, self::$sessionKey); Product data for adding to cart
apply_filters('wcpw_cart_total', $output, $postId); Getting cart total amount
apply_filters('wcpw_cart_total_price', $output, $postId); Getting cart total formatted price
apply_filters('wcpw_cart_item_price', $output, $item, $args); Getting cart item price
apply_filters('wcpw_cart_item_discounted_price', $output, $item, $args); Getting cart item discounted price according the rules
apply_filters('wcpw_cart_item_final_price', $output, $item, $args); Getting cart item final handled price
apply_filters('wcpw_cart_kit_child_value_parts', $value, $cartItem $wizardId, $args); Combined kit child value string parts
apply_filters('wcpw_cart_kit_child_display', $display, $cartItem $wizardId, $args); Combined kit child displayed value string parts
apply_filters('wcpw_kit_child_data', $array); Combined kit child meta data
apply_filters('wcpw_sub_terms', $output, $termId, $taxonomy); Child terms of a term array
apply_filters('wcpw_price_limits', $output, $postId, $stepId); Min/max prices of products for a step
apply_filters('wcpw_send_json_data', $data); Sending JSON response data
apply_filters('wcpw_availability_by_rules', $output, $postId, $rules, $itemId) Availability result by rules
apply_filters('wcpw_result_pdf_instance', $dompdf, $args); DomPDF instance of wizard
apply_filters('wcpw_result_pdf_file_name', $output, $args); DomPDF file name
apply_filters('wcpw_result_pdf_file', $array, $args); DomPDf file data array
apply_filters('wcpw_form_ajax_actions', $ajaxActions); Pairs of JS action and PHP handles for AJAX
apply_filters('wcpw_step_quantities_rule', (int) $output, $postId, $rule); Some of step's products quantity rules
apply_filters('wcpw_submit_form_item_data', $data, $args); Add item to cart data from the main form submit event
apply_filters('wcpw_prevent_final_redirect', false, $postData); Prevents the final redirect
apply_filters('wcpw_steps_ids', $stepsIds, $postId); Prepared form steps IDs array
apply_filters('wcpw_steps', $steps, $postId); Prepared form steps array
apply_filters('wcpw_step', $output, $postId, $stepId); Step data array
apply_filters('wcpw_active_step_id', $output, $postId); Active step ID
apply_filters('wcpw_active_step', $activeStep, $postId); Active step array
apply_filters('wcpw_pagination_args', $paginationArgs, $args); Step pagination arguments
apply_filters('wcpw_pagination_items', $output, $args); Step pagination items array
apply_filters('wcpw_nav_items', $navItemsCache[$postId], $postId); Steps navigation items array
apply_filters('wcpw_filter_fields', $output, $postId, $stepId, $appliedFilters); Step filters array
apply_filters('wcpw_redirect_to_wizard_link', $link, $wizardId, $cartItemKey, $productData); Redirect link to a wizard after add to cart action
apply_filters('wcpw_redirect_to_wizard_product_data', $productData, $wizardId, $cartItemKey); Product data of a wizard after add to cart action (before redirect)
apply_filters('wcpw_variation_arguments', $output, $arguments); Product variations data
apply_filters('wcpw_products_request_args', $output, $productsIds, $filter); Products request args of a step
apply_filters('wcpw_add_all_to_main_cart_items', $cart, $postId); Items on a passing to Woocommerce cart
apply_filters('wcpw_kit_id', date('d-m-Y H:i:s'), $postId, $cart); ID of the kit on a passing to Woocommerce cart
apply_filters('wcpw_kit_title', get_the_title($postId), $postId, $cart); Title of the kit on a passing to Woocommerce cart
apply_filters('wcpw_kit_base_product_data', $productData, $postId, $cart); Data of the admin defined base kit product
apply_filters('wcpw_main_cart_product_data', $productData, $postId, $cartItem); Add products to main cart loop item data
apply_filters('wcpw_merge_cart_quantity', false, $args)); Is necessary to merge the same product quantity in Woocommerce cart
apply_filters('wcpw_step_products_query_args', $queryArgs, $postId, $stepId, $filter); Step products request query array
apply_filters('wcpw_product_availability', $isAvailable, $productId, $postId, $stepId, $args); Product availability in the wizard value
apply_filters('wcpw_step_products_ids', $productsIds, $postId, $stepId, $args); Array of products IDs of a step
apply_filters('wcpw_settings_models', $modelCache); Get all settings models array
apply_filters('wcpw_global_settings_model', $global); Array of the plugin global settings model
apply_filters('wcpw_post_settings_model', $post); Array of a wizard post settings model
apply_filters('wcpw_step_settings_model', $step); Array of a wizard step settings model
apply_filters('wcpw_product_settings_model', $product); Array of a product settings model
apply_filters('wcpw_product_variation_settings_model', $productVariation); Array of a product variation settings model
apply_filters('wcpw_product_category_settings_model', $productCategory); Array of a product category settings model
apply_filters('wcpw_product_attribute_settings_model', $productAttribute); Array of a product attribute settings model
apply_filters('wcpw_global_setting', $value $setting); Get one global setting value
apply_filters('wcpw_post_setting', $value, $id, $setting, $modelSource); Get one wizard's setting value
apply_filters('wcpw_post_settings', $output, $id, $args); Get all wizard's settings values
apply_filters('wcpw_steps_ids_setting', $stepsIdsCache[$id], $id); Wizard's steps IDs array from DB
apply_filters('wcpw_step_settings', $stepsSettingsCache[$id], $id); Get all step setting values
apply_filters('wcpw_step_setting', $value, $id, $stepId, $setting); Get one step setting value
apply_filters('wcpw_step_settings', $output, $id, $args); Get one step settings array
apply_filters('wcpw_product_category_setting', $value, $id, $setting); Get one product category setting value
apply_filters('wcpw_is_sidebar_showed', $show, $id); Is sidebar showed state
apply_filters('wcpw_final_redirect_url', $url, $id); Getting the final redirect URL
apply_filters('wcpw_filter_sources_list', $output); Step filter sources array
apply_filters('wcpw_minimum_products_selected_message', $message, $id, $limit, $value); Minimum products selected error message
apply_filters('wcpw_maximum_products_selected_message', $message, $id, $limit, $value); Maximum products selected error message
apply_filters('wcpw_minimum_products_price_message', $message, $id, $limit, $value); Minimum products price error message
apply_filters('wcpw_maximum_products_price_message', $message, $id, $limit, $value); Maximum products price error message
apply_filters('wcpw_form_template_name', $template, $postId, $stepId); Form step current template name
apply_filters('wcpw_form_templates', $templates); Available form step templates
apply_filters('wcpw_form_item_templates', $templates); Available form item templates
apply_filters('wcpw_variations_type_templates', $templates); Available form item variation templates
apply_filters('wcpw_form_item_template_name', $template, $postId, $stepId); Form item current template name
apply_filters('wcpw_nav_list_templates', $templates); Available steps navigation templates
apply_filters('wcpw_template_htmlpath', $path, $name, $arguments, $settings); Requested template path
apply_filters('wcpw_step_input_short_code_unsupported_types', $unsupportedTypes); List of unsupported step input types using the short-code
apply_filters('wcpw_filter_args_to_query', $output, $data); WP_Query ready filter arguments
apply_filters('wcpw_cart_item_generated_thumbnail_attributes', $attributes, $itemData) Cart product generated thumbnail image attributes filter
apply_filters('wcpw_cart_item_generated_thumbnail', $output, $itemData) Cart product generated thumbnail image filter
apply_filters('wcpw_generated_thumbnail_cart_areas', $cartAreas, $id, $cart) Collected cart areas for thumbnail generation
apply_filters('wcpw_generated_thumbnail_data', $output, $id, $cart) Generated thumbnail URL and path
apply_filters('wcpw_order_item_generated_thumbnail_attributes', $attributes, $itemData) Order item generated thumbnail image attributes in the admin part
apply_filters('wcpw_order_item_generated_thumbnail', $output, $itemData) Order item generated thumbnail image in the admin part
apply_filters('wcpw_result_item_thumbnail', $thumbnail, $cartItem, $cartItemKey) Results table product thumbnail image filter
apply_filters('wcpw_widget_item_thumbnail', $thumbnail, $cartItem, $cartItemKey) Widget product thumbnail image filter
apply_filters('wcpw_widget_generated_thumbnail_attributes', $attributes, $id, $cart) Widget generated thumbnail image attributes

PHP tricks and utils

Link Add custom product filters to a step

If you want to allow the products filtering by custom fields then this is necessary to use two hooks for this. The first one is used to add filter instances for the further work. They are arrays with keys within, namely:

  • label - Filter's name for output on the front part;
  • key - Inner key for using;
  • view - A filter view name supported by a wizard by default or custom one;
  • value - Current value of the only field (like text input) or null;
  • values - Array of possible values of the filter.

The second hook is for handling the passed values to use for WP_Query arguments.

Here is an example of using YITH brands taxonomy as a product filter within the #123 wizard for the 1 and 2 steps:

<?php
// add custom filters to output on the front part
add_filter('wcpw_filter_fields', function ($output, $postId, $stepId, $appliedFilters) {
    // add only for specific wizard ID and steps IDs
    if ($postId == 123 && in_array($stepId, [1, 2])) {
        $label = 'Brands'; // filter name
        $view = 'checkbox'; // required view
        $key = 'yith_product_brand'; // taxonomy to use
        $values = [];

        // collect terms as values
        $terms = get_terms(['taxonomy' => $key]);

        foreach ($terms as $term) {
            $values[] = [
                'id' => $term->term_id,
                'name' => $term->name,
                'isActive' => isset($appliedFilters[$key]) && in_array($term->term_id, $appliedFilters[$key])
            ];
        }

        $output[] = [
            'label' => $label,
            'key' => $key,
            'view' => $view,
            'value' => isset($appliedFilters[$key]) ? $appliedFilters[$key] : null,
            'values' => $values
        ];
    }

    if ($postId == 321 && in_array($stepId, [4, 5])) {
        // other filters here...
    }

    return $output;
}, 10, 4);

// handle passed filters to query args
add_filter('wcpw_filter_args_to_query', function ($output, $filters) {
    foreach ($filters as $filter) {
        foreach ($filter as $key => $value) {
            // add query arg by the custom taxonomy
            if ($key == 'yith_product_brand' && !empty(array_filter($value)) {
                $output['tax_query'][] = [
                    'taxonomy' => $key,
                    'field' => 'id',
                    'terms' => array_filter($value),
                    'operator' => 'IN'
                ];
            }

            // other filters here...
        }
    }

    return $output;
}, 10, 2);
?>

Link Hide products from shop

If you need to make some products available only within a wizard the lower code can help you with it. It adds an extra checkbox on the "Inventory" product tab. If it is ticked then WooCommerce will skip this product from the query, but the wizard ignores this option.

<?php
// add extra field
add_action('woocommerce_product_options_stock_status', function () {
    woocommerce_wp_checkbox(array(
        'id' => '_is_hidden_product',
        'wrapper_class' => 'show_if_simple show_if_variable',
        'label' => 'Hide Product From Shop'
    ));
});

// save post
add_action('woocommerce_admin_process_product_object', function ($product) {
    if (isset($_POST['_is_hidden_product'])) {
        $product->update_meta_data('_is_hidden_product', 'yes');
    } else {
        $product->delete_meta_data('_is_hidden_product');
    }
});

// modify query
add_action('woocommerce_product_query', function ($query) {
    $meta_query = $query->get('meta_query');
    $meta_query[] = array('key' => '_is_hidden_product', 'compare' => 'NOT EXISTS');
    $query->set('meta_query', $meta_query);
});
?>

Link Don't apply coupons to products with a wizard discount

If products from your wizard already have a discount and you don't want coupons can reduce their price more add this extra code to your site.

<?php
// skip wizard's discounted products for coupons
add_filter('woocommerce_coupon_get_discount_amount', function ($discount, $priceToDiscount, $object) {
    if (isset($object['wcpw_id'])
        && (isset($object['wcpw_discount'])
            || isset($object['wcpw_category_discount'])
            || isset($object['wcpw_product_discount']))
    ) {
        return 0;
    }

    return $discount;
}, 10, 3);
?>

Link Apply a dynamic discount according to the selected products number

The next code makes the "Price discount" setting dynamic according to the current selected products numbers in the wizard. Use the $rules variable to define the products number and its discount value as 4 => 10, namely 4 or more products have 10% discount until the next met rule.

<?php
// dynamic discount value by the current cart count
add_filter('wcpw_post_setting', function ($value, $id, $setting) {
    if ($setting != 'price_discount') {
        return $value;
    }

    $cart = \WCProductsWizard\Cart::get($id);
    $cartCount = 0;
    $rules = [
        1 => 0,
        4 => 10,
        10 => 20,
        50 => 25
    ];

    foreach ($cart as $item) {
        if (!isset($item['quantity']) || !$item['quantity']) {
            continue;
        }

        $cartCount += $item['quantity'];
    }

    if ($cartCount) {
        foreach ($rules as $count => $discount) {
            if ($cartCount >= $count) {
                $value = $discount;
            } else {
                break;
            }
        }
    }

    return $value;
}, 10, 3);
?>

Link Apply a dynamic kit price according to the selected products number per step

The next code makes the "Kit price" setting dynamic according to the currently selected product numbers per step. Each step with products has a default price which includes a defined products number. But then there are more products than this defined value each additional product adds an extra amount.

<?php
// dynamic kit price by the selected products number per step
add_filter('wcpw_post_setting', function ($value, $id, $setting) {
    if ($setting != 'kit_price') {
        return $value;
    }

    $cart = \WCProductsWizard\Cart::get($id);
    $stepsQuantities = [];

    foreach ($cart as $product) {
        if (!isset($stepsQuantities[$product['step_id']])) {
            $stepsQuantities[$product['step_id']] = 0;
        }

        $stepsQuantities[$product['step_id']] += $product['quantity'];
    }

    $total = 0;
    $DEFAULT_PRICE_PER_STEP = 10; // default step price
    $PRODUCTS_LIMIT_PER_STEP = 3; // maximum products number included to the default step price
    $EXTRA_PRODUCTS_PRICE_PER_STEP = 2; // additional price per each product upper the limit

    foreach ($stepsQuantities as $quantity) {
        if (!$quantity) {
            continue;
        }

        $total += $DEFAULT_PRICE_PER_STEP;

        if ($quantity > $PRODUCTS_LIMIT_PER_STEP) {
            $extraProductsQty = $quantity - $PRODUCTS_LIMIT_PER_STEP;
            $total += $extraProductsQty * $EXTRA_PRODUCTS_PRICE_PER_STEP;
        }
    }

    return $total;
}, 10, 3);
?>

JS Snippets

JS actions

Action Description
jQuery(document).on('launched.wcpw', (e, instance) => {}); On wizard init
jQuery(document).on('ajaxRequest.wcpw', (e, instance, formData) => {}); Before wizard AJAX query
jQuery(document).on('ajaxSuccess.wcpw', (e, instance, response, formData, options) => {}); On wizard AJAX query success
jQuery(document).on('ajaxCompleted.wcpw', (e, instance, response, formData, options) => {}); On wizard AJAX query success and all process are done
jQuery(document).on('ajaxError.wcpw', (e, instance, response, formData, options) => {}); On wizard AJAX query error
jQuery(document).on('addToMainCart.wcpw', (e, instance, data, result) => {}); On add to main cart
jQuery(document).on('addToMainCartError.wcpw', (e, instance, data, response) => {}); Add to main cart error
jQuery(document).on('addToMainCartRedirect.wcpw', (e, instance, data, response) => {}); On doing the final redirect
jQuery(document).on('submit.wcpw', (e, instance, data) => {}); On form submit
jQuery(document).on('submitError.wcpw', (e, instance, data) => {}); Form submit error

JS tricks and utils

Here is the list of some Javascript codes to change the wizard's behavior. There are many ways to add them to your site. You can use some plugins to add extra scripts, for example Simple Custom CSS and JS.

Also, some themes provides text fields for custom codes for using. Or you can add extra scripts right in theme's javascript files, but it's better to do only for the child themes because you can loose the changes you made while theme update.

// submit wizard on any product variation property change
jQuery(document).on('change', '[data-component~="wcpw-product-variations-item-input"]', function () {
    jQuery(this).closest('[data-component~="wcpw"]').data('wcpw').submit();
});

// add product to cart on any variation property change
jQuery(document).on('change', '[data-component~="wcpw-product-variations-item-input"]', function () {
    var $product = jQuery(this).closest('[data-component="wcpw-product"]');
    var $wcpw = $product.closest('[data-component~="wcpw"]');

    $wcpw.data('wcpw').addCartProduct({productToAddKey: $product.data('step-id') + '-' + $product.data('id')});
});

// add/remove product in cart once it is chosen
jQuery(document).on('change', '[data-component~="wcpw-product-choose"]', function () {
    var $input = jQuery(this);
    var $wcpw = $input.closest('[data-component~="wcpw"]');

    if ($input.attr('type') === 'checkbox') {
        if ($input.prop('checked')) {
            $wcpw.data('wcpw').addCartProduct({productToAddKey: $input.data('step-id') + '-' + $input.val()});
        } else {
            $wcpw.data('wcpw').removeCartProduct({
                productCartKey: $input.closest('[data-component~="wcpw-product"]').data('cart-key')
            });
        }
    } else {
        $wcpw.data('wcpw').addCartProduct({productToAddKey: $input.data('step-id') + '-' + $input.val()});
    }
});

// add product to cart and go next once click on it
jQuery(document).on('click', '[data-component="wcpw-product"]', function () {
    var $product = jQuery(this);
    var $wcpw = $product.closest('[data-component~="wcpw"]');

    $wcpw.data('wcpw').addCartProduct(
        {productToAddKey: $product.data('step-id') + '-' + $product.data('id')},
        {behavior: 'submit'}
    );
});

// submit filter on change immediately
jQuery(document).on('change', '[data-component~="wcpw-filter"]', function () {jQuery(this).submit()});

// don't open the image page on thumbnail click
jQuery(document).on('click', '[data-component="wcpw-product-thumbnail-link"]', function (event) {event.preventDefault()});