이 가이드는 JavaScript를 사용하여 외부 웹사이트에 Discourse 주제 목록을 임베드하고 표시하는 방법을 설명합니다. 이를 통해 블로그, 웹사이트 또는 외부 콘텐츠 플랫폼에 토론이나 공지 사항과 같은 포럼 콘텐츠를 보여줄 수 있습니다.
필요한 사용자 권한: 관리자
요약
외부 웹사이트에 Discourse 주제를 임베드하면 Discourse 포럼의 주제 목록을 다른 사이트에 직접 표시할 수 있습니다. 이 통합은 포럼으로의 트래픽을 유도하고 청중이 커뮤니티 콘텐츠와 지속적으로 상호작용하도록 돕습니다. 임베드된 주제는 웹사이트의 DOM 구조와 통합되는 JavaScript 위젯으로 나타나며, 이를 통해 CSS를 사용하여 쉽게 사용자 정의할 수 있습니다.
주제 임베드 활성화
외부 사이트에서 주제 임베드를 설정하려면:
- 관리자 > 고급 > 임베딩으로 이동하여 설정 탭으로 전환합니다.
embed_topics_list사이트 설정을 활성화합니다.
- 외부 사이트의 HTML head 섹션에 임베딩 스크립트를 추가합니다:
<script src="https://discourse.example.com/javascripts/embed-topics.js"></script>
discourse.example.com을 실제 Discourse 포럼의 URL로 교체합니다.
- 주제를 표시할 위치에 주제 목록 요소를 배치합니다(예: 블로그 게시물 또는 개별 사이트 페이지):
<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- Discourse 사이트의 URL (필수)template- 표시 스타일 옵션:basic(기본값) - 주제 제목을 링크로 표시complete- 제목, 사용자 이름, 아바타, 생성 날짜, 마지막 답변 시간, 좋아요 수, 답변 수, 특징 이미지/썸네일 표시
per-page- 표시할 주제 수 (숨겨진embed_topic_limit_per_page사이트 설정으로 제한되며, 기본값 200)category- 특정 카테고리의 주제를 필터링할 카테고리 IDtags- 특정 태그로 주제 필터링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을 사용하는 경우, example.com만 추가하는 것이 아니라 www.example.com을 추가해야 합니다).
스크립트 로딩 오류
문제: 임베드 스크립트가 로드되지 않거나 연결 오류가 반환됩니다.
해결 방법:
- 스크립트 소스에서 Discourse URL이 정확하고 접근 가능한지 확인하세요.
embed_topics_list사이트 설정이 활성화되어 있는지 확인하세요.- 공개 주제에 대해 Discourse 사이트가 로그인 필수로 설정되어 있지 않은지 확인하세요.
SameSite 컨텍스트 동작
임베딩 사이트와 포럼이 상위 도메인을 공유하는 SameSite 컨텍스트에서, Discourse는 로그인 상태를 존중하여 그에 따라 결과를 표시합니다. 로그인한 사용자는 익명 사용자가 접근할 수 없는 보안 카테고리의 콘텐츠를 볼 수 있습니다.
자주 묻는 질문
Q: 비공개 Discourse 사이트의 주제를 임베드할 수 있나요?
A: 아니요, 주제 임베드는 공개 Discourse 사이트에서만 작동합니다. 로그인 필수인 비공개 사이트는 임베드할 수 없습니다.
Q: 동일한 페이지에 여러 주제 목록을 임베드할 수 있나요?
A: 네, 다른 매개변수를 사용하여 다양한 주제 컬렉션을 표시하기 위해 동일한 페이지에 여러 <d-topics-list> 요소를 포함할 수 있습니다.
Q: 특징 이미지가 있는 주제를 임베드하는 방법은 무엇인가요?
A: <d-topics-list> 요소에서 template="complete" 매개변수를 사용하여 썸네일과 특징 이미지가 있는 주제를 표시하세요.
Q: 주제 링크가 열리는 위치를 변경할 수 있나요?
A: 기본적으로 주제 링크는 부모 창에서 열립니다. CSS 또는 JavaScript 사용자 정의를 통해 이 동작을 수정할 수 있습니다.
