# Баннеры

Модуль создаёт именованные рекламные места и выбирает для каждого публичного
показа один доступный баннер. Изображения не копируются в каталог модуля:
сохраняются ссылки на файлы общей медиатеки.

## Быстрый старт

1. Откройте **Модули → Баннеры → Рекламные места**.
2. Создайте место, например `Шапка сайта`, с кодом `header-main`.
3. Добавьте баннер, выберите изображение, ссылку и это рекламное место.
4. Вставьте тег в документ, блок, рубрику или шаблон:

```text
[mod_banner:header-main]
```

Для совместимости поддерживается ID места и форма `[mod_banners:КОД]`, но
стабильный системный код удобнее: он не меняется при переносе контента между
установками.

## Стратегии выбора

| Стратегия | Поведение |
| --- | --- |
| По весу | Вероятность выбора пропорциональна весу активного баннера. |
| Случайно | Все доступные баннеры имеют одинаковую вероятность. |
| Равномерно | Выбирается баннер с наименьшим общим числом показов. |

До выбора проверяются состояние места и баннера, начало и окончание периода,
лимит показов и лимит кликов. `0` в поле лимита означает «без ограничения».

## Публичные шаблоны

Шаблон рекламного места получает теги:

```text
[tag:category-id] [tag:category-code] [tag:category-title]
[tag:banner-id] [tag:banner]
```

Шаблон баннера получает:

```text
[tag:id] [tag:title] [tag:image] [tag:webp] [tag:picture]
[tag:url] [tag:click-url] [tag:alt] [tag:target]
[tag:width] [tag:height]
```

Для учёта клика ссылка должна использовать `[tag:click-url]`. `[tag:url]`
содержит конечный адрес и предназначен для метаданных или собственного
JavaScript, но прямой переход по нему не увеличивает счётчик.

## API и хуки

`GET /api/v1/banners/{code}` возвращает выбранный HTML в JSON и подходит для
динамической смены баннера без перезагрузки. Ответ не кешируется, а успешный
выбор считается показом.

Фильтр `banners.rendering` получает массив:

```php
array(
	'banner' => $banner,
	'html' => $html,
)
```

Обработчик может изменить `html` и вернуть массив. Не выполняйте повторный
запрос выбора внутри этого hook: показ уже зафиксирован.

## Удаление

Удаление рекламного места каскадно удаляет его баннеры и статистику. Файлы в
`/uploads` и созданные для них миниатюры остаются в медиатеке. Uninstall модуля
удаляет все три таблицы модуля.