Каталог в MODX: 7 типичных ошибок и как их исправить

Каталог в MODX может выглядеть исправным в админке и при этом терять товары на сайте, отдавать пустые фильтры или открывать карточки по неправильным URL. Чаще всего причина не в одном компоненте, а в несогласованной структуре ресурсов, TV-полей, чанков и кеширования. Ниже — практический разбор для MODX Revolution 3.x с типичной связкой pdoTools/pdoResources; если каталог работает на miniShop2, отдельные правила зависят от версии дополнения.

В MODX каталог — это не просто список страниц. Это договорённость между деревом ресурсов, полями товара, запросом выборки и шаблоном вывода. Если хотя бы один слой использует другое имя или идентификатор, пользователь видит пустой каталог.

1. Товары лежат не в том разделе дерева

Самая частая ошибка — товары создают в корне сайта или в соседнем разделе, а вывод ограничивают параметром родителя. В результате администратор видит ресурс в панели MODX, но запрос каталога его не находит.

Перед настройкой вывода зафиксируйте структуру. Например, отдельный ресурс «Каталог» имеет дочерние разделы «Ноутбуки» и «Мониторы», а карточки товаров лежат внутри этих разделов. Если категории должны быть виртуальными или один товар относится к нескольким категориям, обычного дерева может быть недостаточно: тогда нужна отдельная модель связей, например TV с идентификаторами или функциональность конкретного интернет-магазина.

• Проверьте родителя каждого товара в админке.
• Сверьте ID раздела с тем, который передаётся в вызов вывода.
• Убедитесь, что фильтр не исключает скрытые, удалённые или неопубликованные ресурсы.
• Откройте карточку напрямую и проверьте, что она опубликована и доступна в нужном контексте.

Цена ошибки — не только пустая выдача. Товар может случайно попасть в карту сайта, поиск или меню, хотя в каталоге его быть не должно.

2. Выборка и шаблон используют разные поля

В MODX название товара может храниться в системном поле pagetitle, в TV-поле «Название» или в поле товара miniShop2. Для человека это одно и то же название. Для запроса — три разных источника.

Такая рассинхронизация выглядит так: заголовок карточки выводится, а цена и изображение пустые; фильтр по бренду ничего не находит; сортировка работает не по цене, а по дате создания ресурса.

Составьте небольшую карту данных до написания чанка:

Не смешивайте форматирование с данными. Если в цене хранится строка «39 990 ₽», сортировка по ней может дать порядок 100 000, 12 000, 9 990. Числовое значение и отображение валюты лучше разделять.

3. TV-поля не попадают в выборку

TV-поле не всегда загружается автоматически вместе с ресурсом. Каталог может вывести заголовки, но оставить пустыми бренд, цвет или изображение, если запрос не запросил эти поля или чанк ожидает другое имя.

Вызовы pdoResources и похожих дополнений проверяйте по документации именно установленной версии pdoTools. Названия параметров и правила обработки TV могут отличаться от примеров для старых версий. Не переносите настройки из чужого проекта вслепую.

Как проверять проблему

1. Откройте один товар и убедитесь, что TV-поле заполнено.
2. Выведите это поле в простом тестовом шаблоне без карточки и условной логики.
3. Проверьте имя поля: «brand», «Brand» и «Бренд» для MODX не одно и то же.
4. Посмотрите итоговый HTML страницы и выясните, пришло ли значение в шаблон или исчезло раньше.

Если простая проверка показывает значение, ошибка находится в чанке, условии или форматтере. Если значения нет, ищите проблему в запросе, имени TV или привязке поля к шаблону ресурса.

4. Фильтр считает TV-поля обычными колонками

Фильтр по цене, бренду или диагонали часто добавляют поверх списка ресурсов одним условием. Но TV-поля находятся в отдельной таблице MODX и могут иметь несколько значений. Простое сравнение не гарантирует правильный результат, особенно когда цена хранится с пробелами и обозначением валюты.

Для фильтрации заранее определите тип параметра:

• точное значение — бренд или тип товара;
• набор значений — цвет или материал;
• числовой диапазон — цена, мощность, диагональ;
• поиск по тексту — название или артикул.

