Discourse 테마에 설정 추가하기

Discourse · 3월 8, 2018, 10:28오후

Discourse는 테마 개발자가 사이트 소유자가 코드를 한 줄도 변경하지 않고, 테마의 향후 업데이트로 인해 변경 사항이 손실될 걱정을 하지 않으면서 UI를 통해 테마를 사용자화할 수 있도록 "설정"을 추가할 수 있는 기능을 제공합니다.

테마는 또한 특정 테마화 가능한 사이트 설정을 변경할 수 있으며, 이에 대한 자세한 내용은 테마화 가능한 사이트 설정 주제를 참조하세요.

테마에 설정 추가하기

테마에 설정을 추가하는 것은 CSS와 JS 코드를 추가하는 것과 약간 다릅니다. UI를 통해 이를 수행할 방법이 없습니다.

설정을 추가하려면 테마 저장소를 생성하고, 저장소의 루트 폴더에 settings.yaml(또는 settings.yml)이라는 새 파일을 만들어야 합니다. 이 파일에서는 YAML 언어를 사용하여 테마 설정을 정의합니다.

참고: 개발 과정을 크게 단순화시켜 주는 Theme CLI을 활용하는 것이 도움이 될 수 있습니다.

플러그인 개발에 익숙하다면 이 부분은 낯설지 않을 것입니다. 기본적으로 플러그인에 사이트 설정을 추가하는 방식과 거의 동일하게 작동합니다. 설정 파일에 유효한 YAML을 입력하기만 하면 됩니다.

유효한 테마 설정에는 이름과 기본값이 있어야 하며, 이것이 최소한의 요구 사항입니다. 다음과 같이 보입니다:

simple_setting: true

아마도 짐작할 수 있겠지만, 이는 simple_setting이라는 이름의 설정을 생성하고 기본값으로 true를 가지게 합니다.

마찬가지로, 다음과 같은 내용을 추가할 수 있습니다:

site_name: My Forums
max_avatars: 7

그러면 site_name이라는 문자열 설정(기본값 “My Forums”)과 max_avatars라는 정수 설정(기본값 7) 두 가지가 추가됩니다.

JS 코드에서 설정에 다음과 같이 액세스할 수 있습니다: settings.your_setting_key.

따라서 지금까지 우리는 설정을 정의하는 가장 간단한 방식을 다뤘습니다. 다음 섹션에서는 다양한 유형의 설정과 그 사용법에 대해 좀 더 자세히 살펴보겠습니다.

지원되는 유형

설정 유형은 9가지입니다:

integer
float
string
bool (불리언용)
list
enum
objects (json_schema의 대체재)
upload (이미지용)
icon (Discourse 아이콘 세트의 단일 아이콘용)

설정 유형을 지정하려면 설정에 type 속성을 다음과 같이 추가합니다:

float_setting:
  type: float
  default: 3.14

type 속성을 명시적으로 설정할 필요가 항상 있는 것은 아닙니다. Discourse는 설정의 기본값을 기반으로 설정 유형을 자동으로 파악할 만큼 충분히 지능적이기 때문입니다. 따라서 위의 예제를 다음과 같이 줄일 수 있습니다:

float_setting:
  default: 3.14

다만, list, enum, icon 설정을 사용할 때는 type 속성을 설정해야 합니다. 그렇지 않으면 Discourse가 이를 올바르게 인식하지 못할 수 있습니다.

List 설정:

whitelisted_fruits:
  default: apples|oranges
  type: list

Enum 설정:

favorite_fruit:
  default: orange
  type: enum
  choices:
    - apple
    - banana

list 설정과 enum 설정의 차이가 명확하지 않다면: enum 설정은 테마 사용자가 개발자가 정의한 값 세트(choices 속성 참조)에서 _하나_의 값만 선택할 수 있도록 허용합니다.

반면, list 설정은 사용자가 값의 목록(즉, 배열)을 자체적으로 생성할 수 있도록 허용합니다. 설정의 기본 값 목록에 값을 추가하거나 제거할 수 있습니다.
설정 값의 기본 목록은 세로 줄 | 문자로 값을 연결하여 설정할 수 있습니다. 위의 예제에서 list 설정을 참조하세요.

list 설정의 실제 사용 사례는 여기서 볼 수 있습니다: Auto-Linkify Words.

참고: YAML은 공백에 매우 까다롭고, 코드 들여쓰기가 잘못되면 구문 오류를 발생시키므로 YAML 작업 시 들여쓰기에 주의하세요.

Icon 설정:

banner_icon:
  default: bullhorn
  type: icon

Icon 설정은 사이트 소유자에게 검색 가능한 아이콘 선택기를 제공하며, 값은 아이콘 이름입니다. Discourse는 선택된 아이콘을 스프라이트 시트에 추가하므로, 별도로 등록하지 않고도 테마에서 렌더링할 수 있습니다.

`objects` 유형

objects 설정 유형은 사용자 정의 구조와 검증을 통해 고급 설정을 달성할 수 있도록 하는 특수 유형입니다. 이 유형에 대한 별도의 문서가 있습니다.

설정 설명 및 로컬라이제이션

테마 설정에 설명 텍스트를 추가할 수 있으며, 이는 설정 바로 아래 라벨로 표시됩니다. 이렇게 하려면 설정에 description 속성을 다음과 같이 추가하면 됩니다:

whitelisted_fruits:
  default: apples|oranges
  type: list
  description: "이 텍스트는 이 설정 아래에 표시되며 설정의 기능을 설명합니다!"

