Market PRO Filter – Complete Guide

Introduction

Market PRO Filter v.3.3.36  is a professional plugin for Cotonti CMF that extends the standard Market module with a flexible system for filtering products by arbitrary parameters. The plugin allows you to create an unlimited number of characteristics (power, battery capacity, brand, design features, and many others), assign them a convenient type (range, dropdown, checkboxes, radio buttons), and link them to a specific product category. Visitors to the site are presented with an intuitive filter form with "live" counters that instantly recalculate after each selection, and the assigned parameters with translations are displayed on the product page. The plugin fully supports multilingualism (Russian, Ukrainian, English), ensures high performance through thoughtful indexing and file caching, and separates regular and super‑admin parameters for flexible access rights configuration.

This guide is divided into three logical parts. The first part covers the theoretical foundations: what faceted filtering is, how data is stored in the database and processed by SQL queries, why indexes are needed, and how multilingualism is built. The second part is devoted to practical use on the frontend – how the filter form works, how dependent counters behave, and how parameters are presented on the product page. The third part is a detailed instruction for the site administrator: creating, editing and deleting parameters, filling in JSON values, setting up translations, and managing caching.

Section 1. Theory: Structure and Operating Principle

1.1 Faceted Search

Ordinary sequential filtering, where each subsequent chosen parameter simply adds a condition to the query, does not give the user an understanding of which values of other parameters will remain available after the current selection. Faceted filtering solves this problem by pre‑calculating the number of products that will be found if any other filter is added to those already selected.

In the Market PRO Filter plugin, this mechanism is implemented by the marketprofilter_get_faceted_counts() function. For each parameter displayed in the filter form, a separate SQL query is executed that counts the number of products for all its possible values taking into account all other active filters except this parameter itself. Thus, after selecting, for example, a battery voltage of “48V”, next to each capacity (e.g. “21 Ah”) the number of products that have both 48V and that capacity is shown. This allows the buyer to immediately see which combinations of characteristics exist, and to avoid dead‑end situations where the filter finds no products.

To account for selected values of the current parameter (i.e., when several checkboxes within one group are selected) an EXISTS condition is added to the query, requiring the product to have at least one of the checked values. This implements “OR” logic for checkboxes and ensures that the counters within a group are recalculated correctly.

1.2 Parameters and Their Types

Each parameter is described in the cot_marketprofilter_params table by the following fields:

• param_id – an auto‑increment integer identifier.
• param_name – a unique system code consisting of Latin letters, digits, and the underscore character. This code is used in the filter URL (filter_<code>) and as a key in the database. For example: 001_03_samokat_battery_capacity.
• param_title – a service name in the default language (can be overridden through the internationalization mechanism).
• param_type – one of four types: range, select, checkbox, radio.
• param_values – a JSON string that defines the allowed values of the parameter:
  • For range – an object with the keys min and max, e.g. {"min":0,"max":100}.
  • For select, checkbox, radio – a JSON array of strings, e.g. ["digital_display","speedometer","mobile_app"].
• param_category – the structure code of the Market category to which the parameter is linked. If left empty, the parameter is considered “global” and is displayed in all categories that contain products.
• param_active – activity flag (1 – the parameter is displayed, 0 – hidden).
• param_superadmin – if set to 1, the parameter is not shown and is not taken into account for ordinary visitors; only users of the administrators group (group 5) can filter by it.
• param_helpinfo – hint text that can contain HTML tags and is displayed next to the parameter in the filter form and on the product page.

Parameter types determine the appearance of the element in the filter and the way the value is stored:

Range – intended for numerical characteristics such as price, weight, power. In the database, a string min-max is stored for the product (e.g. 1000-1500). When filtering, this string is parsed using CAST(SUBSTRING_INDEX(...) AS DECIMAL), which allows the numerical boundaries to be compared.

Dropdown (select) – allows exactly one value to be chosen from a predefined list. In the values table, exactly one record with the key of the chosen option is saved for the product.

Checkboxes (checkbox) – allow multiple options to be selected simultaneously. Multiple records can be created in cot_marketprofilter_params_values for a single product, one for each selected option. A unique index prevents duplicate insertions.

