Это руководство объясняет, как с помощью JavaScript встроить и отобразить список тем Discourse на внешних сайтах, что позволит вам демонстрировать контент форума (например, обсуждения или объявления) на блогах, веб-сайтах или внешних платформах.
Требуемый уровень пользователя: Администратор
Краткое описание
Встраивание тем Discourse на внешние сайты позволяет отображать списки тем из вашего форума Discourse непосредственно на других ресурсах. Эта интеграция помогает привлекать трафик на ваш форум и удерживает аудиторию, вовлекая её в контент сообщества. Встроенные темы отображаются в виде виджета на JavaScript, который интегрируется в структуру DOM вашего сайта, что упрощает кастомизацию с помощью CSS.
Включение встраивания тем
Для настройки встраивания тем на вашем внешнем сайте:
- Перейдите в раздел Администрирование > Дополнительно > Встраивание и переключитесь на вкладку Настройки. Включите настройку сайта
embed_topics_list.
- Добавьте скрипт встраивания в секцию
<head>HTML-кода вашего внешнего сайта:
<script src="https://discourse.example.com/javascripts/embed-topics.js"></script>
Замените discourse.example.com на реальный URL вашего форума Discourse.
- Разместите элемент списка тем в том месте, где вы хотите отображать темы (например, в записи блога или на отдельной странице сайта):
<d-topics-list discourse-url="https://discourse.example.com" category="1234" per-page="5"></d-topics-list>
- Если вы встраиваете темы на домен, отличный от домена вашего сайта Discourse, добавьте домен вашего внешнего сайта в раздел Администрирование > Дополнительно > Встраивание > Хосты.
Например, если ваш сайт Discourse находится по адресу yourdiscourseforum.com, а вы хотите встроить темы на yourexternalsite.com, вам нужно добавить yourexternalsite.com в список разрешённых хостов.
Вы не можете встраивать темы с частного сайта Discourse, требующего входа в систему.
Параметры конфигурации
Элемент d-topics-list поддерживает следующие атрибуты для настройки отображения тем:
discourse-url— URL вашего сайта Discourse (обязательно)template— Варианты стиля отображения:basic(по умолчанию) — Отображает заголовки тем в виде ссылокcomplete— Отображает заголовок, имя пользователя, аватар, дату создания, время последнего ответа, количество лайков, количество ответов и главное изображение/миниатюру
per-page— Количество тем для отображения (ограничено скрытой настройкой сайтаembed_topic_limit_per_page, по умолчанию 200)category— ID категории для фильтрации тем из конкретной категорииtags— Фильтрация тем по конкретным тегамallow-create— При значенииtrueотображается кнопка «Новая тема»embed-class— Добавляет пользовательский CSS-класс к контейнеру встроенного списка тем (допустимы только буквы, цифры, дефисы и нижние подчёркивания)top-period— Показывает лучшие темы за определённый период:allyearlyquarterlymonthlyweeklydaily
Вы можете комбинировать несколько параметров для уточнения отображения списка тем. Например:
<d-topics-list
discourse-url="https://discourse.example.com"
category="5"
tags="announcements"
per-page="10"
template="complete">
</d-topics-list>
Настройка внешнего вида
Вы можете стилизовать встроенные темы с помощью пользовательского SCSS в панели Администрирование > Внешний вид > Темы и компоненты. Нажмите на вашу текущую или стандартную тему и выберите Редактировать код. Затем выберите опцию Show_advanced и нажмите Встроенный CSS, чтобы добавить свой код:
Вот пример SCSS для создания сеточной раскладки:
.topics-list {
display: grid;
grid-template-columns: repeat(2, 1fr);
.topic-list-item {
.main-link {
border: 1px dotted gray;
padding: 0;
}
.topic-column-wrapper {
flex-direction: column-reverse;
.topic-column.details-column {
width: 100%;
}
.topic-column.featured-image-column .topic-featured-image img {
max-width: initial;
max-height: initial;
width: 100%;
}
}
}
}
Рекомендации по использованию
- Используйте осмысленные фильтры по категориям и тегам для отображения релевантного контента для вашей аудитории
- Устанавливайте подходящее значение
per-page, чтобы не перегружать посетителей - Тестируйте встроенные темы на экранах разных размеров, чтобы обеспечить адаптивный дизайн
- Рассмотрите возможность использования шаблона
completeдля более привлекательного визуального оформления, если позволяет место - Регулярно проверяйте список разрешённых хостов, чтобы убедиться, что только авторизованные домены могут встраивать ваши темы
Распространённые проблемы и решения
Темы не отображаются на внешнем домене
Проблема: Встроенные темы отображаются как пустой или серый блок при просмотре с внешнего домена.
Решение: Добавьте внешний домен в раздел Администрирование > Дополнительно > Встраивание > Хосты вашего сайта Discourse. Убедитесь, что указан правильный поддомен (например, если ваш сайт использует www.example.com, добавьте www.example.com, а не только example.com).
Ошибки загрузки скрипта
Проблема: Скрипт встраивания не загружается или возвращает ошибки соединения.
Решение:
- Проверьте правильность и доступность URL сайта Discourse в источнике скрипта
- Убедитесь, что включена настройка сайта
embed_topics_list - Проверьте, что ваш сайт Discourse не требует входа для доступа к публичным темам
Поведение в контексте SameSite
В контекстах SameSite, когда сайт встраивания и форум имеют общий родительский домен, Discourse учитывает статус входа в систему и отображает результаты соответствующим образом. Пользователи, вошедшие в систему, могут видеть контент из защищённых категорий, недоступный анонимным пользователям.
Часто задаваемые вопросы
В: Могу ли я встроить темы с частного сайта Discourse?
О: Нет, встраивание тем работает только с публичными сайтами Discourse. Частные сайты, требующие входа, встроить нельзя.
В: Могу ли я встроить несколько списков тем на одной странице?
О: Да, вы можете добавить несколько элементов <d-topics-list> на одной странице с разными параметрами для отображения различных коллекций тем.
В: Как встроить темы с главными изображениями?
О: Используйте параметр template="complete" в элементе <d-topics-list>, чтобы отображать темы с миниатюрами и главными изображениями.
В: Могу ли я изменить место, где открываются ссылки на темы?
О: По умолчанию ссылки на темы открываются в родительском окне. Вы можете изменить это поведение с помощью кастомизации CSS или JavaScript.
