# Комментарии

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

Модуль `comments` предоставляет древовидные обсуждения, премодерацию, ответы,
редактирование владельцем и оценку комментариев. Для голосов нужен модуль
[Взаимодействия](interactions.md), защита гостевой формы подключается через
[Антиспам](antispam.md).

## Вставка обсуждения

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

```text
[mod_comments]
```

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

```text
[mod_comments:document:145]
[mod_comments:poll:8]
```

Формат: `[mod_comments:ТИП:КЛЮЧ]`. Тип должен быть разрешён настройкой
**Типы объектов**. Параметр страницы комментариев называется `comments_page`.
Пагинация применяется к корневым веткам: выбранная страница получает корневой
комментарий вместе со всеми его ответами, а ответы соседних страниц из БД не
загружаются.

## Шаблон списка

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

## Шаблон комментария

| Тег | Значение |
| --- | --- |
| `[tag:id]` | ID комментария. |
| `[tag:parent_id]` | ID родителя, `0` для корневой записи. |
| `[tag:depth]` | Глубина ветки, начиная с `0`. |
| `[tag:author]` | Экранированное имя автора. |
| `[tag:body]` | Подготовленный безопасный HTML текста. |
| `[tag:date]` | Дата `дд.мм.ГГГГ ЧЧ:ММ`. |
| `[tag:datetime]` | ISO-дата для атрибута `datetime`. |
| `[tag:status]` | Плашка премодерации либо пустая строка. |
| `[tag:reply]` | Кнопка ответа, если разрешена глубина. |
| `[tag:votes]` | Кнопки «за/против» и текущий счёт. |
| `[tag:edit]` | Кнопка изменения в разрешённый временной интервал. |
| `[tag:delete]` | Кнопка удаления владельцем. |
| `[tag:children]` | Уже собранные дочерние комментарии. |

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

| Тег | Значение |
| --- | --- |
| `[tag:guest_fields]` | Имя и email для неавторизованного посетителя. |
| `[tag:protection]` | Поля активного профиля антиспама `comments`. |
| `[tag:min_length]` | Минимальная длина текста. |
| `[tag:max_length]` | Максимальная длина текста. |

Форма должна сохранять `textarea[name=body]`, скрытый `parent_id`, элементы
`data-comment-form`, `data-comment-cancel` и место статуса
`data-comment-form-status`, если используется штатный JavaScript.

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

```text
GET  /api/v1/comments/document/145?page=1
POST /api/v1/comments/document/145
POST /api/v1/comments/37/edit
POST /api/v1/comments/37/delete
```

Создание принимает `body`, `parent_id`, а для гостя `author_name` и
`author_email`; CSRF передаётся полем `_csrf` или заголовком `X-CSRF-Token`.
Ответ сообщает статус `published` или `pending`.

Создать обсуждение для отсутствующего или удалённого объекта нельзя. Антиспам
проверяет содержимое формы, но не заменяет ограничение частоты: для гостя всегда
действуют отдельные лимиты по actor cookie и HMAC-префиксу сети/цели. Поэтому
смена cookie не создаёт неограниченный поток комментариев.

Настройка премодерации имеет режимы: без модерации, только гости, все. При
удалении документа его обсуждение закрывается. Hooks `comments.creating`,
`created`, `published`, `updated`, `deleted` и `rendering` позволяют подключать
уведомления, внешнюю модерацию и проектный HTML.