Radio buttons (radio) – similar to select, but presented as switches. One record is stored in the database.

1.3 Data Storage and Indexing

The main plugin tables:

• cot_marketprofilter_params – parameter definitions.
• cot_marketprofilter_params_values – product‑parameter‑value linkage. Contains the fields:
  • fieldmrkt_id – product identifier from the cot_market table.
  • param_id – parameter identifier.
  • param_value – string value (for range in min-max format, for the rest – the option key).
• cot_marketprofilter_i18n – translations of titles, values, and hints for each language.

A critically important element of performance is indexing. The values table has a unique composite index uniq_field_param_value (fieldmrkt_id, param_id, param_value), which solves several tasks at once:

• Guarantees the absence of duplicates.
• Speeds up searches when filtering, where conditions are built on param_id and param_value, and the join with the products table is done via fieldmrkt_id.
• Optimizes faceted queries with multiple INNER JOINs, because MySQL can use the index for fast access to the rows.

Foreign keys (FOREIGN KEY) ensure cascading deletion: when a product or parameter is deleted, all related values are automatically removed.

1.4 Multilingualism

The plugin supports three locales: ua (Ukrainian), ru (Russian), en (English). The language in which the titles and parameter values are displayed is determined in the following priority order:

1. The current user’s language (Cot::$usr['lang']), if it is in the list of supported languages.
2. The default language specified in the plugin settings (marketprofilter_defaultlang).
3. The general site language (Cot::$cfg['defaultlang']).

Translations are stored in the cot_marketprofilter_i18n table. Each record contains:

• i18n_param_id – a reference to the parameter.
• i18n_locale – language code (ua/ru/en).
• i18n_title – localized title.
• i18n_values – a JSON object containing the translation of the parameter’s values. The keys must exactly match the options specified in param_values of the main parameter. For example, for param_values: ["red","green"], the translation could be {"red":"Red","green":"Green"}.
• i18n_helpinfo – translation of the hint.

If a translation in a particular language is missing, the functions marketprofilter_get_title() and marketprofilter_get_value() automatically substitute either the value in the default language or a technical identifier, guaranteeing that the interface will always contain meaningful text.

Thanks to this approach, the administrator can centrally manage all textual representations of the filter without editing templates or PHP code.

1.5 Caching of Counts

Faceted queries are potentially resource‑intensive, especially when several filters are used simultaneously. To reduce the load on the database and speed up the page response, the plugin applies simple but effective file caching.

When the function marketprofilter_get_faceted_counts() is first called, a unique key is generated, consisting of the parameter identifier, the current category, and a sorted set of GET parameters. The result of the query is saved as a JSON file in the directory datas/cache/marketprofilter/. The lifetime of such cache is 300 seconds (5 minutes). When the same set of filters is requested again within that time, the data is instantly retrieved from the file, bypassing SQL execution.

The cache is automatically cleared when any product is modified – in the hook for saving product parameters (marketprofilter.market.edit.update.done.php) marketprofilter_cache_clear() is called, which deletes all .cache files in the plugin folder. This guarantees that visitors always see up‑to‑date figures after the catalog is edited.

If desired, the administrator can disable caching by changing the corresponding call in the function, or adjust the lifetime.

1.6 Security and Access Rights

The plugin carefully escapes all data output in HTML:

• Names, titles, and parameter values are passed through htmlspecialchars() before being inserted into the template.
• An exception is made for the hint field (param_helpinfo), which is output without escaping because it may contain HTML and is filled only by administrators in a trusted control panel.

Super‑admin parameters (param_superadmin = 1) are completely hidden from ordinary users:

• The marketprofilter_is_admin() function checks whether the current user belongs to group 5.
• When building the filter on the frontend and on the product page, such parameters are excluded from the selection.
• In faceted counts, super‑admin parameters are also not taken into account, which prevents the leakage of information about the number of products with restricted characteristics.

All SQL queries use parameterized expressions with placeholders, which excludes the possibility of SQL injections.

1.7 Integration into Cotonti

The plugin uses the standard hook system of Cotonti, which guarantees compatibility and the absence of modifications to the core. The main hooks:

