Documentation for v.7.9.0

Last updated: May 07th, 2021

About the plugin

Powerful and flexible plugin for creating filters for your WooCommerce products.

It could help your customers to choose products consistently by answering questions and giving a description of each step.

You can create a quiz to filter products and show only appropriate results to your customers.

This is possible to show filtering results right within the filter or lead the customer to a shopping page.

The filter can be placed on any page. Just place the shortcode wherever you want.

And of course, it can be used as a usual product filter in a shopping page sidebar.

Plugin thumbnail

Get the plugin Try the live version

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. Step Filter requires WooCommerce plugin on the site for work.

Question Settings

The first thing you need to do after the installation of the plugin is to create a question for the filter. Go to the WooCommerce - SF Questions page and click the Add New button.

Use the post content as a description of the question. The label setting will be used as the step's name. Alternatively, the title of the post will be used instead. This part is the same for any filter type and view.

First of all select one of view types. Possible types are:

  • Select - simple HTML element;
  • Radio - simple HTML element;
  • Checkbox - simple HTML element;
  • Chips radio - inline radio view for many variants;
  • Chips checkbox - inline checkbox view for many variants;
  • Button radio - vertical radio view for a few variants;
  • Button checkbox - vertical checkbox view for a few variants;
  • Image radio - simple HTML element with an image within;
  • Image checkbox - simple HTML element with an image within;
  • Multi-choice checkbox - complex element to define OR/AND/NOT relation for each option;
  • Multi-choice range - complex element to define OR/AND/NOT relation for each option;
  • Number - precise numeric input with one handler;
  • Number from - range input with one handler;
  • Number to - range input with one handler;
  • Number between - range input with two handlers;
  • Formula - calculate a value by a formula.

After you can select a filter type setting. You can see not all of the variants are allowed. This depends on the selected view type. Possible types are:

  • Attribute - filter by a product attribute taxonomy;
  • Price - just a price filter;
  • Tag - filter by product tags;
  • Category - filter by product categories;
  • Manual - manual selecting of products or categories;
  • Meta - filter by meta key.

Numeric View Type

Numeric view types have their own settings bundle. This is possible to set From and To values caption, the Unit text and change the step of the value. If you have decimal values as answers set this setting to the lowest possible fraction.

Also, this is possible to Enable/disable the slider for these types of views.

Numeric question settings

Checkbox/Radio/Select View Types

Select view type can have an Empty value to oblige the user to make a choice.

Question empty value settings

Types with the only answer ( radio / select) have the Doesn't matter settings group. It allows to output an answer which doesn't modify the query anyhow. Anyway, this type of views always requires a selected value.

Question 'Doesn't matter' settings

Checkbox-based view types have a Relation setting to define "OR" or "AND" relation between the selected answers. This also possible to define Minimum and Maximum values selected.

Checkbox question settings

For radio / checkbox / select view types you can use the Unmet values behavior setting. It allows to handle question values which leads to zero-products result. Possible values are:

  • Show values as usual;
  • Show values as disabled;
  • Hide values at all.

Question unmet values setting

Terms-based View Types

Radio / checkbox / select view types with attribute / tag / category filter types there is a possibility to Include/exclude specific terms define them by IDs separated by a comma. Also, this is possible to Hide empty terms for them.

Not-numeric views with attribute / tag / category filter types have a possibility to Show count of products near the value name.

Question terms setting

Multi-choice View Type

Multi-choice view types have their own settings bundle. This is possible to choose which of 4 possible values will be used for the question, set their order and change captions.

Multi-choice question settings

Image View Type

Image view types have thumbnails alignment and thumbnail size settings. Thumbnail size setting supports inline size names registered on the site.

Image question settings

Formula View Type

Formula view type provides filtering by a calculated value according to the formula string. That's a complex feature to filter products by numeric attribute / price / numeric meta.

This question type outputs no fields itself. You need to set the required input fields in the question description editor. To output a field use the [wcsf-value-input name="%SOME NAME HERE%" value="%SOME VALUE HERE%"] shortcode.

