예정된 주제 목록 변경 - 테마 및 플러그인 준비 방법

개발
1

Discourse 코드베이스 전반의 렌더링 시스템 표준화를 위한 지속적인 노력의 일환으로, 토픽 목록(topic-list) 구현 방식을 교체하고 있습니다.

기존에는 ‘raw handlebars’(.hbr) 방식을 사용했으며, 템플릿 오버라이드와 raw-plugin-outlets를 통해 커스터마이징할 수 있었습니다. 새로운 토픽 목록 구현은 최신 Glimmer 컴포넌트를 사용하며, 지속 가능한 방식으로 커스터마이징할 수 있도록 처음부터 다시 설계되었습니다.

새로운 구현은 이제 glimmer_topic_list_mode 설정 뒤에 사용 가능합니다.

  • disabled: 레거시 “raw handlebars” 토픽 목록 사용
  • auto: 현재 플러그인과 테마의 호환성을 감지합니다. 호환되지 않는 항목이 있으면 레거시 시스템을 사용하고, 그렇지 않으면 새로운 구현을 사용합니다.
  • enabled: 새로운 토픽 목록 구현을 사용합니다. 호환되지 않는 플러그인이나 테마가 있는 경우 사이트가 손상될 수 있습니다.

이미 대부분의 공식 테마와 플러그인을 새로운 메뉴와 호환되도록 업데이트했습니다. 하지만 토픽 목록을 커스터마이징하는 서드파티 플러그인, 테마 또는 테마 컴포넌트를 사용 중이라면 해당 항목들의 업데이트가 필요합니다.

호환성 문제의 원인을 식별하는 경고가 브라우저 콘솔에 출력됩니다.

:timer_clock: 롤아웃 타임라인

이는 변경될 수 있는 대략적인 추정치입니다

2024년 4분기:

  • :white_check_mark: 코어 구현 완료
  • :white_check_mark: 공식 테마/플러그인 업데이트 (진행 중)
  • :white_check_mark: Meta에서 활성화됨
  • :white_check_mark: 업그레이드 가이드 게시됨

2025년 1분기:

  • :white_check_mark: 공식 테마/플러그인 업데이트

  • :white_check_mark: glimmer_topic_list_mode 기본값을 auto로 설정; 콘솔 비추천(deprecation) 메시지 활성화

  • :white_check_mark: 비추천(deprecation) 항목이 남아있는 문제를 관리자에게 경고 배너로 표시

  • 서드파티 플러그인과 테마 업데이트 필요

  • :white_check_mark: 3월 1일 - 모든 사이트에서 새로운 토픽 목록 활성화. 사이트 설정의 기본값이 enabled로 전환되지만, 'disabled’로 되돌리는 것은 여전히 가능합니다

2025년 2분기

  • :white_check_mark: 4월 1일 이후 - 레거시 모드 및 관련 코드 최종 제거

:eyes: 나에게 어떤 의미가 있는가?

플러그인이나 테마에 ‘raw handlebars’ 파일(이름이 .hbr 또는 .raw.hbs인 파일)이 있다면, 새로운 버전과 호환되도록 업데이트해야 합니다. Ember 컴포넌트/루트를 위한 일반 .hbs 파일은 이 변경 사항의 영향을 받지 않습니다.

component:topic-list 또는 component:topic-list-item에 modifyClass를 사용하는 경우에도 업그레이드가 필요합니다.

사이트에 이러한 호환되지 않는 커스터마이징이 있는 경우, 브라우저 개발자 콘솔에 어떤 테마/플러그인이 원인이 되는지에 대한 정보를 포함한 경고 메시지가 출력됩니다.

대체 방안은 무엇인가?

일부 구형 raw-plugin-outlets는 일반 Plugin Outlets으로 전환되었습니다. 이러한 항목들은 1:1 방식으로 업데이트할 수 있습니다.

더 복잡한 커스터마이징은 개별적으로 평가해야 합니다. 새로운 토픽 목록은 쉽고 견고한 커스터마이징을 위한 여러 새로운 API를 제공합니다. 자세한 내용은 여기에서 확인하세요:

