📑 У цій статті

  1. Проблема: фільтри в OpenCart і чому стандартні модулі ламають тему
  2. Що таке AI Filters v1.0.5 і навіщо event-injected рендеринг
  3. Швидка установка за 5 хвилин
  4. Що отримуєте з коробки
  5. Сумісність з популярними OpenCart-темами
  6. Просунуті налаштування: GA4, URL-state, exclude-self
  7. Troubleshooting: 6 типових проблем
  8. FAQ

У стандартному OpenCart фільтрів на сторінці пошуку немає, а на категоріях вони працюють з перезавантаженням сторінки. Сторонні модулі зазвичай вимагають правок twig-шаблонів — це означає що при оновленні теми вам або треба все робити заново, або фільтри ламаються. AI Filters v1.0.5 вирішує це через event-injected рендеринг: жодних правок теми, AJAX-режим, працює і на категоріях і на сторінці пошуку.

Проблема: фільтри в OpenCart і чому стандартні модулі ламають тему

OpenCart 3 і 4 з коробки мають слабкий filter-механізм:

  • На сторінці категорій — фільтри по атрибутах перезавантажують всю сторінку при кожному кліку. На каталозі 5k+ SKU це сповільнює UX до неприйнятного.
  • На сторінці пошуку (/index.php?route=product/search) стандартних фільтрів немає взагалі. Покупець знайшов 247 товарів — і не може звузити по бренду чи ціні.
  • OpenCart не має підрахунків per-facet count — користувач не знає скільки товарів залишиться після кліку, поки не клікне.

Сторонні модулі (особливо популярні в маркетплейсі OpenCart) зазвичай йдуть тим самим шляхом — модифікують template-файли категорії та пошуку. Наслідки:

⚠️
Класична пастка template-based фільтрів: при оновленні теми (або при купівлі нової) — фільтри або зникають, або ламають верстку. Розробник теми править template, а ваш filter-модуль очікує старого. Боротьба template-versioning vs theme-update.

Що таке AI Filters v1.0.5 і навіщо event-injected рендеринг

AI Filters — фасетний модуль що поставляється у складі AI Search v1.0.5. Працює окремо (можна використовувати без AI-пошуку) або разом з ним. Ключовий принцип — event-injected: модуль не модифікує template-файли. Натомість підписується на стандартні OpenCart events catalog/view/category/before та catalog/view/product/search/before, і вставляє HTML фільтрів у вже-зрендерений output.

💡
Що це дає на практиці: ви оновлюєте тему — фільтри продовжують працювати. Купуєте нову тему — встановлюєте, і фільтри з'являються без жодних редагувань. Жодних модифікацій category.twig чи search.twig не потрібно.

Швидка установка за 5 хвилин

  1. Зареєструйтесь на ai-search.cc — Google login або email.
  2. Завантажте aisearch.ocmod.zip з кабінету — це один архів і для AI Search, і для AI Filters.
  3. В адмінці OpenCart: Extensions → Installer → Upload → виберіть zip → Continue.
  4. Extensions → Modifications → Refresh (важливо — інакше events не активуються).
  5. Extensions → Extensions → Modules → знайти AI Filters → Install → Edit → ввімкнути Status: Enabled → Save.
  6. Перейдіть на frontend і відкрийте будь-яку категорію чи сторінку пошуку. Фільтри з'являться зліва (або у налаштованому положенні).
✅
Це все. Жодних правок category.twig, search.twig чи будь-яких інших template-файлів. Перевірено на офіційній OpenCart-темі та популярних сторонніх (Journal, OctTheme, Ronix, Shoppica).

Що отримуєте з коробки

⚡
AJAX-режим без перезавантажень
🎯
Per-facet counts (exclude-self)
🔗
URL-state для share
📊
GA4 / dataLayer events

AJAX-режим: переключення без reload

Користувач клікає чекбокс — фільтр-панель і список товарів оновлюються без перезавантаження сторінки. Це не SPA-overlay (як у Klevu) — просто XHR-запит до власного endpoint, який повертає новий список ID товарів. URL змінюється через history.pushState(), тож користувач може поділитися посиланням з активними фільтрами.

Per-facet counts з exclude-self логікою

Якщо у вас групи "Колір", "Розмір", "Бренд", і користувач уже вибрав "Чорний", "M" — інші чекбокси показують скільки товарів буде доступно після додавання цього фільтра. Але всередині групи "Колір" числа залишаються без врахування "Чорний" — щоб користувач бачив скільки товарів є з іншими кольорами на тих же фільтрах розміру/бренду. Це називається exclude-self per-group.

Native HTML5 dual-range slider для ціни

Без сторонніх JS-бібліотек. Працює на mobile (touch). Debounced — XHR відбувається після 500ms бездіяльності, не на кожному pixel.

URL-state у CSV форматі

Приклад URL зі активними фільтрами

/index.php?route=product/category&path=20&ai_f[manufacturer]=12,15&ai_f[price]=100-500&ai_f[color]=red,blue

