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 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’.
Change a template using css/html
This seems like the quickest technique, but I was concerned about one of the replies by @eviltrout
Change a template using a plugin outlet
Beginner's Guide to Creating Discourse Plugins - Part 1
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.
Change a template using the client side PluginAPI
A new 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!