다음은 몇 가지 예시입니다:

:sos: 다른 커스터마이징은 어떻게 되는가?

도입한 새로운 API를 사용하여 커스터마이징을 달성할 수 없는 경우, 논의하기 위해 새로운 Development 토픽을 만들어 알려주세요.

:sparkles: 저는 플러그인/테마 개발자입니다. 전환 기간 동안 구형과 신형 토픽 목록 모두를 지원하는 테마/플러그인으로 업데이트하는 방법은 무엇인가요?

새로운 플러그인 아웃렛은 구형과 신형 토픽 목록 구현 모두에서 렌더링됩니다. 따라서: 새로운 구현을 구현한 후에는 단순히 구형 raw-plugin-outlet 커넥터를 삭제하면 됩니다.

템플릿 오버라이드나 비모던화(non-modernized)된 아웃렛을 대체하는 DAG 기반 커스터마이징의 경우, 전환 기간 동안 두 가지 구현을 모두 유지해야 합니다.

테마/플러그인이 구형과 신형 구현 모두를 지원하는 경우, 모든 .hbr 파일 상단에 이 마법 주석(magic comment)을 추가할 수 있습니다:

{{!-- has-modern-replacement --}}

이렇게 하면 비추천(deprecation) 메시지가 조용해지고, “auto” 모드일 때 새로운 구현이 사용될 수 있게 됩니다.

2

조금 까다롭게 보일 수 있지만, 이 말은 실제로 "플러그인이나 테마에 토픽 목록(topic-list)과 관련된 ‘raw handlebars’ 파일이 있다면 업데이트해야 한다"는 뜻이 아닌가요?

다른 모델과 관련된 제 raw handlebars 파일들은 계속 문제없이 사용될 수 있겠죠? 아니면 raw handlebars 파일이 완전히 사라지는 건가요? (추가 모델/루트에는 raw handlebars 파일이 필수라고 생각하는데, 맞나요?)

3

“Raw handlebars”는 discourse 전용 템플릿을 의미하며, 파일 확장자는 .hbr(또는 과거에는 .raw.hbs)입니다. 이 시스템은 주제 목록(topic-list)과 일부 ‘자동완성(autocomplete)’ 내부 기능에서만 사용되었습니다.

다른 .hbs 파일(예: Ember 컴포넌트나 라우트용)에는 영향을 미치지 않습니다.

OP를 업데이트하여 이를 더 명확히 하겠습니다. @pfaffman님 감사합니다!

수정: 다음과 같이 업데이트했습니다:

4

아. 정말 명확하게 설명하려고 하셨군요. 확장자를 명시적으로 적어주셨잖아요. 더 명확하게 할 수는 없을 것 같아요. 이건 제 탓인 것 같습니다. :person_shrugging:

하지만 그 추가 문장이 있었더라면 제가 더 잘 읽을 수 있었을지도 몰랐습니다.

5

공감해줘서 고마워. 오래전부터 이걸 두려워해 왔는데, 드디어 다가오는 중이네…:grimacing: 쉬운 여정은 아닐 것 같아… :sweat_smile: 하지만 Value Transformer가 아마도 그 과정을 좀 더 쉽게 만들어 줄 거야.:crossed_fingers:

6

https://github.com/discourse/discourse-topic-excerpts가 아직 업데이트되지 않은 것 같습니다.

7

네, 업그레이드가 대기 중인 공식 테마/플러그인이 여전히 많이 있습니다. 원글(OP)의 해당 항목을 1분기로 연장하겠습니다 :writing_hand:

8

감사합니다! 지금까지 개발 경험이 정말 좋습니다. TLP를 다룰 때 문제가 생기면 알려드릴게요.

9

좋아요! 공식 topic-list-thumbnails은 이미 업데이트를 마친 항목 중 하나이므로, 참고 자료로 유용하게 활용할 수 있을 것 같습니다.

10

