Оформление¶

Forum Pro по замыслу не зависит от темы. Каждый цвет, радиус, шрифт и тень определяются через цепочку пользовательских свойств, поэтому тема, публикующая токены дизайна, получает форум, выглядящий как часть сайта, вообще без работы над форумом.

Цепочка токенов¶

--forum-*  (переопределение сайта)  →  --grav-*  (дизайн-система темы)  →  --theme-accent  →  нейтральный запасной вариант

Читайте слева направо: свойство --forum-*, заданное вами, всегда побеждает; если его нет, используется токен темы --grav-*; если нет и его — акцентный цвет темы; если нет и его — доступный нейтральный вариант по умолчанию.

На практике это значит:

Темы, публикующие токены дизайна --grav-*, автоматически получают подходящую типографику, карточки, кнопки, чипы и метки. Настраивать ничего не нужно.
Остальные темы получают нейтральное оформление с проверенным контрастом в светлой и тёмной схемах. Оно выглядит намеренным, а не сломанным.
Всё, что нужно настроить отдельно, находится на расстоянии одного пользовательского свойства --forum-*.

Акцентный цвет форума¶

Теме или плагину, которые хотят, чтобы форум соответствовал фирменному цвету, достаточно опубликовать одно свойство:

:root { --theme-accent: #8428df; }

Это вся интеграция. Специальных знаний о форуме не требуется.

--forum-accent всё равно побеждает --theme-accent, поэтому сайт может переопределить выбор темы:

:root { --forum-accent: #0ebcf3; }

Если не задано ни то, ни другое, форум использует собственный синий.

Текст на акцентном фоне¶

Метки, расположенные на залитом акцентном фоне (счётчики, всплывающие уведомления, основные кнопки), автоматически выбирают чёрный или белый цвет в зависимости от светлоты акцента, поэтому бледный фирменный цвет не получит белый текст, который невозможно прочитать. При желании выбор можно закрепить:

:root {
  --forum-on-accent: #000;
  --forum-on-accent-2: #fff;
}

Тёмный режим¶

Некоторым поверхностям нужен сплошной цвет, совпадающий со страницей: выпадающим спискам, всплывающим панелям и диалогам. Forum Pro использует для них системный цвет Canvas, который следует используемой схеме color-scheme, а не тому режиму, который в данный момент рисует тема.

Темы, переключающие тёмный режим любым из следующих способов, распознаются и обрабатываются автоматически:

data-theme="dark"
data-bs-theme="dark"
класс dark на <html> или <body>

Если ваша тема сообщает о тёмном режиме иначе, есть два варианта:

Задайте color-scheme на странице. Это стоит сделать в любом случае, поскольку также исправляет нативные элементы форм и полосы прокрутки:

:root { color-scheme: dark; }

Явно задайте два базовых свойства:

:root {
  --forum-bg: #12141a;
  --forum-fg: #e6e9ef;
}

Значки¶

Каждый значок, состояние и действие используют встроенные SVG Lucide, наследующие currentColor, поэтому они перекрашиваются вместе с окружающим текстом в обеих схемах. Нет шрифтов со значками и эмодзи, которые выглядят по-разному на каждой платформе.

Разделы и категории могут иметь собственный значок, выбранный в Admin → Forum → Structure.

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

Шаблоны Twig Forum Pro следуют обычным правилам переопределения Grav. Скопируйте нужный шаблон из user/plugins/forum-pro/templates/ в папку templates/ вашей темы и редактируйте там. Ваша копия имеет приоритет.

Основные шаблоны:

Шаблон	Что отображает
`forum-index.html.twig`	Главную страницу форума
`forum-category.html.twig`	Категорию
`forum-topiclist.html.twig`	Режимы списков: недавние, непрочитанные, без ответа и другие
`forum-topic.html.twig`	Тему
`forum-profile.html.twig`	Профиль участника
`forum-members.html.twig`	Список участников
`forum-search.html.twig`	Поиск
`forum-queue.html.twig`	Очередь проверки модераторов
`forum-pm-inbox.html.twig` / `forum-pm-thread.html.twig`	Личные сообщения
`forum-notifications.html.twig`	Уведомления
`forum-settings.html.twig`	Настройки участника
`forum-login.html.twig` / `forum-register.html.twig` / `forum-reset.html.twig`	Процессы учётной записи

Примечание

Переопределяя шаблон, вы берёте на себя ответственность за него. Делайте минимальное переопределение, достаточное для задачи, потому что полная копия будет расходиться с плагином по мере его обновления.

По возможности предпочитайте пользовательские свойства переопределению шаблонов. Большинство визуальных изменений, ради которых люди берутся за шаблон, достигаются свойством --forum-*.

Расширение отображения сообщений¶

Каждый текст, который отображает форум, проходит через один парсер Markdown, а затем санитайзер: сообщения, личные сообщения, подписи, объявления и фрагмент в письме-уведомлении. Плагин может участвовать в этом через два хука.

onMarkdownInitialized — собственное событие Grav, возникающее при создании парсера форума, поэтому плагин может зарегистрировать блочные или строчные обработчики так же, как для контента страниц. Текстам форума передаётся page со значением null.

onForumProRenderBody — событие Forum Pro. Оно возникает после разбора и до санитайзера с тремя значениями:

Ключ	Содержимое
`markdown`	Исходный текст в том виде, в каком его написал участник. Его можно читать; изменение здесь ни на что не влияет.
`html`	Разобранный текст. Замените его, и именно замена будет очищена и сохранена.
`context`	Что отображается: `kind` (`post`, `message`, `signature`, `announcement` или `email_excerpt`) плюс известные вызывающему идентификаторы (`post_id`, `topic_id`, `category_id`, `user_id`, `message_id`, `announcement_id`). При импорте добавляется `import: xenforo` или `discourse`.

Санитайзер всё равно обрабатывает то, что вернул слушатель, поэтому его белый список действует: абзацы, списки, заголовки, таблицы, код, ссылки и изображения сохраняются; пользовательские классы, встроенные стили и скрипты — нет. Слушатель может изменить форму сообщения, но не протащить разметку в обход форума.

Плагин, превращающий блок Key: Value в начале сообщения в таблицу:

public static function getSubscribedEvents(): array
{
    return ['onForumProRenderBody' => ['onForumProRenderBody', 0]];
}

public function onForumProRenderBody(Event $event): void
{
    if (($event['context']['kind'] ?? '') !== 'post') {
        return;
    }

    $event['html'] = preg_replace_callback(
        '~<pre><code>((?:[A-Z][\w ]+: .*\n?)+)</code></pre>~',
        static function (array $m): string {
            $rows = '';
            foreach (explode("\n", trim($m[1])) as $line) {
                [$key, $value] = array_pad(explode(':', $line, 2), 2, '');
                $rows .= '<tr><th>' . htmlspecialchars(trim($key)) . '</th><td>' . htmlspecialchars(trim($value)) . '</td></tr>';
            }

            return '<table>' . $rows . '</table>';
        },
        $event['html']
    );
}

Отрендеренный HTML хранится вместе с каждым сообщением, поэтому новый слушатель применяется к сообщениям, написанным с этого момента. Запустите rerender, чтобы применить его к существующим, а затем reindex, чтобы поиск видел тот же текст.

Доступность¶

Фокус перемещается на новый контент после навигации внутри страницы и живых вставок, поэтому скринридеры сообщают, куда попал читатель, а не оставляют его в начале устаревшей страницы.
Кнопки только со значком имеют доступные имена.
Редактор, его панель инструментов и панель обновлений в реальном времени имеют метки и озвучиваются.
Цветовые решения проверяются на контраст в светлой и тёмной схемах, если тема не предоставляет свои.

SEO¶

Серверный рендеринг. Весь форум работает с отключённым JavaScript. Обновления в реальном времени и редактор — прогрессивные улучшения, поэтому поисковый робот видит полный контент.
Канонические URL. Адреса тем канонизируются по id. Несовпадение слага, устаревшая категория в пути или переименованная категория — всё это 301-редирект на правильный адрес, поэтому ссылки не гниют, а поисковые системы индексируют только один URL на тему.
Заголовки браузера для каждой страницы, которые следуют за навигацией внутри страницы.
Цепочки навигации обратно к корню форума на каждой странице.
noindex для временных и скрытых профилей, что не пускает профили спам-регистраций в индекс.

Переводы¶

Весь текст, видимый посетителям, переводится через папку languages/ плагина по стандартному механизму переводов Grav. О том, как Grav находит языковые файлы, см. в разделе Многоязычность.