• market.list.query – modifies the variables $sql_item_count and $sql_item_string, adding the necessary JOIN and WHERE clauses for filtering the product list.
• market.list.tags – builds and passes to the template the {MARKET_FILTER_FORM} block (filter form) and associated variables (MARKETFILTER_MESSAGE, MARKETFILTER_MESSAGE_CLASS).
• market.tags – adds the {MARKET_FILTER_PARAMS} block with a list of assigned characteristics to the product page template.
• market.edit.tags – inserts into the product editing form in the admin panel the {MARKET_FORM_FILTER_PARAMS} block with the interface for assigning parameter values.
• market.edit.update.done – processes the saving of selected parameter values when updating a product.
• tools – registers the plugin administration page in the “Extensions” section.

The plugin templates are loaded with the possibility of overriding: for example, for the electric-scooters category, the template marketprofilter.filterform.electric-scooters.tpl will be searched for first, and if it is absent, the standard marketprofilter.filterform.tpl will be used. This allows flexible changes to the filter design for different sections of the catalog.

Section 2. Practice: How the Filter Works on the Frontend

2.1 Appearance and Structure of the Form

On the product category page, the filter form is usually placed in the sidebar or above the product list. It is wrapped in a Bootstrap 5 card (card p-3 mb-4 rounded-2 border border-success-subtle). In the top right corner, there is a button with a question‑mark icon that opens a modal window with general help on how to use the filter.

The form is submitted via GET, which makes it easy to save the filtering state in the URL and share links. Hidden fields pass the current category (c), the module (e=market), the language (l) and the flag saveFilter=1 (if necessary).

Each parameter occupies a block <div class="mb-3">. The parameter title is displayed in bold; if a hint has been set for the parameter, a question‑mark icon appears next to the title, opening a separate modal window with the hint text.

2.2 Behavior by Type

Range – represented by a slider <input type="range">. Above the slider, the minimum value and the current selected maximum value are shown (updated via the JavaScript function updateRangeValue). The styling uses the CSS variable --value-percentage, which allows the traveled part of the track to be filled with a gradient.

Dropdown (select) – a standard <select> with an additional empty option “---” (so the selection can be cleared). Each item contains the text of the option and, in parentheses, the number of available products, e.g.: “48 (12)”. If an option was previously chosen, it receives the selected attribute.

Checkboxes (checkbox) – each checkbox is wrapped in <div class="form-check">. Next to the label, a “badge” with the product count is displayed if that count is greater than zero. Example: <span class="badge rounded-pill text-bg-warning me-1">12</span>Digital Display. Checked checkboxes receive the checked attribute. The field name is formed as an array (name="filter_...[]"), which allows multiple values to be transmitted.

Radio buttons (radio) – similar to checkboxes, but the field name is transmitted without square brackets, so only one option can be selected. The product count is also displayed.

2.3 Live Counters (Faceted Counts)

The main feature of the plugin is the dynamic numbers next to each option. When a visitor selects a filter for one parameter and clicks “Apply”, the page reloads, and all counters in the form are updated taking the selected value into account.

Example: in the “Electric Scooters” category there are parameters “Battery Voltage” (checkbox) and “Battery Capacity” (select). When the page first opens, the number 20 may appear next to “48V” (the total number of products with that voltage), and the number 8 next to “21 Ah”. After selecting “48V” and clicking “Apply filters”, the page refreshes. Now the counter for “21 Ah” will change and show the number of products that have both 48V and 21 Ah capacity – for example, 3. Similarly, the figures for all other parameters will be recalculated. This allows the buyer to see on the fly whether the selection is narrowing and to avoid wasting time on combinations that yield zero results.

Technically, the update occurs because marketprofilter_get_faceted_counts() is called for each parameter when building the form. The function analyzes all filter_* keys in $_GET, excluding the one for which counts are being computed, and builds an SQL query with multiple INNER JOINs. To account for the selection within the current group (for example, when several checkboxes of one characteristic are checked) EXISTS is used, which gives correct figures within one group.

2.4 Filter URL and Pagination