아, 실수했습니다! @isaac 님이 지난주에 topic-excerpts를 업데이트했습니다: DEV: Update plugin for `glimmer-topic-list` (#34) · discourse/discourse-topic-excerpts@0dd3c6c · GitHub

따라서 새로운 topic-list에서 정상적으로 작동해야 합니다 :crossed_fingers:

11

다음과 같은 오류가 발생하고 있습니다:

A website error message displaying a warning about an error caused by 'Topic List Excerpts'. (Captioned by AI)
A website error message displaying a warning about an error caused by 'Topic List Excerpts'. (Captioned by AI)1302×164 24.6 KB

image
image644×144 19.5 KB

The image shows a user interface for enabling "Glimmer topic list mode" with a reset button. (Captioned by AI)
The image shows a user interface for enabling "Glimmer topic list mode" with a reset button. (Captioned by AI)1432×300 18.8 KB

두 버전 모두 최신 상태입니다

12

열을 추가할 때, 정렬 가능한 열 헤더를 추가하는 전략적인 방법은 무엇인가요?

다른 트랜스포머 외에 다음을 사용하여야 하나요?

api.registerValueTransformer("topic-list-header-sortable-column"

다음 코드만으로는 이 기능이 작동하지 않는 것 같습니다: :thinking:

      api.registerValueTransformer(
        "topic-list-columns",
13

@isaac 에게 알려주세요. 제 추측으로는 새로운 로직이 분류되지 않은(topics) 주제를 처리하도록 업데이트가 필요할 수도 있습니다.

찾아보신 그 트랜스포머(transformer)는 기존 열의 정렬 기능을 재정의(오버라이드)하는 용도로 사용됩니다. (예: discourse-calendar에서는 시간순 주제 보기 화면에서 다른 정렬 방식의 사용이 방치되지 않도록 하기 위해 이렇게 처리합니다.)

새로운 열을 추가하는 경우라면, SortableColumn 컴포넌트를 사용하여 헤더를 정의하기만 하면 됩니다. 예를 들어 코어(core)에는 다음과 같은 예시가 있습니다:

(새로운 API의 정말 좋은 점 중 하나는, 테마/플러그인에서 사용하는 것과 동일한 API로 모든 코어 열이 정의된다는 것입니다!)

14

네, 코드 검색을 할 때 그걸 알아차렸어요, 좋습니다!

15

수정했습니다 :slight_smile:

16

Q: <template>가 아닌, 완전한 Component를 Cell에 할당할 수 있나요?

예를 들어, 최소한의 자바스크립트 로직이 필요한 투명 버튼을 셀에 표시하고 싶다면 어떻게 해야 하나요?

17

네! 기술적으로 볼 때, 맨 <template> 태그는 "템플릿 전용 컴포넌트(Template Only Component)"를 생성합니다. components/ 디렉터리 아래에 맨 .hbs 파일을 배치했을 때 생성되는 컴포넌트 유형과 유사합니다.

따라서 네, 일반 컴포넌트 클래스를 가져와서 전달하는 방식도 동일하게 작동합니다. 클래식 컴포넌트에서도 작동합니다! (물론 더 현대적인 Glimmer 컴포넌트 사용을 권장합니다).

18

완전 대박이네요!

이건 … 정말 많은 걸 바꿔놓네요! :exploding_head:

20

어리석은 질문일 수도 있겠네요.

그런데 … 모바일 주제 목록에 변경 사항을 적용하는 방법은 무엇인가요?

21

모바일의 경우, 새로운 플러그인 아웃렛(래퍼 아웃렛 포함)을 여러 개 추가했습니다.

또는 valueTransformer를 사용해 모든 곳에서 데스크톱 뷰를 강제 적용할 수도 있습니다(토픽 섬네일에서는 이렇게 하고 있습니다).

다음 주에 "토픽 목록 사용자 정의 방법"에 대한 더 자세한 Documentation > Developer Guides 문서를 작성할 예정이므로, 해당 정보도 반드시 포함하겠습니다.