Polls¶

Установка¶

Установить плагин Polls можно одним из трёх способов: метод установки через GPM (менеджер пакетов Grav) позволяет быстро установить плагин простой командой в терминале, ручной метод — из zip-архива, а метод через админку — с помощью плагина Admin.

Зависимости¶

Для работы плагину требуются следующие установленные и включённые плагины:

• Admin Plugin >= 1.10.0 — для интерфейса управления опросами
• Flex Objects >= 1.0.0 — для управления данными
• Database Plugin >= 1.0.0 — для хранения голосов (используется SQLite)
• Shortcode Core >= 5.0.0 — для встраивания опросов в контент

Установка через GPM (предпочтительно)¶

Чтобы установить плагин через GPM, откройте терминал системы (также называемый командной строкой), перейдите в корень установки Grav и введите:

bin/gpm install polls

Плагин Polls будет установлен в папку /user/plugins внутри Grav. Его файлы можно найти в /your/site/grav/user/plugins/polls.

Установка вручную¶

Чтобы установить плагин вручную, скачайте zip-версию этого репозитория и распакуйте её в /your/site/grav/user/plugins. Затем переименуйте папку в polls. Эти файлы можно найти на GitHub.

Теперь все файлы плагина должны находиться в

/your/site/grav/user/plugins/polls

Плагин Admin¶

Если вы используете плагин Admin, плагин можно установить напрямую: откройте меню Plugins и нажмите кнопку Add.

Конфигурация¶

Перед настройкой плагина скопируйте user/plugins/polls/polls.yaml в user/config/plugins/polls.yaml и редактируйте только эту копию.

Ниже приведена конфигурация по умолчанию и описание доступных параметров:

enabled: true                    # Включить плагин
built_in_css: true              # Использовать встроенные стили CSS
theme: default                  # Тема: 'default' или 'modern'
unique_ip_check: true           # Один голос на IP-адрес
session_vote_check: true        # Один голос на сессию
readonly: false                 # Показывать только результаты (без голосования)
callback: /polls                # AJAX-эндпоинт для голосования
poll_template: partials/poll.html.twig      # Шаблон опроса
results_template: partials/results.html.twig # Шаблон результатов
colors: |                       # Пользовательские переменные CSS
  --poll-primary: #1a73e8;
  --poll-secondary: #f8f9fa;
  --poll-border: #dadce0;
  --poll-text: #202124;
  --poll-hover: #e8f0fe;

Учтите: если вы используете плагин Admin, после сохранения конфигурации в админке файл с вашей конфигурацией polls.yaml будет сохранён в папке user/config/plugins/.

Создание опросов¶

1. Перейдите в Admin > Polls в админке Grav
2. Нажмите Добавить, чтобы создать новый опрос
3. Заполните обязательные поля:
4. Заголовок: внутренний идентификатор опроса (используется в шорткодах)
5. Вопрос: вопрос, отображаемый пользователям
6. Ответы: добавьте несколько вариантов ответа (нажимайте «Add item» для каждого ответа)
7. Опубликовано: переключатель для включения и отключения опроса

Расширенные параметры¶

• Минимум ответов: минимальное количество обязательных выборов (по умолчанию: 1)
• Максимум ответов: максимальное количество допустимых выборов (по умолчанию: 1)
• Показывать подсказки: показывать пользователям требования к выбору

Использование¶

Базовое встраивание опроса¶

Используйте шорткод [poll], чтобы встроить опрос в контент:

[poll id="my-poll-id" /]

Параметры шорткода¶

Примеры¶

Опрос с одним выбором¶

[poll id="newsletter-signup" theme="modern" /]

Опрос с несколькими вариантами¶

Настройте опрос так, чтобы разрешить несколько выборов в админке, затем встройте его:

[poll id="favorite-features" /]

Только показ результатов¶

[poll id="survey-2023" readonly="true" /]

Пользовательская конфигурация¶

[poll id="feedback" theme="modern" unique_ip_check="false" session_vote_check="true" /]

Настройка шаблонов¶

Переопределение шаблонов¶

Чтобы настроить внешний вид опроса, скопируйте файлы шаблонов в свою тему:

1. Скопируйте из: user/plugins/polls/templates/partials/
2. Вставьте в: user/themes/YOUR_THEME/templates/partials/

