discourse/app/assets/javascripts/admin/addon/components/theme-site-settings.gjs
Martin Brennan 19af83d39e
FEATURE: Themeable site settings (#32233)
This commit introduces the concept of themeable site settings,
which is a new tool for theme authors that lives alongside theme
modifiers and theme settings. Here is a quick summary:

* Theme settings - These are custom settings used to control UI and functionality within your theme or component and provide configuration options. These cannot change core Discourse functionality.
* Theme modifiers - Allows a theme or a component to modify selected server-side functionality of core Discourse as an alternative to building a plugin.
* Themeable site settings (new) - Allows a theme (not components) to override a small subset of core site settings, which generally control parts of the UI and other minor functionality. This allows themes to have a greater control over the full site experience.

Themeable site settings will be shown for all themes, whether the theme
changes
the value or not, and have a similar UI to custom theme settings.

We are also introducing a new page at
`/admin/config/theme-site-settings` that
allows admins to see all possible themeable site settings, and which
themes
are changing the value from the default.

### Configuration

Theme authors can configure initial values themeable site settings using
a section in the `about.json` file like so:

```json
"theme_site_settings": {
  "search_experience": "search_field"
}
```

These values will not change when the theme updates, because we cannot
know if admins have manually changed them.

### Limitations

Themeable site settings are only really intended to control elements of
the UI, and when retrieving their value we require a theme ID, so these
limitations apply:

- Themeable site settings cannot be used in Sidekiq jobs
- Themeable site settings cannot be used in markdown rules
- Themeable site settings will be cached separately to client site
settings using theme ID as a key
- Themeable site settings will override keys on the `siteSettings`
service on the client using the application preloader
- `SiteSetting.client_settings_json` will not include themeable site
settings, instead you can call `SiteSetting.theme_site_settings_json`
with a theme ID

### Initial settings

There are only two site settings that will be themeable to begin with:

* `enable_welcome_banner`
* `search_experience`

And our new Horizon theme will take advantage of both. Over time, more
settings that control elements of the UI will be exposed this way.
2025-07-16 11:00:21 +10:00

133 lines
4.5 KiB
Text

import Component from "@glimmer/component";
import { tracked } from "@glimmer/tracking";
import { array } from "@ember/helper";
import { action } from "@ember/object";
import { LinkTo } from "@ember/routing";
import { service } from "@ember/service";
import { eq } from "truth-helpers";
import AsyncContent from "discourse/components/async-content";
import DPageSubheader from "discourse/components/d-page-subheader";
import basePath from "discourse/helpers/base-path";
import { ajax } from "discourse/lib/ajax";
import { currentThemeId, listThemes } from "discourse/lib/theme-selector";
import { i18n } from "discourse-i18n";
import DTooltip from "float-kit/components/d-tooltip";
export default class ThemeSiteSettings extends Component {
@service site;
@service router;
@tracked themesWithSiteSettingOverrides = null;
@tracked themeableSiteSettings = null;
get themes() {
return listThemes(this.site);
}
get currentThemeIdValue() {
return currentThemeId();
}
get currentTheme() {
return this.themes.find((theme) => {
return eq(theme.id, this.currentThemeIdValue);
});
}
isLastThemeSettingOverride(overrides, theme) {
return theme === overrides.themes.at(-1);
}
@action
async loadThemeSiteSettings() {
let url = "/admin/config/theme-site-settings.json";
const response = await ajax(url, {
method: "GET",
});
this.themeableSiteSettings = response.themeable_site_settings.map(
(setting) => {
return {
name: setting.humanized_name,
value: setting,
};
}
);
this.themesWithSiteSettingOverrides =
response.themes_with_site_setting_overrides;
return this.themesWithSiteSettingOverrides;
}
<template>
<div class="theme-site-settings">
<AsyncContent @asyncData={{this.loadThemeSiteSettings}}>
<:content as |content|>
<DPageSubheader
@descriptionLabel={{i18n
"admin.theme_site_settings.help"
currentTheme=this.currentTheme.name
basePath=basePath
currentThemeId=this.currentThemeIdValue
}}
/>
<table class="d-admin-table admin-theme-site-settings">
<thead>
<tr>
<th>{{i18n "admin.theme_site_settings.setting"}}</th>
<th>{{i18n "admin.theme_site_settings.default_value"}}</th>
<th>{{i18n "admin.theme_site_settings.overridden_by"}}</th>
</tr>
</thead>
<tbody>
{{#each-in content as |settingName overrides|}}
<tr
class="admin-theme-site-settings-row d-admin-row__content"
data-setting-name={{settingName}}
>
<td class="admin-theme-site-settings-row__setting">
<p class="setting-label">{{overrides.humanized_name}}</p>
<div
class="setting-description"
>{{overrides.description}}</div>
</td>
<td class="admin-theme-site-settings-row__default">
{{overrides.default}}
</td>
<td class="admin-theme-site-settings-row__overridden">
{{#each overrides.themes as |theme|}}
<DTooltip>
<:trigger>
<LinkTo
@route="adminCustomizeThemes.show"
@models={{array "themes" theme.theme_id}}
class="theme-link"
data-theme-id={{theme.theme_id}}
>
{{theme.theme_name}}
</LinkTo>
</:trigger>
<:content>
{{i18n
"admin.theme_site_settings.overridden_value"
value=theme.value
}}
</:content>
</DTooltip>
{{#unless
(this.isLastThemeSettingOverride overrides theme)
}},{{/unless}}
{{/each}}
{{#unless overrides.themes}}
-
{{/unless}}
</td>
</tr>
{{/each-in}}
</tbody>
</table>
</:content>
<:empty>
</:empty>
</AsyncContent>
</div>
</template>
}