Customizing handlebars templates

[sarahann (Sarah)]

I am new to discourse and have been exploring the many ways to add custom styling to my forums.

So far, I have realized that the Custom CSS/HTML feature is mainly for adding new components to discourse. I used this awesome tool to get started Install the Discourse Theme CLI console app to help you build themes.

In terms of customizing Discourse’s template code, modifying the .css classes works fine because it is cascading. However, I have reached the point of customization where I would like to modify the template HTML (not just the CSS). From what I understand, that requires me to modify the handlebars code. Essentially, I want to hide some functionality and modify/extend some of the existing functionality.

I have found 3 popular approaches to achieve this, and am looking for input as to which way is the ‘best practice’.

1. Change a template using css/html
   https://meta.discourse.org/t/how-to-customize-discourse-templates/34813
   This seems like the quickest technique, but I was concerned about one of the replies by @eviltrout

@eviltrout

Overriding templates is always risky, as if we change the underlying template to add or change a feature you will not receive the change. We recommend using plugin outlets and CSS wherever possible. But if you must override a template you can!

2. Change a template using a plugin outlet
   Developing Discourse Plugins - Part 1 - Create a basic plugin
   From my understanding, this technique requires a plugin to be developed and added to discourse. Within the plugin directory, you create the same file structure to the file you wish to overwrite in order to change the functionality.

3. Change a template using the client side PluginAPI
   A versioned API for client side plugins
   It seems this technique requires a script tag to be added to a theme HTML file. The script tag identifies the path to the handlebars file to be overwritten. By using the withPluginApi you can essentially do the same as making a plugin.

I am having a hard time understanding the differences between these 3 options.

• Is one of them considered Discourse’s ‘best practice’
• Is one of them more maintainable and resilient to changes made in Discourse?
• What is the difference between overwriting using a plugin outlet and the pluginAPI? Is there a difference aside from their implementation? Do these two achieve the exact same thing?
• Is one more performant than another?
• How do you extend Discourse’s current handlebars file and add some of your own custom code?
• How do you delete/remove some of Discourse’s functionality that you don’t want to show on the UI?

I realize that this might be a case where these 3 options achieve the same thing and I need to choose which is best for my implementation/system. But anything to help me understand these better is much appreciated!

[david (David Taylor)]

Here are some brief answers:

@sarahann

Is one of them considered Discourse’s ‘best practice’
Is one of them more maintainable and resilient to changes made in Discourse?

Plugin outlets are a far better way to extend things, they shouldn’t be broken by changes made to Discourse.

@sarahann

What is the difference between overwriting using a plugin outlet and the pluginAPI? Is there a difference aside from their implementation? Do these two achieve the exact same thing?

Overriding a template will “replace” it. Plugin outlets are simply points in the page that you can “insert” content into. If you want to add content, a plugin outlet might be enough. Overriding templates should always be a last resort.

@sarahann

Is one more performant than another?

No, I don’t think so

@sarahann

How do you extend Discourse’s current handlebars file and add some of your own custom code?

You can’t really “extend” the templates, only replace them. The “how to customise discourse templates” link you posted has an example, but plugin outlets would be better.

@sarahann

How do you delete/remove some of Discourse’s functionality

The easiest way is through CSS changes in a theme as you mentioned. You could have a look at this theme, which @joebuhlig uses to hide a number of discourse features:

Joe's Personal Discourse Theme

Here’s what may be a new way to use Discourse. Though I’m sure I’m not the first to think of this, I haven’t seen any posts about it. I’ve started a new private instance of Discourse that is designed to be a notes app replacement. Think of Evernote or OneNote but it’s Discourse and for only a single person. It occurred to me that all of these notes apps have things like URLs per note, APIs for interacting with the notes, email in, and the ability to share notes with others. But those are all t…

Hope that helps a bit - if you can describe which bit of discourse you want to change then it will be easier for people to give more specific advice.

[sarahann (Sarah)]

Thanks for the super quick reply!! This has been super helpful!

But I have a few more questions now.

@david

Overriding a template will “replace” it. Plugin outlets are simply points in the page that you can “insert” content into. If you want to add content, a plugin outlet might be enough. Overriding templates should always be a last resort.

I was wondering more if the plugin outlet (Developing Discourse Plugins - Part 1 - Create a basic plugin) and the pluginAPI (A versioned API for client side plugins) do the same thing? Their implementation is different, as one is a plugin added to discourse and the other is part of the HTML/JS. Is one of these methods preferred? Cause you also mentioned that:

@david

Plugin outlets are a far better way to extend things, they shouldn’t be broken by changes made to Discourse.

So does that mean that the pluginAPI isn’t as resilient to changes as the plugin outlets?

@david

The easiest way is through CSS changes in a theme as you mentioned. You could have a look at this theme, which @joebuhlig uses to hide a number of discourse features:

I was hoping not to use ‘display: none’. I was snooping through some sites that have customized Discourse and came across this one. Overwatch Forums
It looks really clean, but lots of the out-of-the-box functionality is removed from the UI. I don’t see any ‘display: none’ to remove the functionality. Could it be that Blizzard used the pluginAPI or plugin outlet to replace some of the handlebars files, and omitted some of the code?