Подробное описание плагина Pure Query

1. Общее описание

Pure Query — мощный конструктор кастомной выдачи для WordPress, разработанный студией Pure SEO. Плагин позволяет создавать гибкие выборки записей любого типа (посты, товары WooCommerce, произвольные типы записей) и отображать их в виде адаптивной сетки или карусели (Swiper) с полностью настраиваемым визуальным конструктором карточки.

Версия: 1.1.5 | Требования: WordPress ≥ 5.6, PHP ≥ 7.4

---

2. Архитектура плагина

Файловая структура:

pure-query/
├── pure-query.php                        # Главный файл плагина (загрузка, константы)
├── uninstall.php                         # Очистка опций при удалении
├── includes/
│   ├── class-pure-query-fields.php       # Обнаружение полей для типов записей
│   ├── class-pure-query-admin.php        # Админ-интерфейс (меню, страницы, шаги)
│   ├── class-pure-query-ajax.php         # AJAX-обработчики (сохранение, загрузка полей)
│   └── class-pure-query-render.php       # Фронтенд-рендеринг (шорткод, сетка, слайдер, карточки)
├── assets/
│   ├── css/
│   │   ├── admin.css                     # Стили админки
│   │   ├── builder.css                   # Стили конструктора карточек
│   │   ├── front.css                     # Базовые стили фронтенда
│   │   └── front-slider.css              # Стили карусели (поверх Swiper)
│   └── js/
│       ├── admin.js                      # Логика админки (шаги, AJAX, формы)
│       ├── builder.js                    # Drag & drop конструктор (SortableJS)
│       ├── front-pagination.js           # Прогрессивная подгрузка (load more)
│       └── front-slider.js               # Инициализация Swiper

Принцип работы:

1. При активации создается пустой список выдач (pure_query_list).
2. Администратор создаёт новую выдачу через пошаговый мастер.
3. Настройки сохраняются в wp_options под ключом pure_query_{ID}.
4. На фронтенде шорткод [pure_query id="..."] рендерит HTML на основе сохранённой конфигурации.

---

3. Административный интерфейс

Плагин добавляет пункт меню Query в раздел Pure plugins в админ-панели WordPress.

Страница со списком выдач:

• Таблица со всеми созданными выдачами (название, тип записи, тип лейаута, шорткод).
• Кнопка «Добавить выдачу».
• Кнопки «Редактировать» / «Удалить» для каждой выдачи.
• Шорткод с кнопкой копирования в буфер обмена.
• Тип лейаута отображается иконкой (сетка/карусель).

Пошаговый мастер создания/редактирования выдачи:

Состоит из 4 шагов с табами:

Шаг 1: Тип записи

• Название выдачи — произвольное название (например, «Похожие товары»).
• Тип записи — выбор из всех публичных типов записей (посты, страницы, товары, CPT и т.д.). При выборе типа записи AJAX-запросом загружаются доступные поля для конструктора.

Шаг 2: Конструктор карточки

Визуальный drag & drop конструктор для создания макета карточки записи. Состоит из двух панелей:

• Левая панель (Доступные поля): Список полей, сгруппированных по категориям:
• Стандартные поля (миниатюра, заголовок, содержимое, отрывок, дата, автор, ссылка, комментарии)
• Таксономии (категории, теги, произвольные таксономии)
• WooCommerce (цена, артикул, статус, рейтинг, кнопка «В корзину», бейдж скидки, галерея и др.)
• Атрибуты товара (цвет, размер и т.д.)
• ACF поля (если установлен Advanced Custom Fields)
• Мета-поля (автоматически обнаруженные meta_keys из БД)
• Элементы карточки WC (ссылка на товар, миниатюра, заголовок, рейтинг, цена, кнопка и т.д. с точным контролем хуков)
• Правая панель (Холст): Область, куда перетаскиваются поля. Поддерживает:
• Перетаскивание полей из левой панели на холст.
• Создание контейнеров (групп) для вложенной структуры.
• Перетаскивание элементов внутри холста и между контейнерами.
• Удаление элемента обратно в панель доступных полей.
• Задание кастомного CSS-класса для каждого элемента.
• Автоматическое обновление дефолтных классов на основе вложенности.

