# Отзывы

← [Назад к разделу «Модули»](README.md)

Модуль `reviews` хранит отзывы отдельно от комментариев и простых голосов. У
отзыва есть оценка от 1 до 5, заголовок, текст, достоинства, недостатки, признак
подтверждённой покупки и ответ компании. Для работы требуется модуль
[Взаимодействия](interactions.md).

## Вставка отзывов

Для текущего документа:

```text
[mod_reviews]
```

Для конкретного объекта:

```text
[mod_reviews:document:123]
[mod_reviews:poll:8]
[mod_reviews:gallery:4]
```

Формат: `[mod_reviews:ТИП:КЛЮЧ]`. Товары, новости и статьи являются документами,
поэтому для них используется тип `document` и ID документа. Тип должен быть
разрешён настройкой **Где доступны отзывы**. Параметр страницы называется
`reviews_page`.

## Поведение

На вкладке **Настройки** можно:

- разрешить или запретить отзывы гостей;
- потребовать email гостя;
- полностью скрыть форму, оставив опубликованные отзывы;
- включить заголовок, достоинства и недостатки;
- показывать отметку подтверждённой покупки;
- отправлять на модерацию все отзывы, только отзывы гостей или публиковать сразу;
- задать число отзывов на странице, длину текста и лимит отправок в час;
- выбрать допустимые типы объектов;
- изменить шаблоны виджета, одного отзыва и формы.

Непроверенные отзывы находятся на вкладке **Отзывы**. Модератор может
опубликовать или отклонить запись, добавить ответ компании и вручную поставить
отметку подтверждённой покупки. Email автора в публичный шаблон не передаётся.

## Шаблон виджета

| Тег | Значение |
| --- | --- |
| `[tag:count]` | Количество опубликованных отзывов объекта. |
| `[tag:average]` | Средняя оценка с одним знаком после запятой. |
| `[tag:items]` | Готовый список отзывов или сообщение о пустом списке. |
| `[tag:pagination]` | Ссылки на страницы отзывов. |
| `[tag:notice]` | Сообщение о закрытой форме или необходимости войти. |
| `[tag:form]` | Готовая форма либо пустая строка. |

## Шаблон отзыва

| Тег | Значение |
| --- | --- |
| `[tag:id]` | ID отзыва. |
| `[tag:author]` | Экранированное имя автора. |
| `[tag:rating]` | Оценка числом от 1 до 5. |
| `[tag:stars]` | Пять заполненных и пустых символов-звёзд. |
| `[tag:verified]` | Плашка подтверждённой покупки либо пустая строка. |
| `[tag:verified_value]` | Признак подтверждённой покупки: `1` или `0`. |
| `[tag:title]` | Заголовок в готовом `h3` либо пустая строка. |
| `[tag:title_text]` | Экранированный заголовок без HTML-обёртки. |
| `[tag:body]` | Экранированный текст с переносами строк. |
| `[tag:pros]` | Готовый блок достоинств либо пустая строка. |
| `[tag:pros_text]` | Экранированный текст достоинств без обёртки. |
| `[tag:cons]` | Готовый блок недостатков либо пустая строка. |
| `[tag:cons_text]` | Экранированный текст недостатков без обёртки. |
| `[tag:reply]` | Ответ компании либо пустая строка. |
| `[tag:reply_text]` | Экранированный текст ответа без внешней обёртки. |
| `[tag:date]` | Дата в формате `дд.мм.ГГГГ`. |
| `[tag:datetime]` | ISO-дата для атрибута `datetime`. |

## Шаблон формы

| Тег | Значение |
| --- | --- |
| `[tag:csrf]` | Скрытое поле CSRF. |
| `[tag:guest_fields]` | Имя и email для неавторизованного посетителя. |
| `[tag:title_field]` | Поле заголовка, если оно включено. |
| `[tag:pros_cons_fields]` | Поля достоинств и недостатков, если они включены. |
| `[tag:protection]` | Поля активного профиля антиспама `reviews`. |
| `[tag:min_length]` | Минимальная длина текста. |
| `[tag:max_length]` | Максимальная длина текста. |

Для штатной отправки форма должна содержать `data-review-form`, поле
`rating`, `textarea[name=body]`, кнопку `type=submit` и элемент
`data-review-status`. Внешний контейнер с адресом API, CSRF и публичные assets
модуль добавляет автоматически.

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

```text
GET  /api/v1/reviews/document/123?page=1
POST /api/v1/reviews/document/123
```

`GET` возвращает опубликованные отзывы, пагинацию и агрегат рейтинга. `POST`
принимает `rating`, `body`, необязательные `title`, `pros`, `cons`, а для гостя
`name` и `email`. CSRF передаётся полем `_csrf` или заголовком
`X-CSRF-Token`. Ответ сообщает статус `published` или `pending`.

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

## Хуки

| Хук | Контекст |
| --- | --- |
| `reviews.creating` | Массив `allowed`, `status`, `rating`, `title`, `body`, `pros`, `cons`, `target_type`, `target_key`; можно отклонить или скорректировать запись. |
| `reviews.created` | Полная сохранённая запись отзыва. |
| `reviews.rendering` | Массив `target_type`, `target_key`, `data`, `settings`, `html`; позволяет заменить итоговый HTML. |

Шаблоны не выполняют PHP. Для проектной логики используйте хуки, а для
оформления — классы в шаблонах и CSS темы сайта.