Доступные шаблоны: - poll.html.twig — основной шаблон отображения опроса - results.html.twig — шаблон отображения результатов

Переменные шаблона¶

poll.html.twig - poll — объект опроса (id, question, answers) - options — параметры конфигурации - polls — экземпляр PollsManager - uri — URL AJAX-колбэка с nonce

results.html.twig - poll — объект опроса - results — результаты голосования по ответам - total_votes — общее количество голосов - options — параметры конфигурации

Пример пользовательского шаблона¶

{# user/themes/YOUR_THEME/templates/partials/poll.html.twig #}
<div class="custom-poll" data-poll-id="{{ poll.id }}">
    <h3>{{ poll.question|markdown(false) }}</h3>

    <form class="pollform">
        <input type="hidden" name="id" value="{{ poll.id }}" />

        {% for answer in poll.answers %}
            <label>
                <input type="checkbox" value="{{ answer }}" />
                <span>{{ answer|markdown(false) }}</span>
            </label>
        {% endfor %}

        <button type="submit">{{ "PLUGIN_POLLS.VOTE"|t }}</button>
    </form>
</div>

Настройка CSS¶

Переменные CSS¶

Настройте внешний вид с помощью переменных CSS в теме или в конфигурации плагина:

:root {
    --poll-primary: #1a73e8;      /* Основной цвет */
    --poll-secondary: #f8f9fa;    /* Цвет фона */
    --poll-border: #dadce0;       /* Цвет границы */
    --poll-text: #202124;         /* Цвет текста */
    --poll-hover: #e8f0fe;        /* Цвет при наведении */
    --poll-success: #34a853;      /* Цвет сообщения об успехе */
    --poll-error: #ea4335;        /* Цвет сообщения об ошибке */
    --poll-radius: 8px;           /* Радиус границы */
    --poll-transition: 0.3s;      /* Длительность анимации */
}

Отключение встроенного CSS¶

Чтобы использовать полностью собственное оформление:

built_in_css: false

Интеграция с JavaScript¶

Плагин вызывает пользовательские события для расширенной интеграции:

// Перед отправкой голоса
document.addEventListener('polls:beforeVote', function(e) {
    console.log('Voting on poll:', e.detail.pollId);
});

// После успешного голосования
document.addEventListener('polls:voteSuccess', function(e) {
    console.log('Vote recorded:', e.detail);
});

// При ошибке голосования
document.addEventListener('polls:voteError', function(e) {
    console.log('Vote failed:', e.detail.error);
});

Справочник API¶

Для продвинутого использования в PHP:

// Получить конкретный опрос
$poll = $grav['polls']->getPoll('poll-id');

// Получить все опросы
$polls = $grav['polls']->getPolls();

// Получить только опубликованные опросы
$polls = $grav['polls']->getPolls(['published' => true]);

// Получить результаты голосования
$results = $grav['polls']->getResults('poll-id');

// Проверить, голосовал ли пользователь
$hasVoted = $grav['polls']->hasAlreadyVoted('poll-id');

Решение проблем¶

Ошибка «опрос не найден»¶

• Убедитесь, что идентификатор опроса в шорткоде точно совпадает с ID опроса
• Проверьте, что опрос опубликован в админке
• Очистите кэш Grav: bin/grav clear-cache

Голосование не работает¶

• Убедитесь, что все зависимости плагина установлены и включены
• Проверьте консоль браузера на ошибки JavaScript
• Убедитесь, что AJAX-эндпоинт (/polls) доступен
• Проверьте права доступа к файлам user-data://polls/polls.db

Результаты не обновляются¶

• Очистите кэш Grav: bin/grav clear-cache
• Проверьте, что плагин Database настроен правильно
• Убедитесь, что SQLite включён в вашей установке PHP
• Проверьте журналы Grav на ошибки базы данных

Проблемы с оформлением¶

• Убедитесь, что built_in_css включён, или предоставьте собственный CSS
• Проверьте конфликты CSS с вашей темой
• Используйте инструменты разработчика браузера, чтобы изучить переменные CSS

Ошибки прав доступа¶

• Убедитесь, что папка user/data доступна для записи
• Проверьте, что веб-сервер может создавать и изменять базу данных SQLite
• Проверьте правильность владельца файлов установки Grav

Режим отладки¶

Включите режим отладки для подробных сообщений об ошибках:

# user/config/system.yaml
debugger:
  enabled: true