# Квэлп: Избранное

Полное руководство qwelp.favorites. Сверено с установленной документацией 9 сентября 2026 года.

## Начало



Модуль сохраняет товары покупателя до и после входа в аккаунт. У каждого сайта свой список и лимит.



1. Откройте «Квэлп → Избранное → Настройки»: задайте общий лимит и при необходимости лимиты сайтов.
2. Во вкладке «Подключение» скопируйте примеры кнопки, страницы избранного и ссылки в шапке.
3. Добавьте товар гостем, откройте список и войдите в аккаунт. Убедитесь, что товар сохранился.



В «Обзоре избранного» доступны статистика по сайтам и популярные товары. Просмотр и обслуживание модуля требуют права W; владельцем покупательского списка всегда остаётся текущий посетитель.

## Подключение



### 1. Кнопка в карточке товара



Вставьте в PHP-шаблон детальной карточки, где доступны ID, IBLOCK_ID и NAME товара. Для карточек каталога замените $arResult на переменную текущего товара.



```php
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 разместите компонент. Его настройки можно менять визуальным редактором.



```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/.



```php
if (\Bitrix\Main\Loader::includeModule('qwelp.favorites'))
{
    \Bitrix\Main\UI\Extension::load('qwelp.favorites');
    echo \Qwelp\Favorites\Button::renderLink(SITE_DIR . 'favorites/');
}
```



:::details Собственный шаблон и оформление



Скопируйте шаблон компонента .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. Это цена каталога, без расчёта скидок корзины, доставки и условий заказа; предложения и персональная итоговая стоимость рассчитываются компонентами каталога и корзины.



:::details Гостевое хранение и срок



Cookie содержит случайный идентификатор, закрытый для JavaScript. Сами товары хранятся на сервере. При режиме «Сессия» идентификатор живёт в сессии Bitrix. Смена режима не переносит прежние гостевые списки. Срок очистки считается от даты добавления записи; настройте уведомление о cookie в соответствии с политикой сайта.



Уменьшение лимита не удаляет записи. В лимит входят и временно недоступные товары. При большом списке покупатель может очистить его целиком.


:::

## Сайты и композит



1. Разместите страницу избранного на каждом нужном сайте. Контекст текущего сайта определяется внутри компонента и подписывается сервером.
2. Кнопки и счётчики размещайте штатными хелперами. Их обычный HTML неперсональный; JavaScript получает актуальное состояние через AJAX.
3. Включите композит и проверьте страницу гостем и двумя разными аккаунтами. Чужой список или счётчик появляться не должен.



Ресурсы пакета устанавливаются в общий /bitrix/js/qwelp/favorites/, /bitrix/components/qwelp/favorites.list/ и /bitrix/admin/. Общий /local/ не требуется. Существующие локальные переопределения имеют приоритет и сохраняются.



:::details Персональный PHP-вывод



Button::getInitJson(), checkState=true и initialState возвращают или задают персональное состояние. Используйте их только внутри динамического фрейма с setAutoUpdate(true) и пустой заглушкой. Не записывайте их результат в общий кеш страницы. У штатного favorites.list фрейм уже включён.



Подпись siteContext подтверждает активный сайт, но не является секретом покупателя. Владельца задаёт сервер. Все публичные AJAX-действия используют POST и CSRF. События JavaScript содержат siteId.


:::

## Обслуживание



### Обычное обслуживание



1. В «Обзоре избранного» выберите сайт и период добавления.
2. В настройках включите автоматическую очистку гостей. При необходимости отметьте «Очистить сейчас» и сохраните настройки.
3. После изменения шаблонов очистите композитный кеш средствами Bitrix; кеш модуля можно очистить в его настройках.



### Установка и удаление



Устанавливайте и удаляйте модуль штатным разделом Marketplace. Перед удалением обязательно отправьте форму подтверждения. Флажок «Сохранить данные» включён по умолчанию. Собственные файлы проверяются по манифесту; изменённые или чужие файлы не перезаписываются и не удаляются.



:::details Если установка или обновление остановились



Проверьте журнал ошибок сервера и наличие пользовательских изменений в конфликтующем пути. Сохраните нужные изменения в пользовательском шаблоне. Повторяйте операцию только после устранения причины. Прерванное удаление сохраняет исходный выбор сохранения данных и сведения для восстановления.



Старая разработческая установка в /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 инфоблока; поддерживаются штатные плейсхолдеры элемента и пути разделов. |



:::details Серверный 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. Редакции БУС: «Малый бизнес» и «Бизнес». Фактическая совместимость с текущим выпуском платформы подтверждается отдельной матрицей перед публикацией.