# Дополнительные товары в popup Tilda Store

Инструкция для файла:

```text
tilda-product-addons-PUBLIC-t123.html
```

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

Файл автономен: конфигурация, стили и JavaScript находятся внутри него.
Сборка, npm, внешний сервер и API-ключи не требуются.

## Установка

### Основной вариант: товары открываются в popup

1. Создайте в Tilda отдельную страницу для общего подвала сайта.
2. Добавьте на нее HTML-блок `T123`.
3. Вставьте в блок содержимое `tilda-product-addons-PUBLIC-t123.html` целиком.
4. Откройте **Настройки сайта → Шапка и подвал** и назначьте эту страницу
   подвалом сайта.
5. Проверьте, что в настройках страниц каталога не включен запрет на
   использование общего подвала.
6. Опубликуйте страницу подвала и заново опубликуйте все страницы каталога.

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

Важно: просто создать и опубликовать отдельную страницу с T123 недостаточно.
Пока эта страница не назначена подвалом, ее код не появится на страницах
каталога и не сможет обработать popup.

### Альтернативный вариант: товар открывается отдельной страницей

1. В настройках магазина включите открытие карточки товара как страницы.
2. Создайте или выберите страницы шапки и подвала для товарных страниц.
3. Добавьте T123 со скриптом в страницу подвала.
4. Назначьте этот подвал товарным страницам в настройках магазина.
5. Опубликуйте подвал и товарные страницы.

Скрипт рассчитан на стандартную разметку карточек Tilda Store. Сильно
измененная разметка Zero Block может потребовать адаптации.

## Обязательная настройка каталогов

В начале HTML-файла находится объект:

```js
window.TILDA_PRODUCT_ADDONS_CONFIG = {
  // ...
};
```

Найдите в нем:

```js
catalogSources: []
```

Добавьте все категории, в которых могут находиться дополнительные товары:

```js
catalogSources: [
  { recId: "1234567890", storePartUid: "111111111111" },
  { recId: "1234567890", storePartUid: "222222222222" }
]
```

Значения выше вымышлены.

### Что такое recId

`recId` — числовой ID блока магазина без префикса `rec`.

Например, если HTML-элемент блока имеет:

```html
id="rec1234567890"
```

в конфиг нужно записать:

```js
recId: "1234567890"
```

Поле `cartRecId` устроено так же, но оно необязательно. Если оставить пустую
строку, скрипт автоматически найдет первую стандартную корзину T706.

### Что такое storePartUid

`storePartUid` — UID категории каталога Tilda Store.

Проще всего найти его прямо в интерфейсе:

1. Откройте каталог товаров.
2. Перейдите в **Разделы**.
3. Откройте нужный раздел.
4. Найдите поле **Адрес раздела**.
5. Скопируйте числовую часть адреса.

Например:

```text
https://example.com/111111111111-aksessuary
```

В конфиг вставляется:

```js
storePartUid: "111111111111"
```

Число в примере вымышлено.

Если дополнения находятся в нескольких категориях, добавьте каждую категорию
один раз. При появлении новой категории достаточно добавить еще один объект в
`catalogSources`.

### Где взять Product ID товара

1. Откройте дополнительный товар в каталоге Tilda.
2. Прокрутите карточку товара вниз.
3. Скопируйте число после подписи **Product ID**.

Product ID — это UID конкретного товара. Его нужно вставлять в характеристику
`Допы`.

### Запасной способ через DevTools

Если нужные значения не видны в интерфейсе, откройте на опубликованной странице
DevTools → Network и найдите запрос `getproductslist`:

- `recid` в параметрах запроса — ID блока каталога;
- `storepartuid` — UID раздела;
- `uid` возле товара в Response — Product ID товара.

## Связь основного товара с дополнениями

В каталоге Tilda откройте основной товар и добавьте характеристику:

```text
Допы
```

В значение внесите UID дополнительных товаров через запятую:

```text
111111111111, 222222222222, 333333333333
```

UID должны принадлежать реальным товарам из подключенных `catalogSources`.
Порядок UID определяет порядок строк в popup.

По умолчанию поддерживаются названия:

```js
addonFieldNames: ["Допы", "addons", "tilda_product_addons"]
```

Список можно изменить, но для русскоязычного магазина рекомендуется оставить
характеристику `Допы`.

## Необязательные настройки

В верхнем конфиге можно изменить:

- `currency` — обозначение валюты;
- `title` — заголовок блока;
- `subtitle` — пояснение под заголовком;
- `themeColor` — акцентный цвет;
- `hideOutOfStock` — скрывать товары с остатком 0;
- `openCartAfterAdd` — открывать корзину после добавления;
- `cartRecId` — явно указать блок корзины;
- `catalogCacheTtlMs` — срок кеширования каталогов.

Технические параметры загрузки обычно менять не требуется.

## Fallback rules и products

`rules` позволяет временно задать связи прямо в конфиге:

```js
rules: {
  "UID_ОСНОВНОГО_ТОВАРА": ["UID_ДОПА_1", "UID_ДОПА_2"]
}
```

Если характеристика `Допы` заполнена, она имеет приоритет над `rules`.

`products` — аварийный кеш сведений о дополнительных товарах. Не добавляйте
туда весь каталог вручную. В обычной установке данные должны загружаться из
`catalogSources`.

## Диагностика

1. Откройте опубликованную страницу с параметром:

```text
?tilda_product_addons_debug=1
```

2. Откройте popup проблемного товара.
3. Выполните в консоли браузера:

```js
TILDA_PRODUCT_ADDONS_DIAG()
```

Полезные поля:

- `currentPopupUid` — UID открытого товара;
- `addonUids` — UID, прочитанные из характеристики;
- `missingAddonUids` — товары, не найденные в каталогах;
- `addonSource` — источник списка дополнений;
- `catalogSources` — используемые каталоги;
- `catalogsLoaded` — завершилась ли загрузка;
- `catalogsLoading` — идет ли загрузка сейчас;
- `lastCatalogLoadError` — последняя ошибка API;
- `lastCatalogProductCount` — количество загруженных товаров;
- `cartFound` — найдена ли корзина.

Каталоги кешируются в `sessionStorage`. Для чистой проверки закройте вкладку
или очистите данные сайта в браузере.

## Публичный API

```js
TILDA_PRODUCT_ADDONS_CONFIG
TILDA_PRODUCT_ADDONS_DIAG()
```

CSS-классы и data-атрибуты имеют префикс `tilda-product-`, чтобы уменьшить риск
конфликтов со стилями сайта и другими модификациями.

## Ограничения

- Требуется стандартная корзина и карточки Tilda Store.
- Сильно измененная разметка Zero Block может потребовать адаптации.
- Проверять работу нужно на опубликованной странице, а не только в редакторе.
- Скрипт зависит от внутренних классов и функций Tilda Store, поэтому после
  крупных обновлений платформы может потребоваться обновление.
- Данные товаров читаются через публичный endpoint Tilda Store.
- Скрипт не отправляет данные на сторонний сервер и не хранит секреты.