qwelp.favorites · Руководство по подключению
Документация
Подключите кнопку, счётчик и страницу избранного. Полная встроенная справка о гостях, пользователях, многосайтовости, композите и обслуживании модуля.
Начало
Модуль сохраняет товары покупателя до и после входа в аккаунт. У каждого сайта свой список и лимит.
- Откройте «Квэлп → Избранное → Настройки»: задайте общий лимит и при необходимости лимиты сайтов.
- Во вкладке «Подключение» скопируйте примеры кнопки, страницы избранного и ссылки в шапке.
- Добавьте товар гостем, откройте список и войдите в аккаунт. Убедитесь, что товар сохранился.
В «Обзоре избранного» доступны статистика по сайтам и популярные товары. Просмотр и обслуживание модуля требуют права W; владельцем покупательского списка всегда остаётся текущий посетитель.
Подключение
1. Кнопка в карточке товара
Вставьте в PHP-шаблон детальной карточки, где доступны ID, IBLOCK_ID и NAME товара. Для карточек каталога замените $arResult на переменную текущего товара.
if (\Bitrix\Main\Loader::includeModule('qwelp.favorites'))
{
\Bitrix\Main\UI\Extension::load('qwelp.favorites');
echo \Qwelp\Favorites\Button::render(
(int)$arResult['ID'],
(int)$arResult['IBLOCK_ID'],
['template' => 'icon', 'productName' => (string)$arResult['NAME']]
);
}2. Страница избранного
Создайте страницу /favorites/index.php штатным редактором сайта. Между подключениями header.php и footer.php разместите компонент. Его настройки можно менять визуальным редактором.
$APPLICATION->IncludeComponent('qwelp:favorites.list', '', [
'PAGE_SIZE' => '12',
'SHOW_PRICE' => 'Y',
'PRICE_CODE' => '',
'SHOW_REMOVE_BUTTON' => 'Y',
'FAVORITES_TEMPLATE' => 'icon',
'IMAGE_WIDTH' => '200',
'IMAGE_HEIGHT' => '200',
'DETAIL_URL_TEMPLATE' => '',
]);3. Ссылка со счётчиком
Вставьте в шапку шаблона сайта. Если адрес страницы отличается, замените favorites/.
if (\Bitrix\Main\Loader::includeModule('qwelp.favorites'))
{
\Bitrix\Main\UI\Extension::load('qwelp.favorites');
echo \Qwelp\Favorites\Button::renderLink(SITE_DIR . 'favorites/');
}Собственный шаблон и оформление
Скопируйте шаблон компонента .default из /bitrix/components/qwelp/favorites.list/templates/ в /local/templates/ваш_шаблон/components/qwelp/favorites.list/ваш_вариант/. Сохраните script.js, динамический frame и атрибуты data-site-id / data-site-context. Не редактируйте установленный пакет: обновления проверяют его хеши.
У кнопки доступны варианты icon, text, star и bookmark. Дополнительный класс задаётся параметром className. Состояния active, loading и фокус должны оставаться различимыми.
Работа списка
| Ситуация | Результат |
|---|---|
| Повторное добавление | Дубликат не создаётся и лимит не расходуется повторно. |
| Торговое предложение | Сохраняется родительский товар. Предложения одного товара имеют общее состояние. |
| Товар выключен, скрыт датами или правами | Он временно не виден в списке и счётчике. Запись сохраняется; после восстановления доступа товар появится снова. |
| Товар удалён из каталога | Обработчик события удаляет его записи из избранного и очищает кеш. |
| Вход в аккаунт | Гостевой список объединяется с пользовательским отдельно по сайтам, без дублей и превышения лимита. Непоместившиеся записи остаются у гостя до следующего объединения или истечения срока хранения. |
| Очистка списка | Удаляются записи только текущего владельца и сайта. Ошибка отдельной записи отменяет операцию целиком. |
Цены выводятся только из разрешённого посетителю типа и для количества 1. Это цена каталога, без расчёта скидок корзины, доставки и условий заказа; предложения и персональная итоговая стоимость рассчитываются компонентами каталога и корзины.
Гостевое хранение и срок
Cookie содержит случайный идентификатор, закрытый для JavaScript. Сами товары хранятся на сервере. При режиме «Сессия» идентификатор живёт в сессии Bitrix. Смена режима не переносит прежние гостевые списки. Срок очистки считается от даты добавления записи; настройте уведомление о cookie в соответствии с политикой сайта.
Уменьшение лимита не удаляет записи. В лимит входят и временно недоступные товары. При большом списке покупатель может очистить его целиком.
Сайты и композит
- Разместите страницу избранного на каждом нужном сайте. Контекст текущего сайта определяется внутри компонента и подписывается сервером.
- Кнопки и счётчики размещайте штатными хелперами. Их обычный HTML неперсональный; JavaScript получает актуальное состояние через AJAX.
- Включите композит и проверьте страницу гостем и двумя разными аккаунтами. Чужой список или счётчик появляться не должен.
Ресурсы пакета устанавливаются в общий /bitrix/js/qwelp/favorites/, /bitrix/components/qwelp/favorites.list/ и /bitrix/admin/. Общий /local/ не требуется. Существующие локальные переопределения имеют приоритет и сохраняются.
Персональный PHP-вывод
Button::getInitJson(), checkState=true и initialState возвращают или задают персональное состояние. Используйте их только внутри динамического фрейма с setAutoUpdate(true) и пустой заглушкой. Не записывайте их результат в общий кеш страницы. У штатного favorites.list фрейм уже включён.
Подпись siteContext подтверждает активный сайт, но не является секретом покупателя. Владельца задаёт сервер. Все публичные AJAX-действия используют POST и CSRF. События JavaScript содержат siteId.
Обслуживание
Обычное обслуживание
- В «Обзоре избранного» выберите сайт и период добавления.
- В настройках включите автоматическую очистку гостей. При необходимости отметьте «Очистить сейчас» и сохраните настройки.
- После изменения шаблонов очистите композитный кеш средствами Bitrix; кеш модуля можно очистить в его настройках.
Установка и удаление
Устанавливайте и удаляйте модуль штатным разделом Marketplace. Перед удалением обязательно отправьте форму подтверждения. Флажок «Сохранить данные» включён по умолчанию. Собственные файлы проверяются по манифесту; изменённые или чужие файлы не перезаписываются и не удаляются.
Если установка или обновление остановились
Проверьте журнал ошибок сервера и наличие пользовательских изменений в конфликтующем пути. Сохраните нужные изменения в пользовательском шаблоне. Повторяйте операцию только после устранения причины. Прерванное удаление сохраняет исходный выбор сохранения данных и сведения для восстановления.
Старая разработческая установка в /local с манифестом без привязки к физическому корню требует отдельной миграции с резервной копией. Автоматически присваивать или удалять её файлы модуль не будет. Для первой Marketplace-установки используйте чистый стенд.
Справка
| Настройка | Диапазон / значение |
|---|---|
| Лимит списка | 1–10000 записей на владельца и сайт; по умолчанию 1000. |
| Хранение гостей | cookie / session; по умолчанию cookie. |
| Срок гостевых записей | 1–365 дней; по умолчанию 30. Очистка запускается агентом. |
| Кеш идентификаторов | 0–86400 секунд; по умолчанию 3600, 0 отключает. Права и доступность проверяются при чтении. |
| PAGE_SIZE | 1–100, по умолчанию 12. |
| IMAGE_WIDTH / IMAGE_HEIGHT | 1–1000, по умолчанию 200. |
| PRICE_CODE | Пусто — базовый разрешённый тип цены; иначе символьный код. |
| DETAIL_URL_TEMPLATE | Пусто — URL инфоблока; поддерживаются штатные плейсхолдеры элемента и пути разделов. |
Серверный API и события
После Loader::includeModule('qwelp.favorites') доступны FavoritesService::add, remove, toggle, exists, getCount, getProductIds, getList, clear, checkMultiple и getPrice. Изменения возвращают Bitrix\Main\Result: всегда проверяйте isSuccess() и getErrors(). Проверка checkMultiple принимает до 100 ID за вызов.
События модуля: OnBeforeAdd / OnAfterAdd, OnBeforeRemove / OnAfterRemove, OnBeforeClear / OnAfterClear. Возвращайте EventResult::ERROR в OnBefore-событии для отмены операции. Не вызывайте в обработчике повторно ту же операцию. Ошибки OnAfter записываются в журнал и не отменяют уже сохранённые данные.
События JS: BX.Qwelp.Favorites:added, removed, changed, cleared, countChanged, error. Используйте siteId при обработке. Публичные getState/checkMultiple передают подписанный siteContext; пользовательские или гостевые ID API не принимает.
Требования
PHP 8.2+, Bitrix main 23.0+, модули iblock, catalog, currency, MySQL / InnoDB. Редакции БУС: «Малый бизнес» и «Бизнес». Фактическая совместимость с текущим выпуском платформы подтверждается отдельной матрицей перед публикацией.
Полный текст встроенной справки, сверенный 09.09.2026. Названия меню и операции относятся к административному разделу вашей установки 1С-Битрикс. Примеры PHP предназначены для страницы сайта или копии шаблона компонента.