Product Finder
v1.1.33

Getting Started

Welcome to the Product Finder user manual.

You can find all the information you need to add product finders to your online store here.

Go ahead, dive in!

  • Please go to the My Downloadable Products section of our store and find your Product Attachment module.
  • Learn how to install the extension here, and follow our Quick Start guidelines in order to set up your own product finders in no time.
  • If you are interested in the module's more advanced features, check out the manual's Configuration section.

How to install the extension

How to install the extension using composer

  1. Backup your store's database and web directory.
  2. Login to the SSH console on your server and navigate to the root directory of the Magento 2 store.
  3. Copy the installation instructions from the page My Downloadable Products to the SSH console and press ENTER.
  4. Run command to enable the extension: 
    php -f bin/magento module:enable Mirasvit_Core Mirasvit_Finder
  5. Run command to install the extension: 
    php -f bin/magento setup:upgrade
  6. Run command to clean the cache: 
    php -f bin/magento cache:clean
  7. Deploy static view files: 
    rm -rf pub/static/*;
rm -rf var/view_preprocessed/*;
php -f bin/magento setup:static-content:deploy;

How to install the extension manually

  1. Backup your store's database and web directory.
  2. Download archive from My Downloadable Products.
  3. Unzip the extension locally.
  4. Copy unzipped folder to the root directory of the Magento store.
  5. Run command to enable the extension: 
    php -f bin/magento module:enable Mirasvit_Core Mirasvit_Finder
  6. Run command to install the extension: 
    php -f bin/magento setup:upgrade
  7. Run command to clean the cache: 
    php -f bin/magento cache:clean
  8. Deploy static view files: 
    rm -rf pub/static/*;
rm -rf var/view_preprocessed/*;
php -f bin/magento setup:static-content:deploy;

Quick Start

Follow this guide in order to set up your own product finder in no time.

  1. Create a new finder:

    1. Go to your Magento admin panel
    2. Сlick the Catalog tab in the top left of your admin panel.
    3. Click Product Finder in the pop-up.
    4. Click Add New Finder to the top right of the finder grid.
    5. Specify its internal name in the first input field.
    6. Click Save in the top right.

  2. Change its general settings.

    If you would like to place the finder on a page without any products, make sure to redirect the filtered results to a page with a product list in the Destination URL field.

  3. Edit its appearance.

    The finder block's visual options are determined by a PHTML template. The module includes plain horizontal and vertical templates. If you would like to create a template that better fits your design language or business goals, you can either edit the existing templates or create a new PHTML file and upload it to the server.

  4. Configure the product filters.

    The filters are prioritized from top to bottom (in the backend and in the vertical template) and from left to right (in the horizontal template).

    There are two ways to synchronize the module's filters with your product information: importing the list of relevant products and custom attributes with a CSV file or connecting the filters to global product attributes. You can use both filtering options in a single finder.

  5. Place the finder on the relevant page.

    You can use widgets, layout update XML snippets or template .phtml in order to do that.

Useful Info

You can add several finders to a single page.

  1. Reindex the finder with php -f bin/magento mirasvit:finder:reindex and clean Magento cache.

General Settings

You can turn the finder on and off, specify its internal name, and change its destination URL in this section.

Destination URL

This option allows you to specify a custom results page for the finder. This field is optional. You only have to add the destination URL if you place the finder on a page without the relevant products, e.g. your homepage.

Note

The results page has to contain the relevant product list and a secondary finder block in order to work properly.

Useful Info

If you do not add a destination URL, the finder will be redirected to the default results page: /finder/index

Available Options

Option Description
Enable Finder Turns the finder on and off.
Name The finder's internal name. It is not visible to customers.
Destination URL Specifies the full or relative path to the finder's custom results page.

Example

The relative path starts with a slash. If the full URL is https://www.mystore.com/tyres.html, you only need to add /tyres.html.

Note

Destination URL only changes the finder's results page. It does not determine the finder block's location. To place the finder on a specific page, you have to add its code snippet from the Display section there.

Appearance

You can change the finder's visual design in this section. Most of the finder's visual details, such as the background and the filter layout, are determined by a PHTML template so you can have maximum creative control.

Editing the Templates

The module includes plain horizontal and vertical templates. They are situated in either of the two locations, depending on the installation type:

Composer: vendor/mirasvit/module-finder/src/Finder/view/frontend/templates/finder/

Manual: app/code/Mirasvit/Finder/view/frontend/templates/finder/

You can copy and paste them to the theme folder and edit them there:

design/frontend/*/*/Mirasvit_Finder/templates/finder/

