Wir haben kürzlich gearbeitet, um den Discourse-Header vom veralteten „Widget“-Rendering-System auf moderne Glimmer-Komponenten umzustellen. Diese Änderung ist jetzt im Discourse-Kern hinter der Site-Einstellung glimmer header mode verfügbar.
Grober Zeitplan
(sehr grobe Schätzungen – können in beide Richtungen angepasst werden)
Q1 2024:
-
Kern-Implementierung abgeschlossen und auf Meta aktiviert -
Upgrade-Empfehlungen veröffentlicht; Konsolen-Deprecation-Meldungen aktiviert
-
Arbeiten zur Aktualisierung aller offiziellen und Drittanbieter-Plugins/Themes beginnen
Q2 2024:
-
Beginn der standardmäßigen Aktivierung der neuen Header-Implementierung
-
Offizielle und Drittanbieter-Themes/Plugins sind für das Upgrade bereit
-
Deprecation-Meldungen lösen ab jetzt eine Warnbanner für Admins aus, falls noch Probleme bestehen
Q3 2024:
-
Ankündigungs-Topic für größere Sichtbarkeit veröffentlicht: Preparing your community for behind-the-scenes header changes
-
w/c 5. August 2024 (v3.4.0.beta1): Neuer Header standardmäßig für alle Sites aktiviert. Admins können weiterhin über die Site-Einstellung „glimmer header mode“ zum alten Header zurückkehren.
-
w/c 2. September 2024: endgültige Entfernung des Feature-Flags und des veralteten Codes
Was bedeutet das für mich?
Wenn dein Plugin oder Theme „Widget“-APIs zur Anpassung des Headers verwendet, müssen diese für Kompatibilität mit dem neuen Header aktualisiert werden.
Wie teste ich den neuen Header?
In der neuesten Version von Discourse wird der neue Header automatisch aktiviert, sobald alle deine Themes/Plugins kompatibel sind.
Sind deine Themes/Plugins nicht kompatibel, wird weiterhin der veraltete Header verwendet. Eine Warnung wird zusammen mit den bestehenden Deprecation-Meldungen in der Konsole ausgegeben. Zudem wird Admins im UI ein Warnbanner angezeigt.
Für den unwahrscheinlichen Fall, dass dieses automatische System nicht wie erwartet funktioniert, kannst du dieses „automatische Feature-Flag“ vorübergehend über die Site-Einstellung glimmer header mode überschreiben. Bitte teile uns in diesem Topic den Grund mit, falls du das tust.
Muss ich mein Plugin/Theme aktualisieren?
Um festzustellen, ob deine Anpassung aktualisiert werden muss, prüfe, ob sie decorateWidget, changeWidgetSetting, reopenWidget oder attachWidgetAction auf einem der folgenden Widgets verwendet:
- header
- site-header
- header-contents
- header-buttons
- user-status-bubble
- sidebar-toggle
- header-icons
- header-topic-info
- header-notifications
- home-logo
- user-dropdown
oder eine dieser Plugin-API-Methoden:
addToHeaderIconsaddHeaderPanel
All dies führt nun dazu, dass Deprecation-Meldungen in der Konsole ausgegeben werden. Die Deprecation-IDs lauten:
discourse.add-header-paneldiscourse.header-widget-overrides
Wenn du in deiner Instanz mehr als ein Theme verwendest, prüfe bitte alle davon.
Admin-Hinweis
Seit dem 20. Juni 2024 haben wir den Admin-Hinweis für die oben genannten Deprecations aktiviert.
Wenn deine Instanz nach diesem Datum bereitgestellt wurde und deine aktuellen Plugins, Themes oder Theme-Komponenten eine der Deprecation-Warnungen auslösen, wird folgende Nachricht nur für Admins* angezeigt:
Diese Meldung dient lediglich dazu, Admins darauf hinzuweisen, dass sie bald handeln müssen, um die betroffenen Anpassungen zu modernisieren: Die alten Anpassungen funktionieren weiterhin, bis wir die veraltete Codebasis entfernen.
Was sind die Ersatzlösungen?
Jedes Theme/Plugin ist anders, aber hier finden Sie Hinweise für die häufigsten Anwendungsfälle:
addToHeaderIcons
Für benutzerdefinierte Header-Symbole empfehlen wir, deinen Code zu entfernen und die offizielle Custom Header Links (Icons) Theme Component zu installieren. Wenn dies deine Anforderungen nicht erfüllt, siehe unten für Details zu den erforderlichen Code-Änderungen:
Die Plugin-API addToHeaderIcons wurde zugunsten der neuen headerIcons-API veraltet. Sie dient dem Hinzufügen, Entfernen oder Neuordnen von Symbolen im Header. Dabei muss eine Komponente übergeben werden.
Die Komponente kann wie folgt übergeben werden:
| Vorher | Nachher |
|---|---|
| api.addToHeaderIcons(“widget-foo”) | api.headerIcons.add(“foo”, FooIcon) |
| api.decorateWidget(“header-icons:before”, () => return helper.h(“div”, “widget-foo”)) | api.headerIcons.add(“foo”, FooIcon, { before: “search” }) |
| api.decorateWidget(“header-icons:after”, () => return helper.h(“div”, “widget-foo”)) | api.headerIcons.add(“foo”, FooComponent, { after: “search” }) |
Dieses Beispiel verwendet Embers Template Tag Format (gjs), um eine Komponente inline zu definieren und an die headerButtons.add-API zu übergeben:
// .../discourse/api-initializers/add-my-button.gjs
import DButton from "discourse/components/d-button";
import { apiInitializer } from "discourse/lib/api";
export default apiInitializer("1.0", (api) => {
api.headerIcons.add("some-unique-name", <template>
<li><DButton class="icon btn-flat" @href="/u" @icon="address-book" /></li>
</template>);
});
Oder für ein Dropdown-Menü kannst du <DMenu anstelle von <DButton verwenden:
import DButton from "discourse/components/d-button";
import { apiInitializer } from "discourse/lib/api";
import DMenu from "float-kit/components/d-menu";
export default apiInitializer("1.0", (api) => {
api.headerIcons.add("some-unique-name", <template>
<li>
<DMenu class="icon btn-flat" @icon="address-book">
<DButton @translatedLabel="User 1" @href="/u/user1" />
<DButton @translatedLabel="User 2" @href="/u/user2" />
<DButton @translatedLabel="User 3" @href="/u/user3" />
</DMenu>
</li>
</template>);
});
Beispiel-Upgrade-Commits:
discourse-icon-header-linksdecorateWidget("header-buttons:*")
Das Widget header-buttons wurde veraltet und wir haben eine neue Plugin-API headerButtons eingeführt. Sie dient dem Hinzufügen, Entfernen oder Neuordnen von Buttons im Header. Dabei muss eine Komponente übergeben werden.
| Vorher | Nachher |
|---|---|
| api.decorateWidget(“header-buttons:before”) | api.headerButtons(“button-name”, ButtonComponent, { before: “auth” }) |
| api.decorateWidget(“header-buttons:after”) | api.headerButtons(“button-name”, ButtonComponent, { after: “auth” }) |
changeWidgetSetting(...) für die Header-Widgets
changeWidgetSettingkönnen mit folgenden Theme-Komponenten erreicht werden:Wenn diese nicht deinem Anwendungsfall entsprechen, lies weiter…
Einige Anpassungen an den Header-Widgets nutzten die changeWidgetSetting-API.
Obwohl es keinen direkten Ersatz für Anpassungen wie die oben genannten gibt, haben wir aufgrund der Funktionsweise der Glimmer-Komponenten-Felder in Discourse 3.3.0.beta3 eine neue Plugin-API eingeführt, um einige dieser Fälle zu behandeln.
registerValueTransformer kann verwendet werden, um Werte zu überschreiben, die im Quellcode als überschreibbar markiert wurden. Dies ist ein ähnlicher Ansatz wie bei Plugin-Outlets.
Wir haben bereits zwei Transformer für die in unserem Quellcode häufigsten Anwendungsfälle hinzugefügt:
-
home-logo-href: Kann verwendet werden, um die URL im Home-Logo-Link zu überschreiben. Siehe den Abschnitthome-logounten für Beispiele. -
header-notifications-avatar-size: Kann verwendet werden, um die Größe des im Header angezeigten Benutzer-Avatars zu ändern. Beispiel:
Der folgende Code:
api.changeWidgetSetting(
"header-notifications",
"avatarSize",
settings.header_avatars_size
);
Würde umgewandelt zu:
api.registerValueTransformer(
"header-notifications-avatar-size",
() => settings.header_avatars_size
);
Diese Transformer müssen zum Discourse-Quellcode hinzugefügt werden. Falls du einen anderen benötigst, teile uns deinen Anwendungsfall unten mit.
Weitere Details zu den neuen Value-Transformer-APIs findest du hier.
home-logo
Wir haben einen home-logo Plugin-Outlet als Ersatz für home-logo:before oder home-logo:after Widget-Decorations eingeführt. Du kannst die automatische Benennung mit __before und __after in deiner Connector-Datei verwenden, um festzulegen, wo dein benutzerdefinierter Inhalt platziert werden soll.
Weitere Details zur Benennung von Connector-Dateien für Before/After findest du hier.
| Vorher | Nachher |
|---|---|
| api.decorateWidget(“home-logo:before”) | Inhalt nach /connectors/home-logo__before verschieben |
| api.decorateWidget(“header-buttons:after”) | Inhalt nach /connectors/home-logo__after verschieben |
Ändern der Home-Logo-Link-URL:
Ein sehr häufiger Bedarf ist die Änderung der URL, auf die das home-logo verlinkt. Wir haben den Value-Transformer home-logo-href eingeführt, um dies zu ermöglichen. Beispiele:
-
Um den Link auf eine statische URL zu ändern
api.registerValueTransformer("home-logo-href", () => "https://example.com"); -
Um eine dynamische URL basierend auf dem aktuellen Benutzer zurückzugeben
api.registerValueTransformer("home-logo-href", () => { const currentUser = api.getCurrentUser(); return `https://example.com/${currentUser.username}`; }); -
Um eine URL basierend auf einer Theme-Component-Einstellung zurückzugeben
api.registerValueTransformer("home-logo-href", () => { return settings.example_logo_url_setting; });
Was ist mit anderen Anpassungen?
Wenn deine Anpassung nicht mit CSS, Plugin-Outlets oder den neuen APIs erreicht werden kann, die wir eingeführt haben, lass es uns bitte wissen, indem du ein neues #dev-Topic erstellst, um dies zu diskutieren.
Wie aktualisiere ich ein Theme/Plugin, um sowohl den alten als auch den neuen Header zu unterstützen?
Alle neuen APIs und Plugin-Outlets, die in diesem Dokument aufgeführt sind, werden sowohl vom neuen als auch vom alten Header unterstützt. Du musst also nur einmal dein Theme/Plugin aktualisieren, und die Benutzer sind bereit für den Wechsel.
Heute haben wir 
stimmt, und ich war begieriger zu lernen, ehrgeiziger, fühlte das lohnenswertere, wurde seitdem geschlagen, überfahren und für tot erklärt
und wieder schätze ich jede Hilfe, die andere anbieten können.
