Developing Discourse Themes & Theme Components

Documentation Developer Guides
, ,
1

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:

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

Frontend Customization

More!

Check out the rest of the Developer Guides !

This document is version controlled - suggest changes on github.

142 Likes
136

A lot of old and/or dead links and references in the The PluginApi - modifyClass() section section…

This file has changed so much that checkReplyLength doesn’t even exist any more…

And later in the same section:

This link just results in a “404 - Page not found” error…

I gave up using these docs after that…

4 Likes
137

A post was split to a new topic: User card template or widget?

138

Docs seem a bit outdated in this part… (also api.modifyClass complains about pluginId missing). How can I run a script when about-page is loaded? This one doesn’t seem to work (no errors though). I had mixed results with some other components. Thanks.

<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>
1 Like
139

Hello :wave: about-page is now in .gjs which also means it’s not modifiable anymore that way. If you want to make changes you have to use one of the connectors available on that page.

You can check these easily with Plugin outlet locations theme component or check in the file <PluginOutlet>.

4 Likes
142

Thank you very much. Makes sense. I have used a connector instead, works fine.

2 Likes
143

Is this guide even accurate anymore? I read thru the whole thing to try to create a theme component and then looked at the sample theme components and none of them use the instructions that they are supposed to. For example, in looking at discourse-brand-header theme component it seems to have been refactored from using stuff like api.createwidget in the header.html to using a totally different code with initializers, Components etc. Extremely complex code. The guide talks about using the API method with widgets, but that’s not what any of the components use at all. Is there an updated guide or something to use Components?

Edit: Supposedly widgets API is going away, but are there any guides on what to use instead? The entire guide here seems to be based on code that is deprecated?

3 Likes
144

That’s true. The guide ought to be updated. However, some parts are still quite relevant, like the structure of files, etc.

2 Likes
145

Yeah, it seems like SCSS is relevant, but otherwise, it seems like all sample theme components use Components and have been refactored to an entirely different codebase than what is taught here. I went thru all the components they link to in the Plugin API section and every single one has been refactored in a manner that is totally different than what is taught here in the guide. Widgets are not used anymore at all. It’s all Components. Is there a guide on how to actually properly use the new Components as Widgets are going away?

2 Likes
146

So I came across this post for example, just now: Upcoming Header Changes - Preparing Themes and Plugins - so they refactored everything from legacy widgets to Glimmer components? But, this tutorial is all legacy widgets. What are Glimmer components exactly and are there any guides? I feel lucky I caught this early on, before I started developing with legacy widgets. Maybe add a note in this guide that widgets are legacy and shouldn’t be used anymore?

2 Likes
147

Ok, I see Glimmer is new Ember components. But, I took a look at the Discourse TOC code and oh my…what previously had like 10 lines of code now is like 100’s of lines across many files with complex classes, decorators etc. I’m guessing Ember had a React moment and decided that let’s makes things really complicated again. Seems like Theme components are now no longer easy, with a simple widget api, but require extensive coding…

2 Likes
148

@ddsgad yes you’re right, most of this guide is extremely out-of-date. I’ve been working on general docs improvements recently, and hope to get this one updates/replaced in the next few weeks.

As you’ve mentioned, real-world examples like DiscoTOC can be a good reference. And then here are some specific guides which are more up-to-date:

For general information about Ember and its components, I recommend looking at the Ember guides.

6 Likes
149

Thanks for those links. Very helpful. Currently, we basically just customize stuff in a discourse topic (first post) to make some better designs, so we’ve been able to basically do everything with plain Vanilla javascript (querySelectorAll etc.) and SCSS, so I guess we will just keep to that for now.

3 Likes
150

The long and out-of-date tutorial in the OP has now been replaced with some more general introduction/signpost information, including a link to a brand new 7-step tutorial which follows much more modern theme development patterns.

4 Likes
151

I’ve read everything, I enjoyed it! Well explained, and very good introduction!

3 Likes
152

I love these guides! Finally deciphered api.decorateCookedElement, thanks for the helpful docs once again!

4 Likes