If you would like to create a template from scratch, you can create a new PHTML file and upload it to the server. You have to place it in the theme folder:

design/frontend/*/*/Mirasvit_Finder/templates/finder/

Changing the Finder's Design

  1. Create a new finder. If you have already created one, click Select, then Edit in the grid's rightmost field.
  2. Choose a visual template in the Appearance's section Template field.
  3. Click Save in the top right.

Note

You cannot edit the Display section in the finder's settings by design. The code is there so you can copy it and place it on any page.

Available Options

Option Description
Template Selects a visual design template.
Block Title Sets the finder's public title.
Block Description Sets the finder's public description.

Note

You have to create a new PHTML file if you would like to use a different design template. Upload it to design/frontend/*/*/Mirasvit_Finder/templates/finder/.

Filters

You can set up product filters in this section.

Note

Clicking Add Filter several times will create a separate filter for each click. There is no limit to the number of filters you can add.

The filters are prioritized from top to bottom (in the backend and the vertical template) and from left to right (in the horizontal template). Any subsequent filter will only show the values available for products with the previous filter's value.

Example

Let us look at the tyre finder in the demo. There is a large selection of tyres with widths ranging from 115 to 750 and profiles ranging from 25 to 95. However, if you select a specific tyre width, e.g. 165, you will only be able to select tyre profiles of tyres with that particular width, e.g. 60, 65, 70 and 80. The same principle applies to any subsequent filter.

Filters are mandatory by default. Visitors will have to select a value before moving on to the next filter. You can make some of them optional, letting the visitors skip the selection. However, they will not be able to select the filter to the right (or the lower one) before the filter on the left (or the higher one) even if both of them are optional. Selecting the latter will clear any selection in the former.

There are two ways to synchronize the module's filters with your product information:

Note

You can use both filtering options in a single finder. Their priority will not change.

Adding Filters by Imported Values

You can import the list of relevant products and custom attributes with a CSV file and set up the filters according to the values in the CSV:

  1. Create a new finder. If you have already created one, click Select, then Edit in the grid's rightmost field.
  2. Add the filters you need by clicking Add Filters in the Filter section.
  3. Set them to Import in the Link To field.
  4. (Optional) Choose between dropdown and label filter display mode in the Display Mode field.
  5. (Optional) Change between ascending and descending sort orders in the Sort Mode field.
  6. (Optional) Make the filter optional by unchecking the box in the Required field.
  7. (Optional) Let customers select multiple values at once by checking the box in the Multiselect field.
  8. Click Save in the top right in order to update the filter list.
  9. Prepare a CSV with the relevant products.

Note

If you are unsure about the formatting, click Import Products in the Import section of the finder's settings page, then click Download Sample File. You can use the downloaded CSV as an example.
  1. Upload your CSV to the Import section.
  2. Click Save in the top right.
  3. Reindex the module with php -f bin/magento mirasvit:finder:reindex.

Adding Filters by Attributes

Alternatively, you can connect the filters to any global product attribute:

  1. Create a new finder. If you have already created one, click Select, then Edit in the grid's rightmost field.
  2. Add the filters you need to the Filter section.
  3. Set them to Attribute in the Link To field.
  4. Select the relevant attribute.

Note

The products you would like to filter must have this attribute.
  1. (Optional) Choose between dropdown and label filter display mode in the Display Mode field.
  2. (Optional) Change between ascending and descending sort order in the Sort Mode field.
  3. (Optional) Make the filter optional by unchecking the box in the Required field.
  4. (Optional) Let customers select multiple values at once by checking the box in the Multiselect field.
  5. Click Save in the top right.
  6. (Optional) Scroll down to the Import section and review the products that have the relevant attributes.
  7. Reindex the module with php -f bin/magento mirasvit:finder:reindex.

Available Options

Option Description
Filter Name Specifies the public filter name.

Note

