Skip to content

A platform for community discussion. Free, open, simple.

DEV: add a value transformer for custom welcome banner locations (#43977)

Krise544b01efc51
diff --git a/frontend/discourse/app/components/welcome-banner.gjs b/frontend/discourse/app/components/welcome-banner.gjs
index 11a4dfd3784..554f6f8bdf3 100644
--- a/frontend/discourse/app/components/welcome-banner.gjs
+++ b/frontend/discourse/app/components/welcome-banner.gjs
@@ -1,5 +1,6 @@
import Component from "@glimmer/component";
-import { next } from "@ember/runloop";
+import { registerDestructor } from "@ember/destroyable";
+import { next, schedule } from "@ember/runloop";
import { service } from "@ember/service";
import { dasherize } from "@ember/string";
import { trustHTML } from "@ember/template";
@@ -18,6 +19,9 @@ import DButton from "discourse/ui-kit/d-button";
import dConcatClass from "discourse/ui-kit/helpers/d-concat-class";
import I18n, { i18n } from "discourse-i18n";
+const claimedLocations = new Map();
+const reportedLocations = new Set();
+
export const ALL_PAGES_EXCLUDED_ROUTES = [
"account-created.edit-email",
"account-created.index",
@@ -130,6 +134,46 @@ export default class WelcomeBanner extends Component {
return () => this.appEvents.off("header:keyboard-trigger", cb);
});
+ constructor() {
+ super(...arguments);
+
+ const { location } = this.args;
+ if (location === undefined) {
+ return;
+ }
+
+ claimedLocations.set(location, (claimedLocations.get(location) ?? 0) + 1);
+ registerDestructor(this, () => {
+ const remaining = claimedLocations.get(location) - 1;
+ if (remaining > 0) {
+ claimedLocations.set(location, remaining);
+ } else {
+ claimedLocations.delete(location);
+ }
+ });
+
+ // Other render points are constructed in this same pass, so wait for them
+ // before deciding that nobody claimed the location.
+ schedule("afterRender", this, this.#reportUnclaimedLocation);
+ }
+
+ // Where the banner renders. Core offers the site setting's locations; a
+ // customization can return a location of its own and render the banner independently,
+ // as long as it passes a @location that matches the transformer's value
+ get location() {
+ return applyValueTransformer(
+ "welcome-banner-location",
+ this.siteSettings.welcome_banner_location
+ );
+ }
+
+ // A bare <WelcomeBanner> without a @location arg will render regardless of the claimed location
+ get matchesLocation() {
+ return (
+ this.args.location === undefined || this.args.location === this.location
+ );
+ }
+
get displayForRoute() {
const { currentRouteName } = this.router;
const { top_menu, welcome_banner_page_visibility } = this.siteSettings;
@@ -194,7 +238,11 @@ export default class WelcomeBanner extends Component {
}
get shouldDisplay() {
- return this.siteSettings.enable_welcome_banner && this.displayForRoute;
+ return (
+ this.siteSettings.enable_welcome_banner &&
+ this.matchesLocation &&
+ this.displayForRoute
+ );
}
get bodyClasses() {
@@ -206,7 +254,7 @@ export default class WelcomeBanner extends Component {
}
get locationClass() {
- return `--location-${dasherize(this.siteSettings.welcome_banner_location)}`;
+ return `--location-${dasherize(this.location)}`;
}
get bgImgClass() {
@@ -236,6 +284,31 @@ export default class WelcomeBanner extends Component {
}
}
+ #reportUnclaimedLocation() {
+ if (this.isDestroying) {
+ return;
+ }
+
+ const { location } = this;
+ if (
+ !this.siteSettings.enable_welcome_banner ||
+ !this.displayForRoute ||
+ claimedLocations.has(location) ||
+ reportedLocations.has(location)
+ ) {
+ return;
+ }
+
+ reportedLocations.add(location);
+ // eslint-disable-next-line no-console
+ console.warn(
+ `Welcome banner: no render point for location "${location}", so the ` +
+ `banner will not be shown. Either render <WelcomeBanner @location="${location}" /> ` +
+ "where you want it, or check the value returned by the " +
+ "welcome-banner-location transformer."
+ );
+ }
+
#shouldDisplayForRoute(
welcome_banner_page_visibility,
top_menu,
diff --git a/frontend/discourse/app/lib/registry/transformers.js b/frontend/discourse/app/lib/registry/transformers.js
index 084c188ace3..ea523763ce4 100644
--- a/frontend/discourse/app/lib/registry/transformers.js
+++ b/frontend/discourse/app/lib/registry/transformers.js
@@ -173,4 +173,5 @@ export const VALUE_TRANSFORMERS = Object.freeze([
"user-notes-modal-subtitle",
"user-path",
"welcome-banner-display-for-route",
+ "welcome-banner-location",
]);
diff --git a/frontend/discourse/app/templates/application.gjs b/frontend/discourse/app/templates/application.gjs
index c0ec39826a0..9cad42476ac 100644
--- a/frontend/discourse/app/templates/application.gjs
+++ b/frontend/discourse/app/templates/application.gjs
@@ -32,7 +32,6 @@ import DTooltips from "discourse/float-kit/components/d-tooltips";
import bodyClass from "discourse/helpers/body-class";
import lazyHash from "discourse/helpers/lazy-hash";
import routeAction from "discourse/helpers/route-action";
-import { eq } from "discourse/truth-helpers";
import DCustomHtml from "discourse/ui-kit/d-custom-html";
export default <template>
@@ -71,11 +70,7 @@ export default <template>
<OfflineIndicator />
{{/if}}
- {{#if
- (eq @controller.siteSettings.welcome_banner_location "below_site_header")
- }}
- <WelcomeBanner />
- {{/if}}
+ <WelcomeBanner @location="below_site_header" />
<PluginOutlet
@connectorTagName="div"
@@ -112,14 +107,7 @@ export default <template>
<AdminOnboardingBanner />
{{/if}}
- {{#if
- (eq
- @controller.siteSettings.welcome_banner_location
- "above_topic_content"
- )
- }}
- <WelcomeBanner />
- {{/if}}
+ <WelcomeBanner @location="above_topic_content" />
<div class="container" id="main-container">
{{#if @controller.showTop}}
diff --git a/frontend/discourse/tests/integration/components/welcome-banner-test.gjs b/frontend/discourse/tests/integration/components/welcome-banner-test.gjs
index 36e35230fd5..dec00e1c53d 100644
--- a/frontend/discourse/tests/integration/components/welcome-banner-test.gjs
+++ b/frontend/discourse/tests/integration/components/welcome-banner-test.gjs
@@ -1,6 +1,8 @@
import { render } from "@ember/test-helpers";
import { module, test } from "qunit";
+import sinon from "sinon";
import WelcomeBanner from "discourse/components/welcome-banner";
+import { withPluginApi } from "discourse/lib/plugin-api";
import { setupRenderingTest } from "discourse/tests/helpers/component-test";
import { i18n } from "discourse-i18n";
@@ -25,6 +27,82 @@ module(
assert.dom(".welcome-banner.--location-below-site-header").exists();
});
+ test("renders only at the location matching welcome_banner_location", async function (assert) {
+ this.siteSettings.welcome_banner_location = "above_topic_content";
+ await render(
+ <template>
+ <WelcomeBanner @location="above_topic_content" />
+ <WelcomeBanner @location="below_site_header" />
+ </template>
+ );
+
+ assert.dom(".welcome-banner").exists({ count: 1 }, "renders once");
+ assert.dom(".welcome-banner.--location-above-topic-content").exists();
+ });
+
+ test("renders without @location regardless of welcome_banner_location", async function (assert) {
+ this.siteSettings.welcome_banner_location = "below_site_header";
+ await render(<template><WelcomeBanner /></template>);
+
+ assert
+ .dom(".welcome-banner")
+ .exists(
+ "a consumer placing the banner itself is not gated on location"
+ );
+ });
+
+ test("welcome-banner-location value transformer moves the banner", async function (assert) {
+ const warnStub = sinon.stub(console, "warn");
+
+ withPluginApi((api) => {
+ api.registerValueTransformer(
+ "welcome-banner-location",
+ () => "discovery-above"
+ );
+ });
+
+ this.siteSettings.welcome_banner_location = "above_topic_content";
+ await render(
+ <template>
+ <WelcomeBanner @location="above_topic_content" />
+ <WelcomeBanner @location="discovery-above" />
+ </template>
+ );
+
+ assert.dom(".welcome-banner").exists({ count: 1 }, "renders once");
+ assert
+ .dom(".welcome-banner.--location-discovery-above")
+ .exists("renders at the transformed location");
+ assert.false(
+ warnStub.called,
+ "does not warn when a render point claims the location"
+ );
+ });
+
+ test("warns when no render point claims the effective location", async function (assert) {
+ const warnStub = sinon.stub(console, "warn");
+
+ withPluginApi((api) => {
+ api.registerValueTransformer(
+ "welcome-banner-location",
+ () => "nowhere-in-particular"
+ );
+ });
+
+ await render(
+ <template><WelcomeBanner @location="above_topic_content" /></template>
+ );
+
+ assert.dom(".welcome-banner").doesNotExist("banner is not rendered");
+ assert.true(
+ warnStub.args
+ .flat()
+ .join(" ")
+ .includes('no render point for location "nowhere-in-particular"'),
+ "warns that the location is unclaimed"
+ );
+ });
+
test("shows the logged in user message with the user's username", async function (assert) {
this.currentUser.previous_visit_at = new Date("2025-01-01");
await render(<template><WelcomeBanner /></template>);