Developing Discourse Themes & Theme Components

[Discourse]

Discourse Themes and Theme Components can be used to customize the look, feel and functionality of Discourse’s frontend. This section of the developer guides aims to provide all the reference materials you need to develop simple themes for a single site, right up to complex open-source theme components.

This introduction aims to provide a map of all the tools and APIs for theme development. If you prefer a step-by-step tutorial for theme development, jump straight to:

Theme Developer Tutorial: 1. Introduction

This tutorial will teach you how to create a Discourse Theme or Theme Component from the ground up. While this topic assumes no previous experience working on Discourse themes, it does assume some prior experience using HTML, CSS and JavaScript. It’ll also help if you know your way around GitHub. What are Discourse themes? A theme or theme component is a set of files packaged together designed to either modify Discourse visually or to add new features. Themes In general, themes are not suppo…

Themes vs. Theme Components

Discourse Themes can be used to customize the frontend user experience using CSS and JavaScript. Each theme has its own git repository, and community admins can generally install and manage them via the Discourse admin panel, even on shared hosting platforms.

Theme Components are themes which are intended for use alongside other Theme Components, as part of an overall Theme. From a development point of view, Theme Components and Themes are almost identical. In these guides, the phrase “Theme” and “Theme Component” are used interchangeably.

Prerequisites

Firstly, make sure you understand how to use existing themes and theme components in Discourse. Using ready-made themes is the quickest and safest way to customize your community. If you need more, then it’s time to consider writing your own theme.

As part of Discourse’s overall architecture, Discourse Themes are built using standard HTML, CSS, JavaScript technologies, and make use of Ember concepts for more advanced UIs. These reference guides assume a base-level understanding of these technologies, and link out to external references where possible.

Discourse is a fast-moving project, and as such any custom theme will require maintenance over time. Make sure you consider this as part of your planning & development processes.

Getting Started

• Theme CLI
• Theme Creator
• File structure of theme

Frontend Customization

• Color Schemes
• JavaScript API
• Outlets
• Transformers
• modifyClass

More!

Check out the rest of the Developer Guides !

---

This document is version controlled - suggest changes on github.

[rsigg]

The PluginApi - modifyClass() section 섹션에 오래되었거나 죽은 링크와 참조가 정말 많습니다…

@Discourse

https://github.com/discourse/discourse/blob/main/app/assets/javascripts/discourse/app/controllers/composer.js#L578

이 파일은 너무 많이 변경되어 checkReplyLength가 더 이상 존재하지도 않습니다…

그리고 같은 섹션의 후반부에서는:

@Discourse

https://github.com/discourse/discourse/blob/master/app/assets/javascripts/discourse/app/components/discovery-categories.js

이 링크는 단순히 “404 - 페이지를 찾을 수 없음” 오류만 발생합니다…

그 후로 이 문서를 사용하는 것을 포기했습니다…

[Overgrow]

@Discourse

컴포넌트가 로드될 때 스크립트를 실행하려면 다음과 같은 코드를 사용할 수 있습니다.

이 부분에 대한 문서가 약간 구식이네요. (api.modifyClass가 pluginId 누락에 대해 경고도 합니다.) about-page가 로드될 때 스크립트를 실행하려면 어떻게 해야 하나요? 아래 코드는 작동하지 않는 것 같습니다(에러는 발생하지 않아요). 다른 컴포넌트에서는 결과가まちまち였습니다. 감사합니다.

<script type="text/discourse-plugin" version="0.11.1">

api.modifyClass("component:about-page", {
  pluginId: 'discourse-about-theme',

  didInsertElement() {
    this._super(...arguments);
    console.log("Welcome to the about page!");
  }

});

</script>

[Don]

안녕하세요 about-page가 이제 .gjs 파일이 되었으며, 이는 해당 방식으로 더 이상 수정할 수 없음을 의미합니다. 변경 사항을 적용하려면 해당 페이지에서 사용할 수 있는 커넥터 중 하나를 사용해야 합니다.

플러그인 아웃렛 위치 테마 컴포넌트를 통해 이를 쉽게 확인할 수 있거나, 파일 내 <PluginOutlet>을 직접 확인해 볼 수도 있습니다.

[Overgrow]

정말 감사합니다. 이해가 됩니다. 대신 커넥터를 사용했는데, 잘 작동합니다.

[ddsgad (DDSGadget)]

이 가이드가 아직도 정확한가요? 테마 컴포넌트를 만들어 보려고 전체를 읽었는데, 샘플 테마 컴포넌트 중 그 지시를 따르는 것이 하나도 없었습니다. 예를 들어 discourse-brand-header 테마 컴포넌트를 살펴보면, header.html에서 api.createwidget와 같은 것을 사용하던 것에서 초기화 프로그램(Initializers), 컴포넌트(Components) 등을 사용하는 완전히 다른 코드로 리팩토링된 것 같습니다. 매우 복잡한 코드입니다. 가이드에서는 위젯을 위한 API 메서드를 사용하라고 하지만, 실제로는 어떤 컴포넌트도 전혀 그렇게 사용하지 않습니다. 컴포넌트를 사용하는 방법에 대한 업데이트된 가이드나 유사한 것이 있을까요?