The name attribute is required for saving the data. Checkbox/radio types require a value attribute also. All other required input attributes might be passed the same inline way.

Here are a couple of using examples:

  • <label>[wcsf-value-input type="number" name="My Numeric Field" value="1" min="1" max="24" class="form-control"]
    Numeric value </label>
  • <label>[wcsf-value-input type="checkbox" name="My Checkbox Field" value="Yes" class="form-check-input"]
    Checkbox Field </label>
  • <label>[wcsf-value-input type="radio" name="My Radio Field" value="Yes" class="form-check-input" checked="checked"]
    Yes </label> <label>[wcsf-value-input type="radio" name="My Radio Field" value="No" class="form-check-input"]
    No </label>

Not all input types are supported

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

First of all, define default Formula variables and their values. There might be just static variables like x = 10. This is necessary because formula code works better with string variables than with pure number values.

Also, with the Formula variables setting you can define variables that might be not passed from the shortcode, namely the checkbox fields.

Much probably, you will have multi-word field names but the formula doesn't support them also. This way you need to define Formula name aliases as "My Custom Field => my_custom_field" and use the alias in the formula field.

Moreover, you might have string field values that should be transformed into a numeric value. That might be helpful for radio/checkbox types. For that you need to define Formula value aliases as My Custom Field => Value One => 123

Before the execution of the formula, all of these settings will be used to find the appropriate variable value.

If there is a mistake in the formula you will see an exception on the results page.

The final thing necessary to configure is the Formula operator setting, which allows to compare the selected question source with the calculation result. This is possible to filter products which are:

  • Equal to the calculated value;
  • Not equal to the calculated value;
  • Less than the calculated value;
  • Less or equal to the calculated value;
  • More than the calculated value;
  • More or equal to the calculated value.

Also, this is possible to use the next built-in functions within the formula:

  • sum - Calculate the sum of values;
  • abs - Absolute value;
  • min - Find the lowest value;
  • max - Find the greatest value;
  • round - Rounds a float.

Formula question settings

Action On Click

Not-numeric views have the Action on click setting. It allows making action on selecting the value. This is possible to do:

  • None - to do nothing;
  • Submit - submit value and stay on the step;
  • Submit and go next - submit value and go to the next step;
  • Submit and go to results - submit value and go to the last step.

Question action on click setting

Additional GET Parameters

For not multi-choice view types you can add an Additional GET parameter. That's might be helpful if there is another filtering plugin on your site and you want to pass queried values from the Step Filter to it on the result page. For example, you can add a "category_id" additional parameter for the category filter type to have it as &category_id={requested_value} in the URL of the result page.

As the Number between view type has two result values you can define two keys separated by the "|" symbol.

For attribute / tag / category filter types also possible to change an Additional GET parameter term source to define what term property will be used as a value of the GET parameter. Currently, possible values are ID/Slug/Name.

Question additional GET parameters settings

Dependency Rules

There is a possibility to make any question invisible in the filter until of firing of some dependency. Use the Dependencies settings table for this. Select another question in the dropdown, then select its value in the next field and the comparison operator. Then this question will be visible only then this dependency will be met.

If you need to make more complex dependency then add more dependency rows in the table and define relations between them.

Question dependencies settings

Question Binding

If you have a couple of different filters with different questions (for example, one in a page body and the second in a sidebar) you can pass the value from one question to another using the Bind with question setting. To make this binding both directions set this setting for both bonded questions.

Question binding setting

Ignore Filtering

You can create any type question and use it in a filter but ignore it while filtering the results. The question might affects the dependencies and statistics but not the results.

Question ignore setting

Attribute Filter

This is necessary to choose one product attribute as a source of the values.

Filtering with the Numeric view will work correctly only with the numeric values of the attribute. Attribute value names will be used as float values.

All other settings depend on the selected view type.

Price Filter

Price filtering can have only a numeric view and have no extra-settings except the numeric's.

Min and max prices of the products will be used as a range.

Category Filter

With category type the question will have product categories as values.

You can define Category parent setting to get sub-categories by this category only.