All selected filters are saved in the URL as parameters filter_<parameter_code>=<value>. The plugin explicitly adds these parameters to the $list_url_path array, which is used by Cotonti’s pagination system. Consequently, the links to subsequent pages of the product list automatically contain the current filters, allowing the user to browse pages without losing the selected conditions.

The “Reset filters” button leads to the clean category URL (cot_url('market', ['c' => $current_cat])), removing all filter_* parameters.

2.5 Informational Message

Above the product list (or elsewhere, as defined by the template), a message about the number of found items is displayed. The template variables MARKETFILTER_MESSAGE and MARKETFILTER_MESSAGE_CLASS are used for this purpose. The count is inserted into the localization string marketprofilter_found_items (e.g., “Found 5 items”) or marketprofilter_no_items (“No items found matching the specified parameters”). The class alert-success or alert-warning allows the message to be styled appropriately.

2.6 Presentation of Parameters on the Product Page

On the individual product page, the {MARKET_FILTER_PARAMS} tag outputs a table (or list) with the assigned parameters. For each parameter, the following is shown:

• The translated parameter name (PARAM_TITLE).
• The formatted value (PARAM_VALUE): for ranges – “1000 — 1500”, for checkboxes – values separated by commas, for selects and radios – the text of the option.
• The hint (PARAM_HELP), if set.

The template of this block is located in the file marketprofilter.market.tags.php.

2.7 Example of a Real Usage Scenario

A buyer enters the “Electric Scooters” category. They see a filter with parameters: brand, power, voltage, capacity, wheel diameter, suspension type, features. All counters show the overall quantities. They select the brand “Kugoo” (the number of products decreases). Then they add power “1700 – 2000 W”. The counters for wheel diameter, voltage, and other characteristics update, reflecting only Kugoo scooters with the specified power. The buyer decides to see how many among them have 10‑inch wheels – sees the number 4. They follow the link, browse the results, without losing the filters.

Section 3. Administrator Guide

3.1 Accessing Parameter Management

To configure the filter, go to the Cotonti administration panel, then to “Extensions” → “Market PRO Filter”. If the plugin is installed correctly, you will see a page with the title “Filter Parameter Management”.

3.2 Table of Existing Parameters

At the bottom of the page there is a table listing all created parameters. It has the following columns:

• ID – internal identifier.
• Parameter code – system name (e.g., 001_04_samokat_battery_voltage).
• Parameter name – translated title (if no translation, the system code is shown).
• Parameter type – one of: range, select, checkbox, radio.
• Parameter values (JSON) – the content of the param_values field, displayed in a monospaced font.
• Category – the code of the category to which the parameter is linked, or a dash if no category is set.
• Active – “Yes” or “No”.
• 🔒 Admin – a mark if the parameter is admin‑only.
• Hint – the first 50 characters of the hint.
• Actions – “Edit” and “Delete” buttons.

The table supports page navigation (pagination): if there are more parameters than 15 (the value from Cotonti settings maxrowsperpage), links for navigating between pages appear.

3.3 Adding a New Parameter

1. Click the “Add parameter” button located above the table.
2. Fill in the form that appears:
   • Parameter code (param_name) – a unique identifier, Latin letters, digits, underscores, no spaces. Example: 001_samokat_max_speed. This code will be used in the URL (after filter_) and in the database. Changing the code after creation is not recommended, as it will affect existing products.
   • Parameter name (param_title) – a service name in the default language. It can be overridden in the translation section for each language.
   • Parameter type (param_type) – choose from the dropdown: “Range”, “Dropdown list”, “Checkboxes”, “Radio buttons”. This determines how the element will look in the form and how the values will be interpreted.
   • Parameter values (JSON) (param_values) – edit the text field:
     • For range, enter a JSON object strictly in the format {"min":0,"max":100}. min and max must be numbers, and min <= max.
     • For select/checkboxes/radio buttons, enter a JSON array of strings, e.g. ["val1","val2","val3"]. Each string is a machine key of the option. Later these keys will be translated.
   • Category (param_category) – select the Market category to which the parameter will belong. If left empty, the parameter will be displayed in all categories (global parameter). For example, you can specify electric-scooters.
   • Active (param_active) – check the box so that the parameter is immediately displayed in the filter.
   • Admin only (param_superadmin) – if checked, the parameter will be hidden from ordinary visitors and available only to users of the administrators group (group 5). This is convenient for service characteristics that should not affect the public filter.
   • Hint / Explanation (param_helpinfo) – optional field. Here you can enter text (HTML is allowed) that will be shown as a tooltip next to the parameter in the filter form and on the product page.