Шаг 3: Лейаут

Выбор между двумя типами отображения:

Сетка (Grid):

• Количество записей на странице.
• Адаптивные колонки: десктоп, планшет, мобильный.
• Отступы между элементами (gap).
• Тип пагинации: нет / по страницам / «Загрузить ещё».
• Показывать сортировку товаров (только WooCommerce).
• Показывать кнопки вариаций Pure Attributes.

Карусель (Swiper):

• Общее количество слайдов.
• Адаптивное количество слайдов на экране (десктоп/планшет/мобильный).
• Промежуток между слайдами.
• Скорость анимации.
• Зацикливание (loop).
• Автоплей с настраиваемой задержкой.
• Стрелки навигации.
• Free Mode.
• Тип пагинации: нет / точки (bullets) / счётчик (fraction) / прогресс-бар.
• Эффект перехода: Slide / Fade / Coverflow.

Шаг 4: Выборка

Базовые параметры:

• Сортировка: по дате, заголовку, случайно, порядку меню, комментариям, дате изменения, мета-полю, популярности (WC), рейтингу (WC), цене (WC).
• Направление сортировки (ASC/DESC).
• Мета-ключ для сортировки (если выбрана сортировка по мета-полю).
• Смещение (offset).
• Исключение текущей записи.

Фильтрация по таксономиям:

• Динамические фильтры для каждой таксономии выбранного типа записи.
• Выбор нескольких терминов из каждой таксономии.
• Оператор: IN / NOT IN / AND.
• Связь между таксономиями: AND / OR.

Контекстные фильтры:

• Автоматический отбор на основе текущей страницы:
• Та же категория (текущая запись/категория).
• Тот же тег.
• Произвольные таксономии (те же, что и у текущей записи/термина).

Фильтрация по мета-полям:

• Добавление неограниченного количества условий по meta_key.
• Операторы: =, !=, >, <, >=, <=, LIKE, EXISTS, NOT EXISTS.
• Связь между условиями: AND / OR.

Фильтры WooCommerce (только для товаров):

• Источник товаров:
• Обычная выборка.
• Upsell (сопутствующие товары текущего товара).
• Cross-sell (кросс-продажи текущего товара).
• Связанные товары (Related).
• Те же атрибуты (поиск товаров с совпадающими атрибутами).
• Ценовой диапазон (товары в пределах ±% от цены текущего).
• Выбор атрибутов для сопоставления (для «Те же атрибуты»).
• Оператор атрибутов: любой из (OR) / все из (AND).
• Диапазон цены в процентах.
• Дополнительные фильтры: только в наличии, только со скидкой, только рекомендуемые.
• Кастомный символ валюты.

---

4. Система полей (class-pure-query-fields.php)

Класс Pure_Query_Fields отвечает за обнаружение и группировку полей для каждого типа записи.

Категории полей:

Категория	Описание
standard	Стандартные WordPress поля: post_thumbnail, post_title, post_content, post_excerpt, post_date, post_modified, post_author, post_permalink, comment_count, post_format
taxonomies	Все публичные таксономии, прикреплённые к типу записи
woocommerce	Специфичные поля WooCommerce: product_price_html, product_regular_price, product_sale_price, product_sku, product_stock_status, product_stock_quantity, product_weight, product_dimensions, product_rating, product_review_count, product_short_description, product_add_to_cart, product_on_sale_badge, product_gallery, product_type, product_total_sales
attributes	Атрибуты товара (как отдельные поля)
wc_hooks	Структурные элементы WC-карточки (открытие/закрытие ссылки, миниатюра, заголовок, рейтинг, цена, кнопка, бейдж скидки)
acf	Поля Advanced Custom Fields (автоматически определяются и маппятся на простые типы)
meta	Произвольные meta-поля из БД (исключая защищённые и уже известные поля)

Плагин умеет отображать ACF-поля различных типов: image, gallery, link, file, wysiwyg, oembed, true_false и другие.

---

5. Рендеринг на фронтенде (class-pure-query-render.php)

Шорткод [pure_query id="..."]