If you are linking the filter to an imported CSV, its name is also used as a column name.
Option Description
Link To Determines whether the filter takes the information from an imported CSV or a product attribute.
Attribute Chooses which attribute the filter uses. You can select any of the global attributes. This field is displayed only if you link the filter to a product attribute.

Note

The relevant products have to be connected to the attribute.
Option Description
Display Mode Determines how a filter list will appear live. Select dropdown mode for longer filters and label mode for shorter ones.
Sort Mode Changes between ascending and descending sort orders.
Required Makes a filter mandatory.
Multiselect Lets a customer select several values at once.

Note

You have to reindex the module with php -f bin/magento mirasvit:finder:reindex in order to make the filter updates go live.

Import Products

You can import a list of relevant products and variables in this section by clicking Import Products and following the instructions in the pop-up. The order and number of columns in the CSV file is determined by the filters, top to bottom. You can also download a sample CSV file and use it as a template.

Note

Make sure you have added all the necessary filters and saved the finder before downloading a sample file or uploading your own CSV, or else the files will contain incorrect data.

Importing the Products You Need Filtered

  1. Add the relevant filters connected to imported values.
  2. Click Save in the top right.
  3. Prepare a CSV with the relevant products.

Note

  • You do not need to add any column headers. The first row will be used for the first product.
  • The first column has to contain the SKU, the others must contain the values for each filter.
  • The column order in the file has to match the grid's filter order in the Import section.

Example

Let's say you are setting up a tyre finder similar to the one in our demo. Your CSV file has to follow this principle:

A B C D E F
1 2255016ZBUFAZ310 225 50 R16 96 W
2 2255016ZGEALTSPT 225 50 R16 92 Y
3 2255016ZBUSUBC10 225 50 R16 96 W
4 2255016VYOV105MO 225 50 R16 92 V
5 2255016ZFISZ90W 225 50 R16 92 W

Useful Info

If you are unsure about how to format your products, click Import Products in the Import section of the finder's settings page, then click Download Sample File. You can use the downloaded CSV as an example.
  1. Upload your CSV in the Import section by clicking Import Products, Upload, selecting the file and clicking Start Import.
  2. Click Save in the top right.

Available Options

Option Description
Download Sample File Downloads a sample CSV file. You can use it as a formatting example for your own product list.
Upload Uploads a new CSV file.
Mode Changes between import modes

Note

Overwrite existing data completely replaces the existing information with data from the new file. Update existing data adds new data but keeps the existing information intact.

Display

This section stores the finder block's Widget, Layout Update XML and Template .phtml code snippets. You have to copy one of them and place it on any page in order for the finder to be displayed there.

Any of the three options can work, but they are intended for different editing purposes. They also vary in complexity and flexibility:

  • Widgets are generally the easiest to use: you can copy and paste the snippet directly to the editor.
  • Layout updates offer more control but they require a knowledge of XML and a direct access to the server.
  • Templates are the most flexible but they require the knowledge of HTML and PHP.

Useful Info

If you are unsure of which snippet to use, please review Magento documentation on widgets, layout updates, and templates or consult with your developer.

Note

You cannot edit the snippets. The block's visual design is determined by default PHTML templates in the module's installation folder and custom templates in the theme folder design/frontend/*/*/Mirasvit_Finder/templates/finder/.

Adding the Finder to the Page

Adding the snippet to the relevant page is sufficient for the finder to work properly if the page has a list of the products you need filtered. If you would like to place the finder on a different page, e.g. your homepage, you have to place a secondary finder on the page with the products, then add the secondary page's URL to the Destination URL field of the finder's general settings section.

If you would like to place the finder on a page that contains the relevant product list:

  1. Copy the code from the field of your choice in the Display section.
  2. Place it on the relevant page by pasting the widget to the editor, updating the layout or adding the template.
  3. Clean Magento cache.

If you would like to place it on a page without a product list:

  1. Copy the code from the field of your choice in the Display section.
  2. Place it on the relevant page by pasting the widget to the editor, updating the layout or adding the template.
  3. Specify the full or the relative page URL in the Destination URL field of the finder's general settings section.

Example