Формат ai_f[group]=v1,v2,v3 — людиночитаний, легко debug-ається, share-friendly. Можна давати посилання на конкретну добірку у Telegram/email.

GA4 / dataLayer events

При кожному застосуванні фільтра у window.dataLayer вистрілює подія:

{ event: 'ai_filters_applied', filter_group: 'manufacturer', filter_value: '12', total_results: 47 }

Можете побудувати GA4-звіт: які фільтри найпопулярніші, які combo приводять до конверсії, де користувачі застрягають.

Сумісність з популярними OpenCart-темами

Event-injected підхід працює з будь-якою темою, яка не вимикає стандартні OpenCart events. Перевірено на:

  • Default OpenCart 3.x / 4.x — повна сумісність
  • Journal 3 / Journal 4 — працює без додаткових налаштувань
  • OctTheme — працює, рекомендуємо вимкнути власні фільтри Oct щоб не конфліктували
  • Ronix — працює
  • Shoppica — працює
🔍
Якщо у вас кастомна тема — у 95% випадків теж працюватиме. Якщо щось не з'являється — пишіть на [email protected], додамо під вашу тему.

Просунуті налаштування

1. Position: ліва колонка vs верх

В адмінці модуля: Filter Position → Left column / Top horizontal / Custom. У режимі Custom можна вказати CSS selector контейнера куди впорснути фільтри (приклад: .product-filter-container).

2. Active groups + сортування

Виберіть які групи показувати: ціна, виробник, колір, розмір, опції, атрибути, наявність, рейтинг. Drag-n-drop порядок. Можна окремо для категорій vs пошуку.

3. Mobile sticky bottom button

На мобільних пристроях панель фільтрів ховається за bottom-кнопку "Фільтри (3)" з лічильником активних. Тапнув — slide-up panel зверху списку товарів.

4. Conditional rules

"Показувати фільтр 'Колір' тільки якщо в активних результатах є хоча б 3 різних кольори". Робить UX чистіше — порожні фільтри не з'являються.

5. Кешування counts

Per-facet counts кешуються на рівні Redis або file-cache. Перший запит — обчислюється, наступні (з тими ж активними фільтрами) — миттєво з кешу. Кеш інвалідується автоматично при зміні товарів.

Troubleshooting: 6 типових проблем

❓
Фільтри не з'являються після установки.
99% випадків — забули натиснути Extensions → Modifications → Refresh після установки. Без цього events не активуються. Зробіть Refresh, очистіть Twig-кеш (Dashboard → Cache) і перевірте знову.
❓
Фільтри з'явилися, але AJAX не працює (повне перезавантаження).
Перевірте, чи jQuery завантажений. Якщо тема використовує своє bundling-решення без jQuery — увімкніть в адмінці AI Filters → Settings → Load jQuery in catalog.
❓
Counts показують 0 для всіх фільтрів.
Перевірте, що ви вже виконали reindex AI Search (навіть якщо AI-пошук не використовуєте — counts беруться з тієї ж бази). Зайдіть в Extensions → Modules → AI Search → Edit → Indexer → Start Indexing.
❓
Конфлікт зі своїми фільтрами теми.
Багато premium-тем (Journal, OctTheme) мають власні фільтри. Вимкніть їх у налаштуваннях теми або в адмінці AI Filters виберіть "Replace theme filters" — модуль автоматично заховає конкуруючий блок.
❓
Slider ціни ламається на mobile.
Перевірте viewport meta-тег у темі: <meta name="viewport" content="width=device-width, initial-scale=1">. Без нього touch-events падають.
❓
URL не зберігає стан фільтрів після reload.
Це означає що ваша тема перевизначає window.history. Контактуйте [email protected] з URL вашого магазину — додамо compatibility layer.

FAQ

Чи є AI Filters окремим продуктом, чи частиною AI Search?

Поставляється у складі AI Search v1.0.5 — один zip-архів, одна ліцензія. Можна використовувати тільки фільтри без AI-пошуку (вимкнути AI Search в адмінці, AI Filters залишити Enabled).

Чи це безкоштовно?

На Free-плані (до 200 SKU) — так. На платних тарифах AI Filters входить у вартість тарифу AI Search без доплат: Starter $12, Business $29, Pro $79, Enterprise $199.

Чи працюватиме на OpenCart 2.x?

Ні. Підтримуємо тільки OpenCart 3.0.x і 4.0.x. На OC 2 архітектура event-системи інша — доведеться писати окремий модуль.

А що з multistore?

Працює. Налаштування модуля можна задати окремо для кожного store через стандартний store-selector OpenCart.

Чи можна налаштувати які групи фільтрів показуються на пошуку vs на категоріях?

Так. У адмінці є дві окремі вкладки: Category Page Filters та Search Page Filters. Кожна зі своїм набором активних груп і їх порядком.

Скільки фільтрів можна додати на сторінку?

Технічного ліміту немає. На практиці UX починає страждати після ~12 груп — рекомендуємо приховати найменш популярні через Conditional rules (показувати тільки якщо є ≥3 значень).