Skip to content

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

DEV: Add plugin outlet aliases and deprecations (#38809)

Sérgio Saquetima373705c907e
diff --git a/config/locales/client.en.yml b/config/locales/client.en.yml
index 2663043c77a..2c6e95cf55b 100644
--- a/config/locales/client.en.yml
+++ b/config/locales/client.en.yml
@@ -395,6 +395,15 @@ en:
visual_overlay: "Visual overlay"
ghost_blocks: "Ghost blocks"
condition_debugging: "Condition debugging"
+ plugin_outlet_debug:
+ find_on_github: "Find on GitHub"
+ wrapper: "(wrapper)"
+ outlet_args: "Outlet args"
+ no_outlet_args: "No outlet args passed to this outlet"
+ aliases: "Aliases"
+ deprecated: "deprecated"
+ deprecated_outlet: "This outlet is deprecated and will be removed."
+ since: "(since %{version})"
toggle_safe_mode: "Toggle safe mode"
toggle_verbose_localization: "Toggle verbose localization"
toggle_mobile_view: "Toggle mobile view"
diff --git a/frontend/discourse/app/components/plugin-outlet.gjs b/frontend/discourse/app/components/plugin-outlet.gjs
index 60b4aade12a..d5aecf01759 100644
--- a/frontend/discourse/app/components/plugin-outlet.gjs
+++ b/frontend/discourse/app/components/plugin-outlet.gjs
@@ -1,5 +1,6 @@
/* eslint-disable ember/no-classic-components */
import Component from "@glimmer/component";
+import { DEBUG } from "@glimmer/env";
import { cached } from "@glimmer/tracking";
import ClassicComponent from "@ember/component";
import { concat } from "@ember/helper";
@@ -23,33 +24,325 @@ const GET_DEPRECATION_MSG =
const ARGS_DEPRECATION_MSG =
"PluginOutlet arguments should now be passed using `@outletArgs=` instead of `@args=`";
-/**
- A plugin outlet is an extension point for templates where other templates can
- be inserted by plugins.
+const DEPRECATION_ONLY_KEYS = ["since", "message", "id", "url", "raiseError"];
+const VALID_POSITIONS = ["before", "after"];
- ## Usage
+/**
+ * Normalizes an alias entry to a consistent object form.
+ * Accepts either a plain string or an object with a `name` property.
+ *
+ * @param {string|Object} alias - The alias entry to normalize.
+ * @returns {{ name: string, deprecated?: boolean, position?: string, since?: string, message?: string, id?: string, url?: string, raiseError?: boolean }}
+ */
+export function normalizeAlias(alias) {
+ if (typeof alias === "string") {
+ return { name: alias };
+ }
- If your handlebars template has:
+ if (DEBUG) {
+ if (!alias.name) {
+ throw new Error("PluginOutlet alias object must have a `name` property.");
+ }
- ```handlebars
- <PluginOutlet @name="evil-trout" />
- ```
+ if (alias.position && !VALID_POSITIONS.includes(alias.position)) {
+ throw new Error(
+ `PluginOutlet alias "${alias.name}" has invalid position "${alias.position}". ` +
+ `Valid values are: ${VALID_POSITIONS.join(", ")}.`
+ );
+ }
- Then any handlebars files you create in the `connectors/evil-trout` directory
- will automatically be appended. For example:
+ if (!alias.deprecated) {
+ const presentKeys = DEPRECATION_ONLY_KEYS.filter(
+ (key) => alias[key] != null
+ );
+ if (presentKeys.length > 0) {
+ throw new Error(
+ `PluginOutlet alias "${alias.name}" has deprecation properties (${presentKeys.join(", ")}) but \`deprecated\` is not true. ` +
+ `Set \`deprecated=true\` or remove these properties.`
+ );
+ }
+ }
+ }
- plugins/hello/assets/javascripts/discourse/templates/connectors/evil-trout/hello.hbs
+ return alias;
+}
- With the contents:
+/**
+ * A plugin outlet is an extension point for templates where other templates can
+ * be inserted by plugins.
+ *
+ * ## Standard vs wrapper outlets
+ *
+ * A **standard outlet** is an empty slot where connectors are inserted:
+ *
+ * ```handlebars
+ * <PluginOutlet @name="above-footer" />
+ * ```
+ *
+ * A **wrapper outlet** wraps existing content by providing a block. When a
+ * connector is registered, it replaces the wrapped content. The outlet also
+ * automatically creates `__before` and `__after` sub-outlets that allow
+ * multiple connectors to render before or after the wrapped content without
+ * replacing it:
+ *
+ * ```handlebars
+ * <PluginOutlet @name="discovery-list-area">
+ * <div class="default-content">This is the default content</div>
+ * </PluginOutlet>
+ * ```
+ *
+ * In this example, connectors can target:
+ * - `discovery-list-area` to replace the default content
+ * - `discovery-list-area__before` to render before it
+ * - `discovery-list-area__after` to render after it
+ *
+ * ## Rendering connectors
+ *
+ * There are two ways to render content in a plugin outlet:
+ *
+ * ### 1. Plugin API (`api.renderInOutlet`)
+ *
+ * Register a component programmatically using the Plugin API:
+ *
+ * ```javascript
+ * import MyComponent from "discourse/plugins/my-plugin/components/my-component";
+ * api.renderInOutlet("evil-trout", MyComponent);
+ * ```
+ *
+ * Or inline with gjs:
+ *
+ * ```javascript
+ * api.renderInOutlet("evil-trout", <template><b>Hello World</b></template>);
+ * ```
+ *
+ * For wrapper outlets, use `api.renderBeforeWrapperOutlet()` and
+ * `api.renderAfterWrapperOutlet()` to render content before or after the
+ * wrapped content without replacing it:
+ *
+ * ```javascript
+ * api.renderBeforeWrapperOutlet("discovery-list-area", BeforeComponent);
+ * api.renderAfterWrapperOutlet("discovery-list-area", AfterComponent);
+ * ```
+ *
+ * ### 2. File-based connectors
+ *
+ * Create a template file in the `connectors/<outlet-name>/` directory:
+ *
+ * `plugins/my-plugin/assets/javascripts/discourse/connectors/evil-trout/hello.gjs`
+ *
+ * ```gjs
+ * <template><b>Hello World</b></template>
+ * ```
+ *
+ * This will render `<b>Hello World</b>` in every `<PluginOutlet @name="evil-trout" />`.
+ *
+ * For wrapper outlets, use the `__before` and `__after` suffixes in the
+ * connector directory name:
+ *
+ * `plugins/my-plugin/assets/javascripts/discourse/connectors/discovery-list-area__before/my-connector.gjs`
+ * `plugins/my-plugin/assets/javascripts/discourse/connectors/discovery-list-area__after/my-connector.gjs`
+ *
+ * ## Args
+ *
+ * See {@link PluginOutletSignature} for the full list of accepted args.
+ *
+ * Notes:
+ * - Use `deprecatedOutletArgument()` to build entries for `@deprecatedArgs`.
+ * - For `@aliases`, an entry may be a plain string (non-deprecated alias)
+ * or a {@link PluginOutletAlias} object. Properties other than `name`,
+ * `position`, and `deprecated` are only valid when `deprecated` is true —
+ * a DEBUG-only assertion fires otherwise.
+ * - The `id` on a {@link PluginOutletDeprecated} defaults to
+ * `discourse.plugin-outlet.deprecated.<name>` if omitted.
+ *
+ * ## Examples
+ *
+ * ### Renaming an outlet (old name is deprecated)
+ *
+ * ```handlebars
+ * <PluginOutlet
+ * @name="new-outlet-name"
+ * @aliases={{array
+ * (hash name="old-outlet-name" deprecated=true since="2026.3.0")
+ * }}
+ * @outletArgs={{this.outletArgs}}
+ * />
+ * ```
+ *
+ * Connectors registered under `old-outlet-name` will render here and emit
+ * a deprecation warning pointing to `new-outlet-name`.
+ *
+ * ### Non-deprecated alias
+ *
+ * ```handlebars
+ * <PluginOutlet
+ * @name="canonical-name"
+ * @aliases={{array "alternate-name"}}
+ * />
+ * ```
+ *
+ * ### Merging a standalone outlet into a wrapper outlet's sub-outlet
+ *
+ * When a standalone outlet (e.g., `below-topic-list-item`) is being replaced by
+ * a wrapper outlet, use `position="after"` (or `"before"`) to route connectors
+ * from the old standalone outlet to the wrapper's `__after`/`__before`
+ * sub-outlet:
+ *
+ * ```handlebars
+ * <PluginOutlet
+ * @name="topic-list-item__main-link-bottom-row"
+ * @aliases={{array
+ * (hash
+ * name="below-topic-list-item-bottom-row"
+ * position="after"
+ * deprecated=true
+ * since="2026.3.0"
+ * )
+ * }}
+ * >
+ * ...wrapped content...
+ * </PluginOutlet>
+ * ```
+ *
+ * Without `position`, alias connectors render in the main outlet (replacing
+ * wrapped content). With `position="after"`, they render in the `__after`
+ * sub-outlet instead, preserving the wrapped content. `position="before"`
+ * works the same way for the `__before` sub-outlet.
+ *
+ * If the original standalone outlet declared a `@connectorTagName` (so that
+ * legacy `.hbs` connectors received an automatic wrapper element), preserve
+ * that behavior on the alias so existing connectors keep their wrapper:
+ *
+ * ```handlebars
+ * <PluginOutlet
+ * @name="latest-topic-list-item__post-count"
+ * @aliases={{array
+ * (hash
+ * name="above-latest-topic-list-item-post-count"
+ * position="before"
+ * connectorTagName="div"
+ * deprecated=true
+ * since="2026.3.0"
+ * )
+ * }}
+ * />
+ * ```
+ *
+ * `connectorTagName` only applies to legacy file-based connectors registered
+ * under the aliased name. Modern `.gjs` connectors control their own DOM and
+ * ignore it.
+ *
+ * ### Deprecating an outlet entirely
+ *
+ * ```handlebars
+ * <PluginOutlet
+ * @name="doomed-outlet"
+ * @deprecated={{hash since="2026.3.0" message="Use the Block API instead."}}
+ * />
+ * ```
+ *
+ * ### Deprecating an individual outlet argument
+ *
+ * Use `@deprecatedArgs` with `deprecatedOutletArgument()` to warn when a
+ * specific arg is read by a connector, while keeping it functional until
+ * connectors are migrated:
+ *
+ * ```gjs
+ * import deprecatedOutletArgument from "discourse/helpers/deprecated-outlet-argument";
+ *
+ * <template>
+ * <PluginOutlet
+ * @name="my-outlet"
+ * @outletArgs={{lazyHash newName=this.newName}}
+ * @deprecatedArgs={{lazyHash
+ * oldName=(deprecatedOutletArgument
+ * value=this.newName
+ * message="`oldName` is deprecated, use `newName` instead."
+ * since="2026.3.0"
+ * )
+ * }}
+ * />
+ * </template>
+ * ```
+ *
+ * ## Wrapper outlet alias behavior
+ *
+ * When a wrapper outlet has aliases, the `__before` and `__after` sub-outlets
+ * automatically inherit them. For example, if outlet `foo` has alias `bar`,
+ * then connectors registered under `bar__before` will render in `foo__before`,
+ * and `bar__after` in `foo__after`.
+ *
+ * Aliases with a `position` property are an exception: they are routed to
+ * the specified sub-outlet using their base name (not appended with
+ * `__before`/`__after`), allowing standalone outlets to be merged into
+ * a wrapper outlet's before or after slot.
+ */
- ```handlebars
- <b>Hello World</b>
- ```
+/**
+ * @typedef PluginOutletAlias
+ *
+ * @property {string} name The alias outlet name.
+ * @property {boolean} [deprecated] Marks this alias as deprecated.
+ * @property {"before"|"after"} [position] Routes the alias to a wrapper sub-outlet.
+ * @property {string} [since] Discourse version when the deprecation was introduced.
+ * @property {string} [message] Custom deprecation message.
+ * @property {string} [id] Deprecation ID for silencing (auto-generated if omitted).
+ * @property {string} [url] URL with more detail about the deprecation.
+ * @property {boolean} [raiseError] Whether to throw instead of warn.
+ * @property {string} [connectorTagName] HTML tag for legacy file-based connector
+ * wrapper (e.g. `"div"`, `"span"`). Only relevant for position-targeted aliases
+ * merging standalone outlets that had `@connectorTagName`.
+ */
- Will insert <b>Hello World</b> at that point in the template.
+/**
+ * @typedef PluginOutletDeprecated
+ *
+ * @property {string} [since] Version when the outlet was deprecated.
+ * @property {string} [message] Custom deprecation message.
+ * @property {string} [id] Deprecation ID.
+ * @property {string} [url] URL with more detail about the deprecation.
+ * @property {boolean} [raiseError] Whether to throw instead of warn.
+ */
-**/
+/**
+ * @typedef PluginOutletSignature
+ *
+ * @property {object} Args
+ *
+ * // Identity
+ * @property {string} Args.name The outlet identifier. Connectors registered
+ * under this name will be rendered here.
+ *
+ * // Args passed to connectors
+ * @property {object} [Args.outletArgs] Arguments passed to connectors rendered
+ * in this outlet.
+ * @property {object} [Args.deprecatedArgs] Args with per-access deprecation
+ * warnings. Build entries with `deprecatedOutletArgument()`.
+ * @property {object} [Args.args] Deprecated legacy alias for `outletArgs`.
+ *
+ * // Aliases & deprecation
+ * @property {Array<string|PluginOutletAlias>} [Args.aliases] Alternative outlet
+ * names that this outlet also resolves connectors from. Useful for renaming
+ * or merging outlets without breaking existing customizations.
+ * @property {PluginOutletDeprecated} [Args.deprecated] Marks this outlet itself
+ * as deprecated. When set, a deprecation warning is emitted if any connectors
+ * are registered for this outlet.
+ *
+ * // Legacy file-based connector rendering
+ * @property {string} [Args.tagName] HTML tag for the wrapper element rendered
+ * around legacy file-based connectors.
+ * @property {string} [Args.connectorTagName] HTML tag for legacy file-based
+ * connector wrappers (e.g. `"div"`, `"span"`).
+ * @property {boolean} [Args.defaultGlimmer] When true, file-based connectors
+ * are rendered as template-only Glimmer components (no `this` context).
+ *
+ * // Optional wrapped content (wrapper outlets)
+ * @property {object} Blocks
+ * @property {[]} Blocks.default Default content rendered when no connector
+ * replaces it.
+ */
+/** @extends {Component<PluginOutletSignature>} */
export default class PluginOutlet extends Component {
@service clientErrorHandler;
@@ -75,14 +368,134 @@ export default class PluginOutlet extends Component {
return result;
}
+ /**
+ * Normalized alias entries from @aliases arg.
+ * Each entry is an object with at least a `name` property.
+ *
+ * @returns {Array<{ name: string, deprecated?: boolean, since?: string, message?: string, id?: string, url?: string, raiseError?: boolean }>}
+ */
+ @cached
+ get normalizedAliases() {
+ if (!this.args.aliases?.length) {
+ return [];
+ }
+ return this.args.aliases.map(normalizeAlias);
+ }
+
+ /**
+ * Derived aliases for the __before sub-outlet.
+ * Includes aliases with `position: "before"` using their base name (for merging
+ * standalone outlets into a wrapper's before slot), plus `__before` variants
+ * of all aliases without a position (for inheriting wrapper sub-outlet connectors).
+ *
+ * @returns {Array<Object>}
+ */
+ @cached
+ get aliasesForBefore() {
+ const result = [];
+ for (const alias of this.normalizedAliases) {
+ if (alias.position === "before") {
+ // Strip position since routing is resolved -- the sub-outlet
+ // should treat this as a regular alias
+ const withoutPosition = { ...alias };
+ delete withoutPosition.position;
+ result.push(withoutPosition);
+ } else if (!alias.position) {
+ result.push({ ...alias, name: `${alias.name}__before` });
+ }
+ }
+ return result;
+ }
+
+ /**
+ * Derived aliases for the __after sub-outlet.
+ * Includes aliases with `position: "after"` using their base name (for merging
+ * standalone outlets into a wrapper's after slot), plus `__after` variants
+ * of all aliases without a position (for inheriting wrapper sub-outlet connectors).
+ *
+ * @returns {Array<Object>}
+ */
+ @cached
+ get aliasesForAfter() {
+ const result = [];
+ for (const alias of this.normalizedAliases) {
+ if (alias.position === "after") {
+ const withoutPosition = { ...alias };
+ delete withoutPosition.position;
+ result.push(withoutPosition);
+ } else if (!alias.position) {
+ result.push({ ...alias, name: `${alias.name}__after` });
+ }
+ }
+ return result;
+ }
+
+ /**
+ * The connector tag name inherited from a position-targeted alias routed
+ * to the `__before` sub-outlet. Preserves the old standalone outlet's
+ * `@connectorTagName` for legacy file-based connectors.
+ *
+ * @returns {string|undefined}
+ */
+ @cached
+ get connectorTagNameForBefore() {
+ for (const alias of this.normalizedAliases) {
+ if (alias.position === "before" && alias.connectorTagName) {
+ return alias.connectorTagName;
+ }
+ }
+ return undefined;
+ }
+
+ /**
+ * The connector tag name inherited from a position-targeted alias routed
+ * to the `__after` sub-outlet. Preserves the old standalone outlet's
+ * `@connectorTagName` for legacy file-based connectors.
+ *
+ * @returns {string|undefined}
+ */
+ @cached
+ get connectorTagNameForAfter() {
+ for (const alias of this.normalizedAliases) {
+ if (alias.position === "after" && alias.connectorTagName) {
+ return alias.connectorTagName;
+ }
+ }
+ return undefined;
+ }
+
@bind
getConnectors({ hasBlock } = {}) {
- const connectors = renderedConnectorsFor(
- this.args.name,
- this.outletArgsWithDeprecations,
- this.context,
- getOwner(this)
- );
+ const aliases = this.normalizedAliases;
+ const dep = this.args.deprecated;
+
+ const connectors = this.#renderedConnectorsFor(this.args.name, {
+ aliases,
+ deprecated: dep,
+ });
+
+ // Emit outlet-level deprecation if connectors exist
+ if (dep && connectors.length > 0) {
+ this.#emitOutletDeprecation();
+ }
+
+ // Collect connectors from aliases (skip position-targeted aliases,
+ // they are handled by the __before/__after sub-outlets)
+ for (const alias of aliases) {
+ if (alias.position) {
+ continue;
+ }
+ const aliasConnectors = this.#renderedConnectorsFor(alias.name, {
+ skipDebug: true,
+ });
+ if (aliasConnectors.length > 0) {
+ if (alias.deprecated) {
+ this.#emitAliasDeprecation(alias);
+ }
+ connectors.push(...aliasConnectors);
+ }
+ }
+
if (connectors.length > 1 && hasBlock) {
const message = `Multiple connectors were registered for the ${this.args.name} outlet. Using the first.`;
this.clientErrorHandler.displayErrorNotice(message);
@@ -98,12 +511,36 @@ export default class PluginOutlet extends Component {
@bind
connectorsExist({ hasBlock } = {}) {
- return (
- connectorsExist(this.args.name) ||
+ if (
+ this.#connectorsExistFor(this.args.name) ||
(hasBlock &&
- (connectorsExist(this.args.name + "__before") ||
- connectorsExist(this.args.name + "__after")))
- );
+ (this.#connectorsExistFor(this.args.name + "__before") ||
+ this.#connectorsExistFor(this.args.name + "__after")))
+ ) {
+ return true;
+ }
+
+ // Check aliases (position-targeted aliases are checked by sub-outlets,
+ // but we still need to consider them for the wrapper's connectorsExist
+ // since they make the wrapper render its content including sub-outlets)
+ for (const alias of this.normalizedAliases) {
+ if (alias.position) {
+ if (this.#connectorsExistFor(alias.name)) {
+ return true;
+ }
+ continue;
+ }
+ if (
+ this.#connectorsExistFor(alias.name) ||
+ (hasBlock &&
+ (this.#connectorsExistFor(alias.name + "__before") ||
+ this.#connectorsExistFor(alias.name + "__after")))
+ ) {
+ return true;
+ }
+ }
+
+ return false;
}
// Traditionally, pluginOutlets had an argument named 'args'. However, that name is reserved
@@ -149,11 +586,54 @@ export default class PluginOutlet extends Component {
return curryComponent(component, args, getOwner(this));
}
+ #connectorsExistFor(name) {
+ return connectorsExist(name);
+ }
+
+ #emitAliasDeprecation(alias) {
+ const message =
+ alias.message ||
+ `Plugin outlet "${alias.name}" has been renamed to "${this.args.name}". Update your connector to use the new name.`;
+
+ deprecated(message, {
+ id: alias.id || `discourse.plugin-outlet.alias.${alias.name}`,
+ since: alias.since,
+ url: alias.url,
+ raiseError: alias.raiseError,
+ });
+ }
+
+ #emitOutletDeprecation() {
+ const dep = this.args.deprecated;
+ const message =
+ dep.message ||
+ `Plugin outlet "${this.args.name}" is deprecated and will be removed in a future version.`;
+
+ deprecated(message, {
+ id: dep.id || `discourse.plugin-outlet.deprecated.${this.args.name}`,
+ since: dep.since,
+ url: dep.url,
+ raiseError: dep.raiseError,
+ });
+ }
+
+ #renderedConnectorsFor(name, options) {
+ return renderedConnectorsFor(
+ name,
+ this.outletArgsWithDeprecations,
+ this.context,
+ getOwner(this),
+ options
+ );
+ }
+
<template>
{{~#if (this.connectorsExist hasBlock=(has-block))~}}
{{~#if (has-block)~}}
<PluginOutlet
@name={{concat @name "__before"}}
+ @aliases={{this.aliasesForBefore}}
+ @connectorTagName={{this.connectorTagNameForBefore}}
@outletArgs={{this.outletArgsWithDeprecations}}
/>
{{~/if~}}
@@ -192,6 +672,8 @@ export default class PluginOutlet extends Component {
{{~#if (has-block)~}}
<PluginOutlet
@name={{concat @name "__after"}}
+ @aliases={{this.aliasesForAfter}}
+ @connectorTagName={{this.connectorTagNameForAfter}}
@outletArgs={{this.outletArgsWithDeprecations}}
/>
{{~/if~}}
diff --git a/frontend/discourse/app/components/topic-list/latest-topic-list-item.gjs b/frontend/discourse/app/components/topic-list/latest-topic-list-item.gjs
index 501524836da..de8bcd3cc8b 100644
--- a/frontend/discourse/app/components/topic-list/latest-topic-list-item.gjs
+++ b/frontend/discourse/app/components/topic-list/latest-topic-list-item.gjs
@@ -1,5 +1,5 @@
import Component from "@glimmer/component";
-import { concat } from "@ember/helper";
+import { array, concat, hash } from "@ember/helper";
import PluginOutlet from "discourse/components/plugin-outlet";
import ItemRepliesCell from "discourse/components/topic-list/item/replies-cell";
import TopicPostBadges from "discourse/components/topic-post-badges";
@@ -87,27 +87,35 @@ export default class LatestTopicListItem extends Component {
<div class="bottom-row">
<PluginOutlet
@name="latest-topic-list-item-main-link-bottom-row"
+ @aliases={{array
+ (hash
+ name="below-latest-topic-list-item-bottom-row"
+ position="after"
+ connectorTagName="span"
+ deprecated=true
+ since="2026.3.0"
+ )
+ }}
@outletArgs={{lazyHash topic=@topic}}
>
{{categoryLink @topic.category~}}
{{~discourseTags @topic mode="list"}}
</PluginOutlet>
- <PluginOutlet
- @name="below-latest-topic-list-item-bottom-row"
- @connectorTagName="span"
- @outletArgs={{lazyHash topic=@topic}}
- />
</div>
</div>
<div class="topic-stats">
- <PluginOutlet
- @name="above-latest-topic-list-item-post-count"
- @connectorTagName="div"
- @outletArgs={{lazyHash topic=@topic}}
- />
<PluginOutlet
@name="latest-topic-list-item-topic-stats"
+ @aliases={{array
+ (hash
+ name="above-latest-topic-list-item-post-count"
+ position="before"
+ connectorTagName="div"
+ deprecated=true
+ since="2026.3.0"
+ )
+ }}
@outletArgs={{lazyHash topic=@topic}}
>
<ItemRepliesCell @topic={{@topic}} @tagName="div" />
diff --git a/frontend/discourse/app/lib/plugin-connectors.js b/frontend/discourse/app/lib/plugin-connectors.js
index e41358a5010..e335a9e7296 100644
--- a/frontend/discourse/app/lib/plugin-connectors.js
+++ b/frontend/discourse/app/lib/plugin-connectors.js
@@ -212,20 +212,27 @@ export function connectorsExist(outletName) {
return Boolean(_connectorCache[outletName] || debugOutletCallback);
}
-export function connectorsFor(outletName, outletArgs) {
+export function connectorsFor(outletName, outletArgs, options) {
if (!_connectorCache) {
buildConnectorCache();
}
- if (debugOutletCallback) {
+ if (debugOutletCallback && !options?.skipDebug) {
return debugOutletCallback(outletName, _connectorCache[outletName], {
outletArgs,
+ ...options,
});
}
return _connectorCache[outletName] || [];
}
-export function renderedConnectorsFor(outletName, args, context, owner) {
- return connectorsFor(outletName, args).filter((con) => {
+export function renderedConnectorsFor(
+ outletName,
+ args,
+ context,
+ owner,
+ options
+) {
+ return connectorsFor(outletName, args, options).filter((con) => {
return (
!con.connectorClass?.shouldRender ||
con.connectorClass?.shouldRender(args, context, owner)
diff --git a/frontend/discourse/app/static/dev-tools/plugin-outlet-debug/outlet-info.gjs b/frontend/discourse/app/static/dev-tools/plugin-outlet-debug/outlet-info.gjs
index 9b3a53636b1..7ea3b21a5fe 100644
--- a/frontend/discourse/app/static/dev-tools/plugin-outlet-debug/outlet-info.gjs
+++ b/frontend/discourse/app/static/dev-tools/plugin-outlet-debug/outlet-info.gjs
@@ -7,6 +7,8 @@ import DTooltip from "discourse/float-kit/components/d-tooltip";
import concatClass from "discourse/helpers/concat-class";
import icon from "discourse/helpers/d-icon";
import { DEPRECATED_ARGS_KEY } from "discourse/lib/outlet-args";
+import { or } from "discourse/truth-helpers";
+import { i18n } from "discourse-i18n";
import ArgsTable from "../shared/args-table";
import devToolsState from "../state";
@@ -31,6 +33,8 @@ const SMALL_OUTLETS = [
* @param {string} outletName - The name of the plugin outlet.
* @param {Object} [outletArgs] - Arguments passed to the outlet. May contain a non-enumerable
* `__deprecatedArgs__` property with the raw deprecated args for display in the debug tooltip.
+ * @param {Array<Object>} [aliases] - Normalized alias entries for this outlet.
+ * @param {Object} [deprecated] - Deprecation info if the outlet itself is deprecated.
*/
export default class OutletInfoComponent extends Component {
static shouldRender() {
@@ -100,6 +104,24 @@ export default class OutletInfoComponent extends Component {
);
}
+ /**
+ * Whether this outlet has any aliases configured.
+ *
+ * @returns {boolean}
+ */
+ get hasAliases() {
+ return this.args.aliases?.length > 0;
+ }
+
+ /**
+ * Whether this outlet itself is deprecated.
+ *
+ * @returns {boolean}
+ */
+ get isDeprecated() {
+ return !!this.args.deprecated;
+ }
+
/**
* Returns the heading modifier class based on outlet type.
*
@@ -149,7 +171,7 @@ export default class OutletInfoComponent extends Component {
{{icon "plug"}}
{{this.displayName}}
{{#if this.partOfWrapper}}
- (wrapper)
+ {{i18n "js.dev_tools.plugin_outlet_debug.wrapper"}}
{{/if}}
</span>
<a
@@ -157,18 +179,71 @@ export default class OutletInfoComponent extends Component {
href="https://github.com/search?q=repo%3Adiscourse%2Fdiscourse%20@name=%22{{this.displayName}}%22&type=code"
target="_blank"
rel="noopener noreferrer"
- title="Find on GitHub"
+ title={{i18n "js.dev_tools.plugin_outlet_debug.find_on_github"}}
>{{icon "fab-github"}}</a>
</div>
<div class="outlet-info__content">
+ {{#if this.isDeprecated}}
+ <div class="outlet-info__deprecation-banner">
+ {{icon "triangle-exclamation"}}
+ <span>
+ {{or
+ @deprecated.message
+ (i18n
+ "js.dev_tools.plugin_outlet_debug.deprecated_outlet"
+ )
+ }}
+ {{#if @deprecated.since}}
+ <span class="outlet-info__since">
+ {{i18n
+ "js.dev_tools.plugin_outlet_debug.since"
+ }}
+ </span>
+ {{/if}}
+ </span>
+ </div>
+ {{/if}}
+
+ {{#if this.hasAliases}}
+ <div class="outlet-info__section">
+ <div class="outlet-info__section-title">
+ {{i18n "js.dev_tools.plugin_outlet_debug.aliases"}}
+ </div>
+ <ul class="outlet-info__aliases">
+ {{#each @aliases as |alias|}}
+ <li class="outlet-info__alias">
+ <code>{{alias.name}}</code>
+ {{#if alias.deprecated}}
+ <span class="outlet-info__alias-deprecated">
+ {{icon "triangle-exclamation"}}
+ {{i18n
+ "js.dev_tools.plugin_outlet_debug.deprecated"
+ }}
+ {{#if alias.since}}
+ {{i18n
+ "js.dev_tools.plugin_outlet_debug.since"
+ version=alias.since
+ }}
+ {{/if}}
+ </span>
+ {{/if}}
+ </li>
+ {{/each}}
+ </ul>
+ </div>
+ {{/if}}
+
{{#if this.hasOutletArgs}}
<div class="outlet-info__section">
- <div class="outlet-info__section-title">Outlet Args</div>
+ <div class="outlet-info__section-title">
+ {{i18n "js.dev_tools.plugin_outlet_debug.outlet_args"}}
+ </div>
<ArgsTable @args={{@outletArgs}} @prefix="plugin outlet" />
</div>
{{else}}
<div class="outlet-info__empty">
- No outlet args passed to this outlet
+ {{i18n "js.dev_tools.plugin_outlet_debug.no_outlet_args"}}
</div>
{{/if}}
</div>
diff --git a/frontend/discourse/app/static/dev-tools/plugin-outlet-debug/patch.js b/frontend/discourse/app/static/dev-tools/plugin-outlet-debug/patch.js
index fff18c402c2..b06d3874551 100644
--- a/frontend/discourse/app/static/dev-tools/plugin-outlet-debug/patch.js
+++ b/frontend/discourse/app/static/dev-tools/plugin-outlet-debug/patch.js
@@ -14,23 +14,25 @@ export function patchConnectors() {
// so ArgsTable can display deprecation info without separate prop passing
_setIncludeDeprecatedArgsProperty(true);
- _setOutletDebugCallback((outletName, existing, { outletArgs } = {}) => {
- existing ||= [];
+ _setOutletDebugCallback(
+ (outletName, existing, { outletArgs, aliases, deprecated } = {}) => {
+ existing ||= [];
- if (!devToolsState.pluginOutletDebug) {
- return existing;
- }
+ if (!devToolsState.pluginOutletDebug) {
+ return existing;
+ }
- if (SKIP_EXISTING_FOR_OUTLETS.includes(outletName)) {
- existing = [];
- }
+ if (SKIP_EXISTING_FOR_OUTLETS.includes(outletName)) {
+ existing = [];
+ }
- const componentClass = curryComponent(
- OutletInfoComponent,
- { outletName, outletArgs },
- getOwnerWithFallback()
- );
+ const componentClass = curryComponent(
+ OutletInfoComponent,
+ { outletName, outletArgs, aliases, deprecated },
+ getOwnerWithFallback()
+ );
- return [{ componentClass }, ...existing];
- });
+ return [{ componentClass }, ...existing];
+ }
+ );
}
diff --git a/frontend/discourse/app/static/dev-tools/styles.css b/frontend/discourse/app/static/dev-tools/styles.css
index ea94152e2d3..364043ed62a 100644
--- a/frontend/discourse/app/static/dev-tools/styles.css
+++ b/frontend/discourse/app/static/dev-tools/styles.css
@@ -532,6 +532,62 @@ pre.outlet-info__error-message {
overflow-y: auto;
}
+.outlet-info__deprecation-banner {
+ display: flex;
+ align-items: center;
+ gap: 6px;
+ padding: 6px 8px;
+ background: var(--danger-low);
+ border: 1px solid var(--danger-medium);
+ border-radius: 4px;
+ color: var(--danger);
+ font-size: 12px;
+ line-height: 1.4;
+
+ .d-icon {
+ flex-shrink: 0;
+ }
+}
+
+.outlet-info__since {
+ color: var(--primary-medium);
+ font-size: 11px;
+}
+
+.outlet-info__aliases {
+ list-style: none;
+ margin: 0;
+ padding: 0;
+ display: flex;
+ flex-direction: column;
+ gap: 4px;
+
+ code {
+ font-size: 12px;
+ padding: 1px 4px;
+ background: var(--primary-very-low);
+ border-radius: 3px;
+ }
+}
+
+.outlet-info__alias {
+ display: flex;
+ align-items: center;
+ gap: 6px;
+}
+
+.outlet-info__alias-deprecated {
+ display: flex;
+ align-items: center;
+ gap: 4px;
+ color: var(--danger);
+ font-size: 11px;
+
+ .d-icon {
+ font-size: 10px;
+ }
+}
+
/* Shared Outlet Args Table */
.outlet-args-table {
display: flex;
diff --git a/frontend/discourse/tests/integration/components/plugin-outlet-test.gjs b/frontend/discourse/tests/integration/components/plugin-outlet-test.gjs
index 2161f912540..76ca7f2d03d 100644
--- a/frontend/discourse/tests/integration/components/plugin-outlet-test.gjs
+++ b/frontend/discourse/tests/integration/components/plugin-outlet-test.gjs
@@ -3,12 +3,15 @@ import Component from "@glimmer/component";
import { tracked } from "@glimmer/tracking";
import ClassicComponent from "@ember/component";
import templateOnly from "@ember/component/template-only";
+import { array, hash } from "@ember/helper";
import { getOwner } from "@ember/owner";
import { click, find, render, settled } from "@ember/test-helpers";
import hbs from "htmlbars-inline-precompile";
import { module, test } from "qunit";
import sinon from "sinon";
-import PluginOutlet from "discourse/components/plugin-outlet";
+import PluginOutlet, {
+ normalizeAlias,
+} from "discourse/components/plugin-outlet";
import deprecatedOutletArgument from "discourse/helpers/deprecated-outlet-argument";
import lazyHash from "discourse/helpers/lazy-hash";
import deprecated, {
@@ -1292,3 +1295,551 @@ module(
});
}
);
+
+module(
+ "Integration | Component | plugin-outlet | aliases and deprecations",
+ function (hooks) {
+ setupRenderingTest(hooks);
+
+ hooks.beforeEach(function () {
+ this.consoleWarnStub = sinon.stub(console, "warn");
+ disableRaiseOnDeprecation();
+ });
+
+ hooks.afterEach(function () {
+ this.consoleWarnStub.restore();
+ enableRaiseOnDeprecation();
+ });
+
+ test("renders connectors registered under an alias name", async function (assert) {
+ extraConnectorComponent(
+ "old-outlet-name",
+ <template>
+ <span class="alias-content">From alias</span>
+ </template>
+ );
+
+ await render(
+ <template>
+ <PluginOutlet
+ @name="new-outlet-name"
+ @aliases={{array "old-outlet-name"}}
+ />
+ </template>
+ );
+
+ assert.dom(".alias-content").hasText("From alias");
+ });
+
+ test("renders connectors from both canonical name and alias", async function (assert) {
+ extraConnectorComponent(
+ "canonical-outlet",
+ <template>
+ <span class="canonical">Canonical</span>
+ </template>
+ );
+ extraConnectorComponent(
+ "alias-outlet",
+ <template>
+ <span class="alias">Alias</span>
+ </template>
+ );
+
+ await render(
+ <template>
+ <PluginOutlet
+ @name="canonical-outlet"
+ @aliases={{array "alias-outlet"}}
+ />
+ </template>
+ );
+
+ assert.dom(".canonical").hasText("Canonical");
+ assert.dom(".alias").hasText("Alias");
+ });
+
+ test("deprecated alias emits warning when connectors exist", async function (assert) {
+ extraConnectorComponent(
+ "old-name",
+ <template>
+ <span class="old">Old</span>
+ </template>
+ );
+
+ await render(
+ <template>
+ <PluginOutlet
+ @name="new-name"
+ @aliases={{array
+ (hash name="old-name" deprecated=true since="4.0")
+ }}
+ />
+ </template>
+ );
+
+ assert.dom(".old").hasText("Old");
+ assert.true(
+ this.consoleWarnStub.calledWithMatch(
+ /Plugin outlet "old-name" has been renamed to "new-name"/
+ )
+ );
+ });
+
+ test("deprecated alias does not emit warning when no connectors exist", async function (assert) {
+ await render(
+ <template>
+ <PluginOutlet
+ @name="new-name"
+ @aliases={{array
+ (hash name="old-name" deprecated=true since="4.0")
+ }}
+ />
+ </template>
+ );
+
+ assert.false(
+ this.consoleWarnStub.calledWithMatch(/old-name/),
+ "no deprecation warning emitted"
+ );
+ });
+
+ test("deprecated alias uses custom message when provided", async function (assert) {
+ extraConnectorComponent(
+ "legacy-name",
+ <template>
+ <span class="legacy">Legacy</span>
+ </template>
+ );
+
+ await render(
+ <template>
+ <PluginOutlet
+ @name="modern-name"
+ @aliases={{array
+ (hash
+ name="legacy-name"
+ deprecated=true
+ since="4.0"
+ message="Use modern-name instead of legacy-name"
+ )
+ }}
+ />
+ </template>
+ );
+
+ assert.dom(".legacy").hasText("Legacy");
+ assert.true(
+ this.consoleWarnStub.calledWithMatch(
+ /Use modern-name instead of legacy-name/
+ )
+ );
+ });
+
+ test("non-deprecated alias does not emit warnings", async function (assert) {
+ extraConnectorComponent(
+ "alternate-name",
+ <template>
+ <span class="alt">Alt</span>
+ </template>
+ );
+
+ await render(
+ <template>
+ <PluginOutlet
+ @name="primary-name"
+ @aliases={{array "alternate-name"}}
+ />
+ </template>
+ );
+
+ assert.dom(".alt").hasText("Alt");
+ assert.strictEqual(
+ this.consoleWarnStub.callCount,
+ 0,
+ "no warnings emitted"
+ );
+ });
+
+ test("wrapper outlet aliases resolve __before and __after connectors", async function (assert) {
+ extraConnectorComponent(
+ "old-wrapper__before",
+ <template>
+ <span class="alias-before">Before from alias</span>
+ </template>
+ );
+ extraConnectorComponent(
+ "old-wrapper__after",
+ <template>
+ <span class="alias-after">After from alias</span>
+ </template>
+ );
+
+ await render(
+ <template>
+ <PluginOutlet @name="new-wrapper" @aliases={{array "old-wrapper"}}>
+ <span class="wrapped">Wrapped content</span>
+ </PluginOutlet>
+ </template>
+ );
+
+ assert.dom(".alias-before").hasText("Before from alias");
+ assert.dom(".wrapped").hasText("Wrapped content");
+ assert.dom(".alias-after").hasText("After from alias");
+ });
+
+ test("@deprecated emits warning when connectors exist", async function (assert) {
+ extraConnectorComponent(
+ "doomed-outlet",
+ <template>
+ <span class="doomed">Doomed</span>
+ </template>
+ );
+
+ await render(
+ <template>
+ <PluginOutlet
+ @name="doomed-outlet"
+ @deprecated={{hash since="4.0"}}
+ />
+ </template>
+ );
+
+ assert.dom(".doomed").hasText("Doomed");
+ assert.true(
+ this.consoleWarnStub.calledWithMatch(
+ /Plugin outlet "doomed-outlet" is deprecated/
+ )
+ );
+ });
+
+ test("@deprecated does not emit warning when no connectors exist", async function (assert) {
+ await render(
+ <template>
+ <PluginOutlet
+ @name="doomed-outlet"
+ @deprecated={{hash since="4.0"}}
+ />
+ </template>
+ );
+
+ assert.false(
+ this.consoleWarnStub.calledWithMatch(/doomed-outlet/),
+ "no deprecation warning emitted"
+ );
+ });
+
+ test("@deprecated uses custom message", async function (assert) {
+ extraConnectorComponent(
+ "old-outlet",
+ <template>
+ <span class="old-outlet">Old</span>
+ </template>
+ );
+
+ await render(
+ <template>
+ <PluginOutlet
+ @name="old-outlet"
+ @deprecated={{hash
+ since="4.0"
+ message="This outlet will be removed. Use the Block API."
+ }}
+ />
+ </template>
+ );
+
+ assert.dom(".old-outlet").hasText("Old");
+ assert.true(
+ this.consoleWarnStub.calledWithMatch(
+ /This outlet will be removed\. Use the Block API\./
+ )
+ );
+ });
+
+ test("multiple aliases on same outlet", async function (assert) {
+ extraConnectorComponent(
+ "alias-one",
+ <template>
+ <span class="one">One</span>
+ </template>
+ );
+ extraConnectorComponent(
+ "alias-two",
+ <template>
+ <span class="two">Two</span>
+ </template>
+ );
+
+ await render(
+ <template>
+ <PluginOutlet
+ @name="target-outlet"
+ @aliases={{array "alias-one" "alias-two"}}
+ />
+ </template>
+ );
+
+ assert.dom(".one").hasText("One");
+ assert.dom(".two").hasText("Two");
+ });
+
+ test("file-based connectors under alias name render in canonical outlet", async function (assert) {
+ registerTemporaryModule(
+ `${TEMPLATE_PREFIX}/old-file-outlet/my-connector`,
+ hbs`<span class="file-alias">File-based alias connector</span>`
+ );
+
+ await render(
+ <template>
+ <PluginOutlet
+ @name="new-file-outlet"
+ @aliases={{array "old-file-outlet"}}
+ />
+ </template>
+ );
+
+ assert.dom(".file-alias").hasText("File-based alias connector");
+ });
+
+ test("connectorsExist returns true when connectors exist only under alias", async function (assert) {
+ extraConnectorComponent(
+ "only-alias-outlet",
+ <template>
+ <span class="only-alias">Only alias</span>
+ </template>
+ );
+
+ await render(
+ <template>
+ <PluginOutlet
+ @name="empty-canonical"
+ @aliases={{array "only-alias-outlet"}}
+ >
+ <span class="default">Default content</span>
+ </PluginOutlet>
+ </template>
+ );
+
+ assert.dom(".only-alias").hasText("Only alias");
+ assert.dom(".default").doesNotExist();
+ });
+
+ test("mixed deprecated and non-deprecated aliases", async function (assert) {
+ extraConnectorComponent(
+ "deprecated-alias",
+ <template>
+ <span class="dep">Deprecated</span>
+ </template>
+ );
+ extraConnectorComponent(
+ "active-alias",
+ <template>
+ <span class="active">Active</span>
+ </template>
+ );
+
+ await render(
+ <template>
+ <PluginOutlet
+ @name="main-outlet"
+ @aliases={{array
+ (hash name="deprecated-alias" deprecated=true since="4.0")
+ "active-alias"
+ }}
+ />
+ </template>
+ );
+
+ assert.dom(".dep").hasText("Deprecated");
+ assert.dom(".active").hasText("Active");
+ assert.true(
+ this.consoleWarnStub.calledWithMatch(/deprecated-alias/),
+ "deprecated alias emits warning"
+ );
+ assert.false(
+ this.consoleWarnStub.calledWithMatch(/active-alias/),
+ "non-deprecated alias does not emit warning"
+ );
+ });
+
+ test("DEBUG assertion: alias with deprecation properties but no deprecated flag", function (assert) {
+ assert.throws(
+ () => {
+ const aliases = [{ name: "bad-alias", since: "4.0" }];
+ // Trigger normalization
+ aliases.map(normalizeAlias);
+ },
+ /has deprecation properties.*but `deprecated` is not true/,
+ "throws when alias has since without deprecated=true"
+ );
+ });
+
+ test("DEBUG assertion: alias with invalid position value", function (assert) {
+ assert.throws(
+ () => normalizeAlias({ name: "bad-pos", position: "middle" }),
+ /invalid position "middle"/,
+ "throws for invalid position value"
+ );
+ });
+
+ test("position='after' routes alias connectors to wrapper __after outlet", async function (assert) {
+ extraConnectorComponent(
+ "old-standalone-outlet",
+ <template>
+ <span class="from-old-standalone">Old standalone</span>
+ </template>
+ );
+
+ await render(
+ <template>
+ <PluginOutlet
+ @name="new-wrapper-outlet"
+ @aliases={{array
+ (hash
+ name="old-standalone-outlet"
+ position="after"
+ deprecated=true
+ since="4.0"
+ )
+ }}
+ >
+ <span class="wrapped">Wrapped content</span>
+ </PluginOutlet>
+ </template>
+ );
+
+ assert.dom(".wrapped").hasText("Wrapped content");
+ assert.dom(".from-old-standalone").hasText("Old standalone");
+ });
+
+ test("position='before' routes alias connectors to wrapper __before outlet", async function (assert) {
+ extraConnectorComponent(
+ "old-above-outlet",
+ <template>
+ <span class="from-old-above">Old above</span>
+ </template>
+ );
+
+ await render(
+ <template>
+ <PluginOutlet
+ @name="new-wrapper-outlet"
+ @aliases={{array (hash name="old-above-outlet" position="before")}}
+ >
+ <span class="wrapped">Wrapped content</span>
+ </PluginOutlet>
+ </template>
+ );
+
+ assert.dom(".wrapped").hasText("Wrapped content");
+ assert.dom(".from-old-above").hasText("Old above");
+ });
+
+ test("position-targeted alias does not render in main outlet", async function (assert) {
+ extraConnectorComponent(
+ "targeted-alias",
+ <template>
+ <span class="targeted">Targeted</span>
+ </template>
+ );
+
+ await render(
+ <template>
+ <PluginOutlet
+ @name="standalone-outlet"
+ @aliases={{array (hash name="targeted-alias" position="after")}}
+ />
+ </template>
+ );
+
+ assert.dom(".targeted").doesNotExist();
+ });
+
+ test("position-targeted alias with connectorTagName preserves wrapper element", async function (assert) {
+ registerTemporaryModule(
+ `${TEMPLATE_PREFIX}/old-tagged-outlet/my-connector`,
+ hbs`<span class="legacy-content">Legacy connector</span>`
+ );
+
+ await render(
+ <template>
+ <PluginOutlet
+ @name="new-wrapper-with-tag"
+ @aliases={{array
+ (hash
+ name="old-tagged-outlet"
+ position="after"
+ connectorTagName="span"
+ )
+ }}
+ >
+ <span class="wrapped">Wrapped</span>
+ </PluginOutlet>
+ </template>
+ );
+
+ assert.dom(".wrapped").hasText("Wrapped");
+ assert.dom(".legacy-content").hasText("Legacy connector");
+ const wrapper = find(".legacy-content").parentElement;
+ assert.strictEqual(
+ wrapper.tagName,
+ "SPAN",
+ "legacy connector is wrapped in a <span> from connectorTagName"
+ );
+ });
+
+ test("position-targeted alias without connectorTagName renders tagless", async function (assert) {
+ registerTemporaryModule(
+ `${TEMPLATE_PREFIX}/old-tagless-outlet/my-connector`,
+ hbs`<span class="tagless-content">Tagless connector</span>`
+ );
+
+ await render(
+ <template>
+ <PluginOutlet
+ @name="new-wrapper-tagless"
+ @aliases={{array (hash name="old-tagless-outlet" position="after")}}
+ >
+ <span class="wrapped">Wrapped</span>
+ </PluginOutlet>
+ </template>
+ );
+
+ assert.dom(".wrapped").hasText("Wrapped");
+ assert.dom(".tagless-content").hasText("Tagless connector");
+ });
+
+ test("position-targeted alias with deprecation emits warning", async function (assert) {
+ extraConnectorComponent(
+ "old-below-outlet",
+ <template>
+ <span class="old-below">Old below</span>
+ </template>
+ );
+
+ await render(
+ <template>
+ <PluginOutlet
+ @name="wrapper-outlet"
+ @aliases={{array
+ (hash
+ name="old-below-outlet"
+ position="after"
+ deprecated=true
+ since="4.0"
+ )
+ }}
+ >
+ <span class="wrapped">Content</span>
+ </PluginOutlet>
+ </template>
+ );
+
+ assert.dom(".old-below").hasText("Old below");
+ assert.true(
+ this.consoleWarnStub.calledWithMatch(/old-below-outlet/),
+ "deprecated position alias emits warning"
+ );
+ });
+ }
+);