Themes and theme components allow you to handle uploaded assets such as images and fonts. You can control what assets your theme accepts using the site setting: theme authorized extensions
There are two classifications of themes and components - local and remote.
Local:
- The default Light and Dark themes that ship with every Discourse instance
- Themes and components created using the + Create New installation method
- Themes and components that were uploaded from your local computer using the From your device installation method.
Remote:
- Themes and components installed from the Popular list of themes
- Themes and components installed using the From a git repository method
Uploading assets to local themes and components
Navigate to your theme or component and select + Add in the Uploads section:
In the Add Upload modal, choose a file and enter a SCSS variable name to use with with your CSS, javascript, and/or handlbars customizations
Once uploaded, the asset will pop up in the Uploads list:
Important Note: Do not add uploads to themes and components through the admin interface if the component was installed remotely from a git repository. Updates to the component will clear out any uploads that were not included in the git repository.
Including assets in remote themes and components
See Create and share a font theme component for a detailed example.
How to make use of the assets
SCSS
@font-face {
font-family: Amazing;
src: url($Comic-Sans) format('woff2')
}
body {
font-family: Amazing;
font-size: 15px;
}
.d-header {
background-image: url($texture);
}
Javascript
<script type="text/discourse-plugin" version="0.8">
console.log(settings.theme_uploads.balloons)
</script>
Handlebars
<script type="text/x-handlebars" data-template-name="/connectors/topic-above-post-stream/foobar">
<img src="{{theme-setting "theme_uploads.balloons"}}">
</script>
HTML
You can’t directly add a theme asset to vanilla HTML (like in the header or after header sections of the customize admin panel). You have to use a handlebars template or the plugin API (more about those in Developer’s guide to Discourse Themes).
One workaround is to load your asset as a background image using SCSS (like the example above). So in the header section of your theme you might add:
<div class="my-custom-div">
<a href="/"></a>
</div>
and then in your CSS:
.my-custom-div a {
height: 50px;
width: 100px;
background-image: url($asset-name);
}
Additional Information
Treat theme_uploads as Settings in JavaScript
This has been implemented here:
https://github.com/discourse/discourse/commit/719a93c312b9caa6c71de22d67f1ce1a78c1c8b2
This change allows themes and components access to theme assets.
This means that inside theme js you can now get the URL for an asset with:
settings.theme_uploads.name
You can now do:
handlebars: {{theme-setting "theme_uploads.balloons"}}
javascript: settings.theme_uploads.balloons
Last Reviewed by @AlexDev on 2022-06-10T20:00:00Z