Discourse now has the ability for themes to have “settings” that can be added by theme developers to allow site owners to customize themes through UI without having to change any line of code and worry about losing their changes with future updates for the theme.
Table of Content
- Adding settings to your theme
- Supported types
- Setting description and localization
- Min and max attributes
- Access to settings in your JS and CSS code
1) Adding settings to your theme
If you’re on Discourse version 2.0.0 beta 4 or higher, you’ll see there is a new “Settings” tab where you’ll be using the YAML language to define your theme settings. (if you don’t see the setting tab, make sure you’re not trying to edit an imported/remote theme).
Now if you’re familiar with plugin development, this shouldn’t be a new thing to you - it mostly works the same way as adding site settings to your plugin. Just dump some valid YAML under the settings tab and you’ll be good to go.
A valid theme setting must have a name and default value, that’s the bare minimum and it looks like this:
simple_setting: true
As you can probably tell, that will create a setting with the name simple_setting
and it’ll have true as its default value.
Similarly, you can add something like this:
site_name: My Forums
max_avatars: 7
And you’ll have two more settings, site_name
which will be a string setting with “My Forums” as the default value, and max_avatars
as an integer setting with default value of 7.
So until this point we’ve covered the simplest way to define settings. In the next section we’ll dive a bit deeper into the various types of settings and how you can use them.
2) Supported types
There are 6 types of settings:
- integer
- float
- string
- bool (for boolean)
- list
- enum
And you can specify type by adding a type
attribute to your setting like this:
float_setting:
type: float
default: 3.14
I should say that you don’t always have to explicitly set a type
attribute because Discourse is smart enough to work out the setting type from the setting’s default value. So you can reduce the above example to this:
float_setting:
default: 3.14
That said, you need to set a type attribute when working with list and enum settings, otherwise Discourse will not recognize them correctly.
Example of list and enum settings:
whitelisted_fruits:
default: apples|oranges
type: list
favorite_fruit:
default: orange
type: enum
choices:
- apple
- banana
In case the difference between list and enum settings is not clear to you: enum settings allow your theme users to select only one value from a set of values defined by you (see the choices
attribute).
On the other hand, list settings allow your users to create their own list (i.e. an array) of values. They can add to or remove from the setting’s default list of values.
You can set the default list of values for the setting by joining the values with a vertical bar “|” character. See the list setting in the example above.
You can see a real-world use case for list settings here: Linkify words in post, theme component.
Note: pay attention to indentation when working with YAML because YAML is very picky about spaces and will throw a syntax error if your code indentation is incorrect
3) Setting description and localizations
You can add description text to your theme setting and it’ll be shown right under the setting. To do that simply add a description
attribute to your setting like so:
whitelisted_fruits:
default: apples|oranges
type: list
description: "This text will be displayed under this setting and it explains what the setting does!"
And you’ll get this:
Multiple languages support
If you know more than one language, and you’d like to add support for those languages to your theme, then you can totally do that provided that Discourse supports said languages.
First of all, make sure the language you want to support is in this list:
Languages list
Code |
|
|
|
Name |
ar |
|
|
|
اللغة العربية |
bs_BA |
|
|
|
bosanski jezik |
ca |
|
|
|
català |
cs |
|
|
|
čeština |
da |
|
|
|
dansk |
de |
|
|
|
Deutsch |
el |
|
|
|
ελληνικά |
en |
|
|
|
English |
es |
|
|
|
Español |
et |
|
|
|
eesti |
fa_IR |
|
|
|
فارسی |
fi |
|
|
|
suomi |
fr |
|
|
|
Français |
gl |
|
|
|
galego |
he |
|
|
|
עברית |
id |
|
|
|
Indonesian |
it |
|
|
|
Italiano |
ja |
|
|
|
日本語 |
ko |
|
|
|
한국어 |
lv |
|
|
|
latviešu valoda |
nb_NO |
|
|
|
Norsk bokmål |
nl |
|
|
|
Nederlands |
pl_PL |
|
|
|
język polski |
pt |
|
|
|
Português |
pt_BR |
|
|
|
Português (BR) |
ro |
|
|
|
limba română |
ru |
|
|
|
Русский |
sk |
|
|
|
slovenčina |
sq |
|
|
|
Shqip |
sr |
|
|
|
српски језик |
sv |
|
|
|
svenska |
te |
|
|
|
తెలుగు |
th |
|
|
|
ไทย |
tr_TR |
|
|
|
Türkçe |
uk |
|
|
|
українська мова |
ur |
|
|
|
اردو |
vi |
|
|
|
Việt Nam |
zh_CN |
|
|
|
中文 |
zh_TW |
|
|
|
中文 (TW) |
(If you can’t see your language in the list then you might want to take a look at How to add a new language)
Then you’ll need find your language code from the above list and use the language code as a key under the description
attribute and translation as a value for the key like so:
whitelisted_fruits:
default: apples|oranges
type: list
description:
en: English text
ar: نص باللغة العربية
fr: Texte français
And now you have support for 3 languages: English, Arabic and French.
4) Min and max attributes
Sometimes you may need to specify limits that a setting value can’t exceed to prevent your users from accidentally breaking the theme or possibly the whole site.
To specify limits, simply add a min
or max
or both attributes to your setting like so:
integer_setting:
default: 10
min: 5
max: 100
You can specify limits to integer, float and string settings. For integer and float settings, the value of the setting itself is checked against the limits. And for string settings, the length of the value is checked against the specified limits.
If your user tries to enter a value that’s not within the allowed range, they’ll see an error telling them what the min and max values are.
5) Access to settings in your JS and CSS code
To have access to setting in your theme JS code, the script
tag that wraps your code must have a type="text/discourse-plugin"
attribute as well as version
specified like so:
<script type="text/discourse-plugin" version="0.8.13">
alert(settings.integer_setting + 1);
console.log(settings.string_setting);
</script>
In CSS, you’ll get a variable created for every setting of your theme and each variable will have the same name as the setting it represents.
So if you had a float setting called global_font_size
and a string setting called site_background
, you could do something like this in your theme CSS:
html {
font-size: #{$global-font-size}px;
background: $site-background;
}
If you have a question about this or there is something unclear, feel free to ask - I’ll try to answer/clarify as much as I can. Also this is a wiki post, so contributions to improve this are greatly appreciated!