The relative page URL has to start with a slash after the domain extension. If the full URL is https://www.mystore.com/tyres.html, you only need to add /tyres.html.
  1. Copy the code from the field of your choice in the Display section.
  2. Place it on the the page where you would like to place the primary finder, e.g. the homepage, by pasting the widget to the editor, updating the layout or adding the template.
  3. Clean Magento cache.

Useful Info

You can add several finders to a single page.

Available Options

Snippet Description
Layout Update XML Copy this snippet if you would like to work with a layout update.
Widget Copy this snippet if you would like to work with a widget.
Template .phtml Copy this snippet if you would like to work with a PHTML file.

How to upgrade extension

To upgrade the extension, follow these steps:

  1. Backup your store's database and web directory.
  2. Login to the SSH console of your server and navigate to the root directory of the Magento 2 store.
  3. Run command to update current extension with all dependencies: 
    composer require mirasvit/module-finder:* --update-with-dependencies

    Note

    In some cases, the command above is not applicable, or it's not possible to update just the current module, or you need to upgrade all Mirasvit modules in a bundle. In this case, the command above will have no effect.

    Run instead composer update mirasvit/* command. It will update all Mirasvit modules installed in your store.

  4. Run command to install updates: 
    php -f bin/magento setup:upgrade
  5. Run command to clean the cache: 
    php -f bin/magento cache:clean
  6. Deploy static view files: 
    rm -rf pub/static/*;
rm -rf var/view_preprocessed/*;
php -f bin/magento setup:static-content:deploy;

Disabling the Extension

Temporarily Disable

To temporarily disable the extension please follow these steps:

  1. Login to the SSH console on your server and navigate to the root directory of the Magento 2 store.
  2. Run command to disable the extension: 
    php -f bin/magento module:disable Mirasvit_Finder
  3. Log in to the Magento backend and refresh the store cache (if enabled).

Extension Removal

To uninstall the extension, please follow these steps:

  1. Login to the SSH console on your server and navigate to the root directory of the Magento 2 store.
  2. Run command to disable the extension: 
    php -f bin/magento module:disable Mirasvit_Finder
  3. Run command to remove the extension: 
    composer remove mirasvit/module-finder
  4. Log in to the Magento backend and refresh the store cache (if enabled).

Change Log

1.1.33

(2024-10-21)

Fixed

  • Issue related to translation of filter labels
  • Added svg loader instead of font-awesome

1.1.32

(2024-08-08)

Fixed

  • Show no filter options if a category has no matching products

1.1.31

(2024-07-15)

Fixed

  • Issue related to filter options taken from the localstorage
  • Increasing the length of name field in mst_finder_filter_option table

1.1.30

(2024-06-06)

Fixed

  • Added caching to filter options requests

1.1.29

(2024-06-06)

Fixed

  • Disable filter options during ajax requests

1.1.28

(2024-06-03)

Fixed

  • Adding a loader during ajax request

1.1.27

(2024-06-03)

Fixed

  • Reduced the number of Ajax requests when selecting an option

1.1.26

(2024-03-06)

Fixed

  • Issue with imported products after reindex

1.1.25

(2023-11-08)

Fixed

  • Compatibility with m2.4.6
  • Issue when filter does not apply

1.1.23

(2023-10-11)

Improvements

  • Compatibility with m2.4.6

1.1.22

(2023-10-05)

Fixed

  • Filter options sorting

1.1.21

(2023-10-04)

Fixed

  • Filter does not apply in m2.3 and Elastic 6
  • Filters do not load from cache correctly

1.1.20

(2023-10-03)

Fixed

  • Sort Mode does not work

1.1.19

(2023-08-28)

Fixed

  • If array has missed key or keys are not sorted, json creates object instead of array
  • Impossible to process constructor argument Parameter #0 CombineFactory $combineFactory

1.1.18

(2023-06-12)

Fixed

  • Compatibility with OpenSearch Search Engine
  • Error "JSON Parse error: Unexpected identifier "object""

1.1.17

(2023-05-30)

Fixed

  • Error "Trying to access array offset on value of type bool in Mirasvit/Finder/Service/ImportOptionService.php on line 182"
  • Error "Undefined array key 2 in Finder/Ui/Import/Listing/DataProvider.php on line 192"

1.1.16

(2023-05-19)

Fixed

  • Reset button does not work

1.1.15

(2023-05-12)

Fixed

  • Error "You cannot define a correlation name 'tbl_category_ids' more than once"

1.1.14

(2023-03-15)

Fixed

  • PHP 8.2

1.1.13

(2023-02-21)

Fixed

  • Finder URL key for multi stores

1.1.11

(2023-02-17)

Fixed

  • Error "Mirasvit\Finder\Service\FilterOptionService::getName() must be of the type string, null returned"
  • Code in the finder setting "Template .phtml"

1.1.10

(2023-02-07)

Fixed

  • Attribute translation

1.1.8

(2023-02-02)

Fixed

  • Label multi select filters
  • Filtering with Elastic

1.1.7

(2023-01-20)

Fixed

  • Filters saving
  • Warning: Undefined array key "finder_id"
  • Uniqueness of the filter URL key

1.1.6

(2022-11-02)

Fixed

  • JS loading queue

1.1.5

(2022-10-18)

Fixed

  • Filters do not apply to catalog when "Friendly URLs" enabled

1.1.3

(2022-10-07)

Fixed

  • Issue when filters with the same name do not work

1.1.2

(2022-08-12)

Fixed

  • Import validation

1.1.1

(2022-06-20)

Improvements

  • remove db_schema_whitelist.json

1.1.0

(2022-05-23)

Improvements

  • Migrate to declarative schema

1.0.24

(2022-04-27)

Improvements

  • Added conditions to the finder

1.0.23

(2022-04-22)

Fixed

  • Fixed the issue with finder filter not applied when filter's URL key differs from attribute code (friendly URLs)

1.0.22

(2022-04-22)

Fixed

  • Fixed the issue with finder returns not filtered products with friendly URLs enabled (since 1.0.20)
  • Fixed the issue with finder returns not filtered collection (Magento 2.3.*)

1.0.21

(2022-04-20)

Fixed

  • Compatibility with Mageplaza_LayeredNavigation
  • Reset button
  • Multi finders on the same page

1.0.20

(2022-04-01)

Improvements

  • Added finder reindex to the cron

Fixed

  • Execution timeout during file import
  • Compatibility with Mageplaza_LayeredNavigation
  • Filters for preselected options
  • Increase filters speed

1.0.19

(2022-04-01)

Fixed

  • Multiselect for the display mode "Label"
  • Reset URL does not work when friendly URLs enabled
  • Compatibility with Mageplaza_LayeredNavigation v2.4.3

1.0.18

(2021-09-09)

Fixed

  • Filter with hyphen does not work
  • Import identical SKUs for different filters

1.0.17

(2021-08-09)

Fixed

  • Friendly URLs

Improvements

  • Filter sorting option

1.0.15

(2021-07-05)

Fixed

  • Default value for "dropdown" filter

1.0.13

(2021-05-26)

Improvements

  • Store customer selection in the session
  • Multiselect dropdown

1.0.12

(2021-05-17)

Fixed

  • Filter options on the result page

Improvements

  • Added sort option "non-sorted" to the filter "Sort Mode"

1.0.11

(2021-05-13)

Fixed

  • Filter option "Multiselect" does not work

1.0.10

(2021-05-06)

Fixed

  • fixed: Compatibility with m2.3 (Render filters)

1.0.9

(2021-04-21)

Fixed

  • fixed: Compatibility with m2.3 (Count calculated wrong for layer navigation filters)

1.0.8

(2021-04-19)

Fixed

  • Fix delete message for m2.4

1.0.7

(2021-04-12)

Fixed

  • Compatibility with magento 2.2, 2.3

Improvements

  • Added index by attribute
  • Added filter button
  • Category suffix parse

1.0.6

(2021-01-06)

Fixed

  • Issue when imported options show wrong results (one to many relation)

1.0.5

(2020-11-26)

Improvements

  • Demo
  • Documentation

1.0.4

(2020-11-19)

Features

  • Compatibility with m2.3

1.0.3

(2020-11-11)

Features

  • Friendly urls

1.0.2

(2020-11-09)

Fixed

  • Display of required fields

1.0.1

(2020-11-06)

Fixed

  • Filters by attributes

1.0.0

(2020-10-19)

Features

  • Initial release