Для сложных фильтров выгоднее хранить характеристики в структуре, которую поддерживает выбранный компонент магазина, а не собирать всё из десятков свободных TV. Иначе запросы становятся длиннее, индексы базы не помогают, а каждое новое свойство требует правок в нескольких местах.

Проверяйте фильтр на трёх товарах: с одним значением, с несколькими значениями и с пустым значением. Отдельно проверьте URL после применения фильтра: параметры должны сохраняться при переходе на вторую страницу выдачи.

5. Кеш скрывает исправления

В MODX результат может быть закеширован на уровне самого тега, страницы, дополнения или прокси-кеша. Поэтому после изменения TV, чанка или параметров выборки вы продолжаете видеть старую карточку и принимаете это за ошибку в коде.

Порядок проверки должен быть одинаковым:

1. Сохраните ресурс и убедитесь, что изменение действительно записалось в админке.
2. Очистите кеш MODX штатным способом.
3. Откройте страницу в приватном окне или с отключённым кешем браузера.
4. Проверьте исходный HTML, а не только визуальный результат.
5. Если перед сайтом стоит CDN или серверный кеш, временно исключите URL каталога из кеширования.

Постоянно отключать кеш нельзя: каталог начнёт заново собирать тяжёлые выборки на каждый запрос. В рабочей системе лучше разделить данные, которые меняются редко, и данные, требующие быстрой актуализации.

6. Чанк карточки зависит от контекста, которого нет

Один и тот же чанк может использоваться для списка, страницы поиска и блока рекомендаций. Но в каждом вызове набор доступных плейсхолдеров отличается. В одном месте есть цена и изображение, в другом они пусты, хотя товар тот же.

Не исправляйте такую проблему добавлением случайных плейсхолдеров в чанк. Сначала определите источник данных конкретного вызова. Затем приведите имена к одному соглашению и проверьте карточку отдельно от списка.

Особенно часто ломаются изображения. В TV хранится имя файла, а шаблон ожидает полный URL; или медиа-источник возвращает путь с одним слешем, а чанк добавляет второй. Проверяйте итоговое значение в атрибуте src и статус ответа изображения в инструментах разработчика браузера.

7. URL и канонический адрес расходятся

Для товаров важны не только красивые адреса, но и их стабильность. Если URL строится из заголовка, а алиас меняется после переименования товара, поисковики и рекламные ссылки получают другой адрес. Если в каталоге одновременно работают несколько контекстов, один и тот же ресурс может открываться с разными доменами.

Заранее решите, что является постоянным идентификатором товара. Обычно это отдельный алиас или артикул, а не изменяемое маркетинговое название. После изменения адреса настройте корректное перенаправление средствами MODX или веб-сервера и проверьте, что старый URL не ведёт на случайную категорию.

Сравнение подходов к каталогу

Выбор архитектуры определяет, сколько ручной работы понадобится через полгода, когда появятся варианты товара, остатки и фильтры.

Если в каталоге уже нужны остатки, несколько цен, модификации и заказ, не пытайтесь бесконечно расширять набор TV-полей. На этом этапе стоимость миграции ниже, чем цена поддержки самодельной схемы.

Что ломается первым

• Пустой список. Проверьте родителя, публикацию, контекст и фильтр по статусу.
• Пустые TV-поля. Сверьте имя поля, привязку к шаблону и настройки загрузки TV.
• Неверная сортировка цены. Уберите валюту из хранимого значения и используйте числовой тип.
• Фильтр даёт лишние товары. Проверьте логику совпадения значений и пустые поля.
• После правки ничего не изменилось. Очистите кеш MODX, браузера и внешнего кеширующего слоя.

Что сделать дальше

Соберите для проекта таблицу полей: имя, тип, источник, обязательность и пример значения. Затем возьмите один товар и пройдите весь путь — от записи в админке до HTML карточки и URL. После этого проверьте каталог на тестовом наборе из пустых, граничных и заполненных значений.

В продакшене измеряйте время ответа страницы категории, количество SQL-запросов, размер HTML и долю ответов с пустыми карточками. Инвалидацию кеша и настройку SEO-метаданных стоит вынести в отдельную задачу: они связаны с каталогом, но не заменяют проверку структуры данных.

Сноска. TV (Template Variable) — дополнительное поле ресурса в MODX. Его значение хранится отдельно от основных полей страницы, поэтому для выборки и вывода часто нужна специальная настройка.