In Plugin System Upgrades @eviltrout introduced a system for extending Discourse HTML using plugin outlets.
Plugin outlets are tagged areas in our application that allow you to inject a template. The template has access to the backing controller so it can be dynamic.
Our theme system in /admin/customize/themes allows you to define custom CSS and HTML.
When injecting HTML into your page you can also inject templates, this gives you a very simple mechanism for injecting content into various plugin outlets.
To inject into an outlet
-
Find out the outlet name, you can do so by digging through our source or using the plugin outlet location theme.
-
Define a handlebars template in the
</head>section.
An example of this is:
<script type='text/x-handlebars' data-template-name='/connectors/discovery-list-container-top/THEME_NAME'>
Welcome {{currentUser.username}}. Please visit <a class="nav-link " href="http://google.com" target="_blank">My Site</a>
</script>
(be sure to replace THEME_NAME with a unique identifier for your theme)
This will result in adding a navigation link in the header that only exists when the header is not in extra info mode (which happens when you scroll down a topic)
Naming is critical
Your template must have the data-template-name attribute identify the outlet. It is named like so:
/connectors/OUTLET-NAME/UNIQUE-ID
If you stray from that naming your template will not be picked up or injected.
Using this technique even business and standard customers can heavily extend Discourse without needing plugins.
Adding backing class to the outlet
If you wish to add a backing class to the outlet use api.registerConnectorClass eg:
api.registerConnectorClass("user-preferences-interface", "add-keyboard-selector", {
shouldRender() {
return require("discourse/lib/utilities").isAppleDevice();
}
});
When possible always prefer solutions that inject into a plugin outlet, over solutions that override an entire template, that allows your theme to be far more robust and “future proof”.
Advanced usage
When using the Theme CLI, or a git-backed theme, you can split up your theme javascript into multiple files under /javascripts. More information can be found at Splitting up theme Javascript into multiple files