그러면 다음과 같은 결과가 나옵니다:

다국어 지원

여러 언어를 알고 있으며 테마에 해당 언어 지원을 추가하고 싶다면, Discourse가 해당 언어를 지원하는 경우 이를 완전히 수행할 수 있습니다.

우선, 지원하려는 언어가 다음 목록에 있는지 확인하세요:

언어 목록

코드				이름
ar				اللغة العربية
bs_BA				bosanski jezik
ca				català
cs				čeština
da				dansk
de				Deutsch
el				ελληνικά
en				English
es				Español
et				eesti
fa_IR				فارسی
fi				suomi
fr				Français
gl				galego
he				עברית
id				Indonesian
it				Italiano
ja				日本語
ko				한국어
lv				latviešu valoda
nb_NO				Norsk bokmål
nl				Nederlands
pl_PL				język polski
pt				Português
pt_BR				Português (BR)
ro				limba română
ru				Русский
sk				slovenčina
sq				Shqip
sr				српски језик
sv				svenska
te				తెలुగు
th				ไทย
tr_TR				Türkçe
uk				українська мова
ur				اردو
vi				Việt Nam
zh_CN				中文
zh_TW				中文 (TW)

(목록에서 언어를 찾을 수 없다면 How to add a new language 을 참고해 보세요)

그런 다음 위의 목록에서 언어 코드를 찾아야 하고, description 속성 아래에서 언어 코드를 키로 사용하고 번역을 값으로 사용해야 합니다. 다음과 같이요:

whitelisted_fruits:
  default: apples|oranges
  type: list
  description:
    en: English text
    ar: نص باللغة العربية
    fr: Texte français

이제 영어, 아랍어, 프랑스어 3개 언어에 대한 지원을 갖추게 되었습니다.

추가 설정 속성 및 옵션

Min 및 Max 속성

때때로 사용자가 테마 또는 심지어 전체 사이트를 우연히 깨뜨리는 것을 방지하기 위해 설정 값이 초과할 수 없는 한계를 지정해야 할 수 있습니다.

한계를 지정하려면 설정에 min 또는 max 또는 두 속성을 모두 다음과 같이 추가하면 됩니다:

integer_setting:
  default: 10
  min: 5
  max: 100

integer, float, string 유형 설정에 한계를 지정할 수 있습니다. integer 및 float 설정의 경우, 설정 값 자체가 한계와 비교됩니다. string 설정의 경우, 값의 길이가 지정된 한계와 비교됩니다.

사용자가 허용된 범위를 벗어난 값을 입력하려고 하면, 최소값과 최대값이 무엇인지 알려주는 오류가 표시됩니다.

JS/CSS/Handlebars에서의 설정에 대한 액세스

테마 설정은 테마 JavaScript 파일에서 settings 변수로 전역적으로 사용 가능합니다. 예를 들어:

// {theme}/javascripts/discourse/api-initializers/init-theme.gjs
import { apiInitializer } from "discourse/lib/api";

export default apiInitializer((api) => {
  console.log("settings are", settings);
});

이 settings 객체는 .gjs <template> 태그 내에서 일반적으로 사용할 수도 있습니다.

CSS 변수 설정

CSS에서는 테마의 모든 설정에 대해 변수가 생성되며, 각 변수는 해당 설정과 동일한 이름을 갖습니다.

따라서 global_font_size라는 float 설정과 site_background라는 string 설정이 있다면, 테마 CSS에서 다음과 같은 작업을 수행할 수 있습니다:

html {
  font-size: #{$global-font-size}px;
  background: $site-background;
}

그룹 멤버십 해결

테마 컴포넌트는 현재 사용자가 구성된 그룹에 속하는지에 따라 기능을 표시하거나 숨겨야 하는 경우가 있습니다. currentUser.groups를 확인하여 이를 처리하지 마세요. 이 속성은 사용자에게 표시되는 그룹만 포함하며 숨겨진 그룹을 놓칠 수 있기 때문입니다.

그룹 기반 list 설정의 경우, 서버 측에서 확인을 해결하려면 resolve_group_membership: true를 추가하세요:

copy_button_allowed_groups:
  default: "1|3"
  type: list
  list_type: group
  resolve_group_membership: true

이 옵션은 설정에 type: list와 list_type: group이 있을 때만 유효합니다. 활성화되면 프론트엔드 settings 객체에는 원래의 그룹 목록이 포함되지 않습니다. 대신, Discourse는 user_in_ 접두사가 붙은 동일한 설정 이름을 가진 불리언 값을 추가합니다:

// {theme}/javascripts/discourse/api-initializers/init-theme.gjs
import { apiInitializer } from "discourse/lib/api";

export default apiInitializer((api) => {
  if (!settings.user_in_copy_button_allowed_groups) {
    return;
  }

  // User is in at least one selected group.
});

생성된 불리언 값은 logged_in_users와 anonymous_users와 같은 자동 그룹에서도 작동합니다. 객체 테마 설정은 type: groups 속성에 동일한 옵션을 사용할 수 있습니다. 자세한 내용은 테마 설정용 objects 유형을 참조하세요.

글		댓글	조회수
Add support for theme settings Feature	18	5240	5월 4, 2018
How are theme setting fields created? Support	6	2360	5월 8, 2018
Controlling site settings with themes Developer Guides	0	320	7월 16, 2025
Developing Discourse Plugins - Part 3 - Add custom site settings Developer Guides plugin-guides , tutorial	39	24553	3월 15, 2025
Theme with variable width inside settings UX	5	1086	4월 13, 2022