수정: 위젯 API가 곧 사라진다고 하는데, 대신 무엇을 사용해야 하는지에 대한 가이드가 있나요? 여기의 전체 가이드가 비추천(deprecated)된 코드를 기반으로 작성된 것 같습니다.

[NateDhaliwal]

맞아요. 가이드는 업데이트되어야 합니다. 하지만 파일 구조 같은 일부 내용은 여전히 꽤 관련이 있습니다.

[ddsgad (DDSGadget)]

네, SCSS는 관련이 있는 것 같지만, 그 외에는 모든 샘플 테마 컴포넌트가 Components를 사용하며, 여기서 가르치는 내용과는 완전히 다른 코드베이스로 리팩토링된 것 같습니다. 플러그인 API 섹션에서 링크된 모든 컴포넌트를 확인해 보았는데, 하나같이 여기서 가이드로 가르치는 방식과는 전혀 다른 방식으로 리팩토링되어 있었습니다. Widgets는 더 이상 전혀 사용되지 않습니다. 전부 Components입니다. Widgets가 사라지는 상황에서, 새로운 Components를 실제로 올바르게 사용하는 방법에 대한 가이드가 있을까요?

[ddsgad (DDSGadget)]

예를 들어 방금 이런 게시물을 보았습니다: Upcoming Header Changes - Preparing Themes and Plugins - 그래서 레거시 위젯에서 Glimmer 컴포넌트로 모든 것을 리팩토링한 건가요? 하지만 이 튜토리얼은 전부 레거시 위젯에 대한 내용입니다. Glimmer 컴포넌트란 정확히 무엇이며, 관련 가이드가 있나요? 레거시 위젯으로 개발을 시작하기 전에 이걸 알게 되어 다행이라고 생각합니다. 이 가이드에 위젯이 레거시이며 더 이상 사용되지 않는다는 주의를 추가해 주시면 어떨까요?

[ddsgad (DDSGadget)]

네, Glimmer가 새로운 Ember 컴포넌트라는 점은 알겠어요. 그런데 Discourse TOC 코드를 살펴봤는데, 제발… 이전에 10줄 정도였던 코드가 이제는 여러 파일에 걸쳐 수백 줄로 늘어났고, 복잡한 클래스, 데코레이터 등이 사용되고 있더라고요. Ember가 React처럼 '모멘트’를 맞이해서 다시 정말 복잡한 방향으로 가자고 결정한 것 같아요. 테마 컴포넌트도 이제는 간단한 위젯 API로 쉽게 만들 수 있는 것이 아니라, 방대한 양의 코딩이 필요한 것 같습니다…

[david (David Taylor)]

@ddsgad 네, 맞습니다. 이 가이드의 대부분이 매우 오래되었습니다. 최근 일반 문서 개선 작업을 진행 중이며, 향후 몇 주 안에 이 가이드를 업데이트하거나 교체할 예정입니다.

말씀하신 대로 DiscoTOC와 같은 실제 사례가 좋은 참고 자료가 될 수 있습니다. 그리고 여기 더 최신 상태인 특정 가이드들이 있습니다:

• Install the Discourse Theme CLI console app to help you build themes

• Using Plugin Outlet Connectors from a Theme or Plugin

• Customizing the topic list

• Introducing Discourse developer toolbar

Ember 및 그 컴포넌트에 대한 일반적인 정보는 Ember 가이드를 참고하는 것을 권장합니다.

[ddsgad (DDSGadget)]

링크들 감사합니다. 정말 도움이 됩니다. 현재 우리는 기본적으로 discourse 주제(첫 번째 게시글)의 요소를 커스터마이징하여 더 나은 디자인을 만들고 있는데, 덕분에 기본적으로 순수 Vanilla JavaScript(querySelectorAll 등)와 SCSS만으로 거의 모든 작업을 처리할 수 있었습니다. 그래서 당분간 이 방식을 유지할 것 같습니다.

[david (David Taylor)]

OP의 길고 오래된 튜토리얼은 이제 더 일반적인 소개/가이드 정보로 대체되었습니다. 여기에는 훨씬 더 현대적인 테마 개발 패턴을 따르는 완전히 새로운 7단계 튜토리얼에 대한 링크도 포함되어 있습니다.

[Arkshine]

모든 내용을 읽었고, 재미있게 읽었습니다! 잘 설명되어 있었고, 아주 좋은 입문 자료였어요!

[NateDhaliwal]

이런 가이드 정말 좋아요! api.decorateCookedElement를 드디어 파악했습니다. 또 도움되는 문서 감사합니다!