# Опросы

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

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

## Вставка и адреса

```text
[mod_poll:8]
```

Число после двоеточия — ID опроса. Тег возвращает пустую строку для неверного
ID. Публичный архив по умолчанию доступен на `/polls`, отдельный опрос — на
`/polls/8`; базовый URL меняется в настройках и резервируется модулем.

## Шаблон опроса

| Тег | Значение |
| --- | --- |
| `[tag:id]` | ID опроса. |
| `[tag:title]` | Экранированный вопрос или заголовок. |
| `[tag:description]` | Готовый блок описания либо пустая строка. |
| `[tag:options]` | Варианты для формы голосования. |
| `[tag:results]` | Собранные строки результатов. |
| `[tag:protection]` | Поля антиспама, когда голосование доступно. |
| `[tag:notice]` | Состояние: не началось, завершено или голос уже учтён. |
| `[tag:ballots]` | Число бюллетеней, если показ результатов разрешён. |
| `[tag:max_choices]` | Максимум вариантов для множественного опроса. |

## Шаблон варианта

| Тег | Значение |
| --- | --- |
| `[tag:id]` | ID варианта. |
| `[tag:title]` | Подпись варианта. |
| `[tag:input_type]` | `radio` для одиночного и `checkbox` для множественного режима. |
| `[tag:checked]` | Атрибут ` checked` для выбора текущего посетителя. |

## Шаблон результата

| Тег | Значение |
| --- | --- |
| `[tag:id]` | ID варианта. |
| `[tag:title]` | Подпись варианта. |
| `[tag:votes]` | Число голосов за вариант. |
| `[tag:percent]` | Доля в процентах с одним знаком после точки. |
| `[tag:color]` | Настроенный цвет полосы результата. |

## Шаблон архива

`[tag:items]` содержит карточки опросов, `[tag:pagination]` — страницы архива,
`[tag:total]` — общее число опубликованных опросов.

Штатный JavaScript ожидает `data-poll-form`, `data-poll-results`,
`data-poll-result-list` и `data-poll-status`. Их можно переставлять, но не
удалять, если нужны Ajax-голосование и переключение результатов.

## API и hooks

```text
GET  /api/v1/polls/8
POST /api/v1/polls/8/vote
```

Голосование принимает массив `options[]` и CSRF. Сервер проверяет расписание,
режим, максимум вариантов, право изменить голос и политику показа результатов.
Ответ возвращает агрегаты и обновлённый HTML виджета.

Антиспам и rate limit выполняются независимо. Даже успешно обработанный профиль
`polls` не отключает лимиты actor и сетевого префикса; закрытый, отложенный или
несуществующий опрос не может получить новую внутреннюю interaction-цель.

`polls.voted` вызывается после сохранения бюллетеня и получает poll, выбранные
options, actor и результат interaction. `polls.rendering` может изменить
готовый HTML.