If you need to output only specific sub-categories levels or limit max categories tree depth use Start from categories level and Max sub-categories level. But keep in mind the max sub-categories level setting can't be less than start from categories level setting

Category question setting

All other settings depend on the selected view type.

Manual Filter

Manual filter type allows to create and configure each possible value you need in the question.

Click on the Add a value button to add a row with settings.

Each value could have the settings:

  • Image - for image checkbox/radio view types;
  • Pre-checked - setting to make the value checked by default;
  • Name - a label of the value;
  • Dependencies - define the rules of showing of the value;
  • Source - set the value's source.

Question manual values

In the value source modal you can select one of the values:

  • Any product - not filtering at all;
  • Product - choose products in the result of the value.
  • Category - filter products by one or a few categories;
  • Tags - filter products by one or a few tags;
  • Attributes - filter products by flexible attribute rules;

Question manual product select

Meta Filter

The Meta key setting is required for this type of filtering. Place a string to it and the question will collect all of the possible values of this meta key of products and then use them as the question's values.

For the numeric views the min and the max meta values will be used for the limits, but they should have numeric type.

Filter Settings

Basic Settings

First of all select a source of the steps. That might be just questions posts or question categories. For the second case, each step will output a few questions attached to a category at once.

Select created questions for using and change their order.

There are a few modes allowed:

  • Free walk - allows to walk through the questions as user wants;
  • Step by step - allows only to go consistently though questions;
  • Single-step - show all questions one after one;
  • Sequence - show questions one after one consistently.

This is possible to add extra query arguments which will be used while filtering the results. You can include/exclude specific products, categories, or product attributes in the filtering results.

After tuning all settings, copy the shortcode into any page content to output the filter.

Filter basic settings

Results Settings

Results URL should have a URL to a shop or category page or just "#" symbol to stay on the same page (for using as a widget).

Empty results URL setting will lead the user to a specific page if there are no filtering results by his request.

This is possible to Show results within the filter on the last step without a redirect to another page. This tab could have any title.

If you tick the Show preliminary results count setting there will be a tooltip shown on each question value change.

Also, you can limit the Maximum products number results.

This is possible to make an Instant redirect to the only result page for the paged results showing.

Filter results

Behavior Settings

If you want to see the statistics of filter queries tick the Collect inquiries for statistic for this. You will see this statistic on a special plugin's page. This statistic doesn't collect any personal information.

This is possible to Scroll to top on the form update to let the user see the starting of the next question on submit. Also, there is the gap setting to not scroll the page too high.

Navigation items might have one of the Nav action on click - just go to the next step or submit and go next.

Filter behavior

View Settings

Select one of Nav view values to change the navigation view.

Use the post content as a description of the first step. If you need this, check the Enable description tab setting. To change the step title, change the description tab title setting.

You can enable/disable the value list showing within the filter or on the shop page.

Filter view

Result PDF Settings

PDF customization

To modify the PDF template make a copy of views/products/pdf.php to your active theme (or child theme) directory to woocommerce-step-filter/products/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. This is possible to use special shortcodes to output the current page number and total pages number.

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

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 loop.

Result PDF settings

Controls Settings

Controls settings allows to choose which buttons are used in the filter 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 4 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;

Filter controls

Statistic Collection

To collect a filter's requests statistic don't forget to tick the appropriate setting of the filter behavior settings group.

After go to the WooCommerce - SF Inquiries page and select the required filter in the upper dropdown. You will see all filter questions with their values. Each value will have the label, percentage of all requests, and number of requests. The bar height of the value indicates the percentage of all requests.

Statistic chart

Lower the chart you can find each inquiry with its date, results number, and requested values. You even can see what products there found according to the user's request. Click the results number link to see the admin page with the appropriate products.

All inquiries can be terminated using the special lower button.

Statistic list

Plugin Settings

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" framework, then the filter will be styled the same as your active theme. Or if you need some basic styles applied to the filter'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.

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 filter can't go next thought the steps or loses the answers on the page update. In this case tick "Store session in the DB" setting which works much reliable but probably a little bit slower.

General settings page

Templates Customization

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

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