3. Click “Add” (Add).

3.4 Editing a Parameter

1. In the parameters table, click the “Edit” button next to the desired record.
2. You will be taken to an editing form that is similar to the add form, but already filled with the current data.
3. Make the necessary changes and click “Save” (Save). To discard changes, click “Cancel” (Cancel), which will return you to the parameter list.

Important: the “Parameter code” field should not be changed unless absolutely necessary, as it is used as a key in many places.

3.5 Deleting a Parameter

Click the “Delete” button in the parameter row. A deletion confirmation will appear. After confirmation, the parameter, all its translations, and links to products will be deleted irreversibly.

3.6 Translations (Multilingualism)

When editing a parameter, below the main form there is a “Translations” section. For each supported language (RU, EN, UA) three fields are provided:

• Parameter name (XX) – the translated title that will be seen by users with the corresponding interface language.
• Value translation (XX) – here you need to enter a JSON object where the keys strictly correspond to the values from param_values, and the values are their translations. For example, if param_values = ["red","green"], then i18n_values for English should be {"red":"Red","green":"Green"}. For the range type this field is not displayed.
• Hint / Explanation (XX) – translation of the hint text.

If any field is left empty, the value from the default language or a technical key will be used.

3.7 Cache Management

The cache of faceted counts is updated automatically when a product is saved. If for some reason a complete cache clearing is required, simply delete all files with the .cache extension in the folder datas/cache/marketprofilter/ (e.g., via FTP or a file manager). Another option is to temporarily comment out the clearing line in the product save hook, but this is not required in normal operation.

3.8 Logging

The plugin has a built‑in logging system that writes debugging information to files inside the folder plugins/marketprofilter/logs/. To enable logging, go to the plugin settings (Configuration → Market PRO Filter) and set the parameter “Enable logging and journaling” to “Yes”. Logs are saved to the file marketprofilter.log, and every 72 hours an archive copy is created with a timestamp. This helps to diagnose problems with filtering.

3.9 JSON Examples for Different Types

When filling in the “Parameter values (JSON)” field, it is important to observe the syntax:

• Power range (W):

  json

  {"min":0,"max":3000}

• Dropdown for wheel diameters (inches):

  json

  ["8","10","12","14","16","20"]

• Checkboxes for modification features:

  json

  ["digital_display","speedometer","mobile_app","foldable","seat","suspension"]

• Radio buttons for suspension type:

  json

  ["no_suspension","front_suspension","rear_suspension","dual_suspension"]

Use double quotes for keys and string values. Do not put a comma after the last element. The validity of the JSON can be checked using any online validator (e.g., jsonlint.com). Invalid JSON will cause an error when saving the parameter.

3.10 Recommendations for Organizing Parameters

• Group parameters meaningfully. It is convenient to name parameter codes with a category or theme prefix, e.g. 001_ for electric scooters, 002_ for electric bicycles.
• Do not overuse checkboxes with a very large number of options – each option creates a separate record in the values table, which can slow down performance with a very large number of products (thousands and tens of thousands). However, this is not a problem for typical online stores.
• Use super‑admin parameters for hidden technical data (e.g., supplier names, internal article numbers) that should not be visible to buyers.
• Regularly check the logs, especially after updating the plugin or changing the category structure.

Conclusion

The Market PRO Filter plugin is a powerful, flexible, and deeply developed product filtering tool for Cotonti. The combination of faceted logic, thoughtful indexing, file caching, and full multilingual support makes it suitable for both small catalogs and large stores with hundreds of characteristics. The detailed documentation presented above will help developers and administrators effectively use all the capabilities of the plugin, while buyers will be able to quickly find the right products in a user‑friendly interface.