# Шаблоны плагина

## Где живут файлы

Все исходные шаблоны плагина находятся в `plugins/shop/templates/`:

```
plugins/shop/templates/
├── front/
│   ├── index.tpl       — витрина (/shop)
│   ├── product.tpl     — карточка товара (/shop/product/{slug})
│   ├── cart.tpl        — корзина (/cart) — клиентская, на localStorage
│   ├── checkout.tpl    — форма оформления (/checkout)
│   └── thanks.tpl      — страница «спасибо» (/checkout/thanks/{number})
├── admin/
│   ├── products_index.tpl       — список товаров с фильтрами и табами
│   ├── products_form.tpl        — форма товара (6 вкладок)
│   ├── products_export.tpl      — форма экспорта XLSX/CSV
│   ├── orders_index.tpl         — список заказов
│   ├── orders_show.tpl          — карточка заказа
│   ├── orders_create.tpl        — ручное создание заказа с автокомплитом
│   ├── customers_index.tpl      — список клиентов
│   ├── customers_show.tpl       — профиль клиента + история заказов
│   ├── manufacturers_index.tpl  — производители
│   ├── manufacturers_form.tpl
│   ├── attributes_index.tpl     — атрибуты товара
│   ├── attributes_form.tpl      — визуальный конструктор атрибута
│   ├── promocodes_index.tpl
│   ├── promocodes_form.tpl
│   ├── shipping_index.tpl       — способы доставки
│   ├── shipping_form.tpl
│   ├── payments_index.tpl       — способы оплаты
│   ├── payments_form.tpl
│   ├── reviews_index.tpl        — модерация отзывов
│   ├── analytics_index.tpl      — аналитика магазина
│   ├── csv_import.tpl           — импорт каталога
│   ├── settings.tpl             — настройки магазина
│   └── dashboard_widget.tpl     — виджет «Витрина магазина» на главном дашборде
└── async/
    └── cart_widget.tpl          — виджет корзины в шапке темы
```

## Как переопределить шаблон в своей теме

Не правьте файлы внутри `plugins/shop/templates/` — они потеряются при обновлении плагина. Вместо этого скопируйте нужный шаблон в активную тему:

```
plugins/shop/templates/front/product.tpl
        ↓ копировать в ↓
templates/<active_theme>/plugins/shop/front/product.tpl
```

`Engine::resolve()` сначала ищет файл в активной теме, потом в `default`-теме, и только потом в самом плагине. Поэтому ваш файл-оверрайд **перебивает** оригинал автоматически.

### Пример: своя обёртка карточки товара

1. Создаём `templates/<theme>/plugins/shop/front/product.tpl`.
2. Копируем содержимое из `plugins/shop/templates/front/product.tpl`.
3. Меняем разметку — например, добавляем блок «Похожие товары».
4. Файл плагина не трогаем.

После обновления плагина (например, выйдет shop 1.2) — ваша версия продолжит работать.

## Доступные переменные в front-шаблонах

### `front/index.tpl`

- `{products}` — массив товаров (id, slug, title, price, price_fmt, cover, …).
- `{categories}` — массив категорий товаров.
- `{current_category}` — выбранная категория или null.
- `{search}` — текущая поисковая строка.
- `{pagination}` — `total`, `page`, `last_page`, `links`.

### `front/product.tpl`

- `{product}` — товар: id, slug, title, short, body, price, price_fmt, old_price_fmt, sku, stock, cover, images, options (JSON опций), variations (JSON вариаций), rating_avg, rating_count, views.
- `{category}` — категория товара (если есть).
- `{custom_fields}` — массив доп. полей сущности `shop_product`.
- `{attributes}` — массив атрибутов с их значениями.
- `{specs}` — извлечённые «Характеристики» для блока на странице товара.

### `async/cart_widget.tpl`

Без переменных — это пустая «болванка», JS наполняет её данными из localStorage. Чтобы изменить разметку — скопируйте в тему и поменяйте структуру; главное оставить элемент с атрибутом `data-cart-widget`, который ждёт JS-загрузчик.

## Доступные inline-теги в любых шаблонах

| Тег | Пример | Что делает |
|---|---|---|
| `{price amount="1234.5"}` | `{price amount="{p.price}"}` | Форматирует число по настройкам валюты |
| `{currency}` | `{currency}` | Символ валюты ($, €, ₴…) |
| `{lang key="shop.cart"}` | в любом тексте | Перевод по ключу из `languages/*.json` |
| `{icon name="cart" size="20"}` | в кнопке | SVG-иконка из ядерного набора |

## Подсказки

- **Размеры изображений.** Для миниатюр используйте `{product.cover|thumb}` (320 px), для среднего — `|medium` (800 px), для большого — `|large` (1600 px). Создаются автоматически при загрузке.
- **Цена с символом валюты.** Не складывайте строки руками — есть тег `{price amount="…"}`, который правильно форматирует число и символ. Хардкод `₴`, `$` в шаблонах больше не используется.
- **Async-блоки.** Виджет корзины — пример async-блока. Если хотите блок «топ-5 товаров на главной», зарегистрируйте свой блок через `BlockRegistry::register('top_products', …)` и вставьте `{async block="top_products"}` в `templates/<theme>/home.tpl`.
- **Перевод внутри `<script>`.** Inline-теги `{lang ...}`, `{price ...}` работают и внутри JS-блоков (специальная обработка в Compiler). CSS-селекторы `[data-x]` не интерпретируются как блочные теги — это безопасно.
- **JS-форматтер цены в темах.** В голову страницы инжектится `window.CELENA_SHOP = { symbol, position, decimals, thousands, decimal }`. JS темы может форматировать цены через `window.CelenaShop.price(amount)` без хардкода символов.