• Принимает единственный атрибут id (идентификатор выдачи).
• Строит WP_Query на основе сохранённой конфигурации.
• Применяет фильтры таксономий, мета-полей, контекстных условий и WooCommerce-специфик.
• Поддерживает интеграцию с Pure Filter (сортировка, фильтрация, пагинация передаются в POST-запросах).

Особенности рендеринга:

1. Адаптивная сетка: Генерирует inline CSS с grid-template-columns для десктопа, планшета и мобильного + медиа-запросы. Для товаров WooCommerce дополнительно сбрасываются стандартные float-стили через !important.
2. Карусель: Использует Swiper 11.x. Конфигурация передаётся через JavaScript-объект pqSwiperConfigs в футере, где инициализируются экземпляры Swiper.
3. Конструктор карточек: Поля рендерятся строго по позициям на холсте. Контейнеры оборачиваются в <div>, поля — в <div> с CSS-классом. Поддерживаются вложенные структуры.
4. WooCommerce-интеграция:

• Карточки товаров рендерятся внутри <li> с классами product и wc_get_product_class().
• Управление хуками: плагин отключает стандартные WC-хуки (woocommerce_template_loop_product_link_open/close, add_to_cart), чтобы они не дублировались при использовании конструктора.
• Поддержка Pure Attributes: если поле wc_loop_item_add_to_cart добавлено в конструктор, кнопка «В корзину» может быть заменена на форму вариаций Pure Attributes.
• Сортировка товаров через выпадающий список (кастомная реализация, не стандартный WC_Query).

1. Пагинация:

• Стандартная пагинация по страницам (с использованием paginate_links).
• Прогрессивная подгрузка (load more) через fetch() + DOMParser (без jQuery). Работает через product-page GET-параметр для управления страницами.
• При интеграции с Pure Filter пагинация может управляться фильтром (хук pure_query_pagination_managed_by_filter).

1. Кастомный символ валюты: Если задан в настройках выдачи, подменяет символ валюты WooCommerce через фильтр woocommerce_currency_symbol во время рендеринга.
2. Сортировка на фронтенде: Работает через GET-параметр orderby. При наличии Pure Filter на странице, сортировка перехватывается его AJAX-обработчиком.

---

6. AJAX-обработчики (class-pure-query-ajax.php)

Действие	Описание
pure_query_get_fields	Загружает поля для выбранного типа записи (стандартные, таксономии, WC, ACF, мета)
pure_query_get_terms	Загружает термины для указанной таксономии
pure_query_get_attributes	Загружает атрибуты WooCommerce с их терминами
pure_query_save	Сохраняет конфигурацию выдачи (санитизация, генерация ID, обновление списка)
pure_query_delete	Удаляет выдачу по ID

Все запросы защищены nonce (pure_query_admin) и проверкой прав manage_options.

---

7. Интеграции

С Pure Filter:

• Передача pure_query_id для совместной фильтрации (AJAX).
• Возможность управления пагинацией через фильтр (хук pure_query_pagination_managed_by_filter).
• Сортировка может обрабатываться Pure Filter при наличии на странице.

С Pure Attributes:

• Автоматическое отображение кнопок вариаций и форм покупки в карточках товаров.
• Возможность отключить для конкретной выдачи (настройка «Показывать кнопки и вариации Pure Attributes»).

С Advanced Custom Fields (ACF):

• Автоматическое обнаружение групп полей, привязанных к типу записи.
• Рендеринг всех основных типов ACF-полей (изображения, галереи, ссылки, файлы, WYSIWYG, true/false и др.).

---

8. Системные хуки и фильтры

Хук/Фильтр	Описание
pure_query_grid_pagination_type	Позволяет изменить тип пагинации для сетки
pure_query_pagination_managed_by_filter	Указывает, управляется ли пагинация внешним фильтром
pre_get_posts	Пометка AJAX-запросов Pure Filter (сохранение pure_query_id)
posts_orderby	Принудительная сортировка на SQL-уровне для Pure Query запросов

---

9. Удаление плагина

При деинсталляции (uninstall.php) плагин полностью очищает все свои опции:

• Удаляет настройки каждой выдачи (pure_query_{id}).
• Удаляет список выдач (pure_query_list).
• Не оставляет следов в базе данных.