Bevorstehende Änderungen bei Themen- und Plugin-Listen – wie man Themen und Plugins vorbereitet

[david (David Taylor)]

Im Rahmen unseres kontinuierlichen Bestrebens, die Rendering-Systeme in der gesamten Codebasis von Discourse zu standardisieren, ersetzen wir die Implementierung der Topic-Liste.

Zuvor wurde hierfür ein Ansatz mit „rohem Handlebars“ (.hbr) verwendet, der über Template-Overrides und Raw-Plugin-Outlets angepasst werden konnte. Die neue Implementierung der Topic-Liste verwendet moderne Glimmer-Komponenten und wurde von Grund auf so aufgebaut, dass sie auf nachhaltige Weise angepasst werden kann.

Die neue Implementierung ist nun hinter der Einstellung glimmer_topic_list_mode verfügbar.

• disabled: Verwendet die Legacy-Topic-Liste „rohes Handlebars“.
• auto: Erkennt die Kompatibilität Ihrer aktuellen Plugins und Themes. Wenn eines davon inkompatibel ist, wird das Legacy-System verwendet; andernfalls wird die neue Implementierung verwendet.
• enabled: Verwendet die neue Topic-Listen-Implementierung. Wenn Sie inkompatible Plugins oder Themes haben, kann Ihre Website beschädigt werden.

Wir haben die meisten unserer offiziellen Themes und Plugins bereits aktualisiert, um sie mit dem neuen Menü kompatibel zu machen. Wenn Sie jedoch Drittanbieter-Plugins, Themes oder Theme-Komponenten verwenden, die die Topic-Liste anpassen, müssen diese aktualisiert werden.

Warnungen werden in der Browserkonsole ausgegeben, die die Quelle der Inkompatibilität identifizieren.

Zeitplan für die Einführung

Dies sind grobe Schätzungen, die sich ändern können

Q4 2024:

• Kernimplementierung abgeschlossen
• Aktualisierung offizieller Themes/Plugins (in Arbeit)
• Aktiviert auf Meta
• Upgrade-Ratschläge veröffentlicht

Q1 2025:

• Aktualisierung offizieller Themes/Plugins

• glimmer_topic_list_mode standardmäßig auf auto gesetzt; Konsolen-Deprecations-Nachrichten aktiviert

• Deprecations lösen ein Admin-Warnbanner für verbleibende Probleme aus

• Drittanbieter-Plugins und Themes sollten aktualisiert werden

• 1. März – Aktivierung der neuen Topic-Liste für alle Websites. Der Standardwert für die Website-Einstellung wird auf enabled umgestellt, es wird jedoch weiterhin möglich sein, auf „disabled“ zurückzuschalten.

Q2 2025

• nach dem 1. April – endgültige Entfernung des Legacy-Modus und des zugehörigen Codes

Was bedeutet das für mich?

Wenn Ihr Plugin oder Theme „rohe Handlebars“-Dateien enthält (benannt .hbr oder .raw.hbs), müssen diese für die Kompatibilität mit der neuen Version aktualisiert werden. Reguläre .hbs-Dateien für Ember-Komponenten/Routen sind von dieser Änderung nicht betroffen.

Upgrades sind auch erforderlich, wenn Sie modifyClass für component:topic-list oder component:topic-list-item verwenden.

Wenn Ihre Website solche inkompatiblen Anpassungen aufweist, werden Warnmeldungen in der Entwicklerkonsole des Browsers ausgegeben, die Informationen darüber enthalten, welches Theme/Plugin die Ursache ist.

Was sind die Ersetzungen?

Einige der alten Raw-Plugin-Outlets wurden in reguläre Plugin-Outlets konvertiert. Diese können 1:1 aktualisiert werden.

Fortgeschrittenere Anpassungen müssen von Fall zu Fall bewertet werden. Die neue Topic-Liste verfügt über eine Reihe neuer APIs für einfache und robuste Anpassungen. Weitere Informationen finden Sie hier:

Customizing the topic list

The topic-list is one of the most-used and most-customized user-interfaces in Discourse. There are many different tools available to theme and plugin developers to achieve this customization, each with their own advantages, disadvantages and maintenance considerations. CSS-based Customization The safest and most common customization method is CSS. As with any other Discourse customization: the more complex your changes, the more maintenance is likely to be required in your theme or plugin. Gen…

Hier sind einige Beispiele:

• discourse-assign führt eine neue Spalte zu einer bestimmten Topic-Liste hinzu

• discourse-calendar verwendet eines der neuen Plugin-Outlets, um die Event-Datumsanzeige anzuzeigen

• discourse-solved verwendet einen neuen valueTransformer, um das vorherige modifyClass zu ersetzen

Was ist mit anderen Anpassungen?

Wenn Ihre Anpassung nicht mit den von uns eingeführten neuen APIs erreicht werden kann, teilen Sie uns dies bitte mit, indem Sie ein neues #dev-Thema zur Diskussion erstellen.

Ich bin ein Plugin-/Theme-Autor. Wie aktualisiere ich ein Theme/Plugin, um während des Übergangs sowohl die alte als auch die neue Topic-Liste zu unterstützen?

Die neuen Plugin-Outlets werden sowohl in der alten als auch in der neuen Implementierung der Topic-Liste gerendert. Wenn Sie also die neue implementiert haben, löschen Sie einfach den alten Raw-Plugin-Outlet-Connector.

Für DAG-basierte Anpassungen, die Template-Overrides oder nicht modernisierte Outlets ersetzen, müssen Sie während der Übergangszeit beide Implementierungen beibehalten.

Sobald Ihr Theme/Plugin sowohl die alte als auch die neue Implementierung unterstützt, können Sie diesen magischen Kommentar am Anfang aller Ihrer .hbr-Dateien hinzufügen:

{{!-- has-modern-replacement --}}

Dadurch werden die Deprecations-Nachrichten unterdrückt und die neue Implementierung kann im „auto“-Modus verwendet werden.

[pfaffman (Jay Pfaffman)]

@david

Wenn Ihr Plugin oder Theme über „Raw Handlebars“-Dateien verfügt (mit der Endung .hbr oder .raw.hbs), müssen diese für die Kompatibilität mit der neuen Version aktualisiert werden.

Entschuldigen Sie, dass ich pingelig bin, aber bedeutet das nicht eigentlich eher „wenn Ihr Plugin oder Theme über ‚Raw Handlebars‘-Dateien verfügt, die etwas mit der Topic-Liste zu tun haben, dann müssen diese aktualisiert werden“?

Meine Raw Handlebars-Dateien, die sich mit anderen Modellen befassen, werden weiterhin in Ordnung sein, oder? Oder werden Raw Handlebars-Dateien ganz abgeschafft? (Ich glaube, sie sind für zusätzliche Modelle/Routen erforderlich, oder?)

[david (David Taylor)]

„Raw handlebars“ bedeutet unsere Discourse-spezifischen Vorlagen mit der Dateiendung .hbr (oder historisch .raw.hbs). Wir haben dieses System nur für die Themenliste und einige interne „Autocomplete“-Funktionen verwendet.

Andere .hbs-Dateien (z. B. für Ember-Komponenten oder Routen) sind davon nicht betroffen.

Ich werde die OP aktualisieren, um das klarer zu machen. Danke, @pfaffman!

Bearbeiten: Hier ist es:

@david

Wenn Ihr Plugin oder Thema über „raw handlebars“-Dateien (benannt .hbr oder .raw.hbs) verfügt, müssen diese für die Kompatibilität mit der neuen Version aktualisiert werden. Normale .hbs-Dateien für Ember-Komponenten/Routen sind von dieser Änderung nicht betroffen.

[pfaffman (Jay Pfaffman)]

@david

„Raw handlebars“ bedeutet unsere Discourse-spezifischen Vorlagen, die die Dateiendung .hbr (oder historisch .raw.hbs) haben.

Oh. Du hast wirklich versucht, es klarzumachen. Du hast die Erweiterungen explizit angegeben. Ich glaube nicht, dass du es klarer machen kannst. Ich denke, das liegt an mir.

Aber vielleicht hätte der zusätzliche Satz mir geholfen, es lesen zu können.

[Don]

Danke für das Teilen. Ich habe das schon lange befürchtet und es kommt… Das wird wohl kein einfacher Lauf… Aber der Value Transformer wird es wahrscheinlich einfacher machen.

[merefield (Robert)]

Ich glaube, GitHub - discourse/discourse-topic-excerpts: Add topic excerpts to all topics in the topic list wurde noch nicht aktualisiert?

[david (David Taylor)]

Ja, wir haben noch viele offizielle Themes/Plugins, die auf ein Upgrade warten. Ich werde diesen Punkt in Q1 im OP erweitern

[merefield (Robert)]

Danke! Ich genieße die bisherige Entwicklererfahrung! Ich werde Sie wissen lassen, wenn TLP Probleme aufwirft, wenn ich dazu komme.

[david (David Taylor)]

Cool! Die offizielle topic-list-thumbnails ist eine derer, die wir mit dem Update fertiggestellt haben, daher könnte sie als nützliche Referenz dienen.

[david (David Taylor)]

@merefield

Ich glaube, GitHub - discourse/discourse-topic-excerpts: Fügt Themen-Auszüge zu allen Themen in der Themenliste hinzu wurde noch nicht aktualisiert?

@david

Yup, wir haben noch viele offizielle Themes/Plugins, die auf ein Upgrade warten

Oh, mein Fehler! @isaac hat topic-excerpts letzte Woche aktualisiert: DEV: Update plugin for `glimmer-topic-list` (#34) · discourse/discourse-topic-excerpts@0dd3c6c · GitHub

Es sollte also unter der neuen Themenliste gut funktionieren

[merefield (Robert)]

Ich erhalte:

Beide Versionen sind aktuell.

[merefield (Robert)]

@david

discourse-assign führt eine neue Spalte zu einer bestimmten Topic-Liste hinzu.

Wenn eine Spalte hinzugefügt wird, wie fügt man dann strategisch eine sortierbare Spaltenüberschrift hinzu?

indem man verwendet:

api.registerValueTransformer("topic-list-header-sortable-column"

zusätzlich zu den anderen Transformern?

      api.registerValueTransformer(
        "topic-list-columns",

scheint dies nicht von allein zu tun?

[david (David Taylor)]

@merefield

Ich bekomme:

cc @isaac. Wenn ich raten müsste: vielleicht muss die neue Logik aktualisiert werden, um nicht kategorisierte Themen zu behandeln?

@merefield

Was ist der strategische Weg, um eine sortierbare Spaltenüberschrift hinzuzufügen?

Der Transformer, den Sie gefunden haben, dient dazu, die Sortierbarkeit vorhandener Spalten zu überschreiben (z. B. tun wir dies in discourse-calendar, um zu verhindern, dass andere Sortiermethoden verwendet werden, wenn Sie sich in der chronologischen Themenansicht befinden).

Wenn Sie eine neue Spalte hinzufügen, dann sollten Sie Ihre Kopfzeile einfach mit der SortableColumn-Komponente definieren können. z. B. hier ist eine im Kern:

app/assets/javascripts/discourse/app/components/topic-list/header/activity-cell.gjs

app/assets/javascripts/discourse/app/components/topic-list/list.gjs

(Eine Sache, die an der neuen API wirklich schön ist, ist, dass alle Kernspalten mit derselben API definiert werden, die Sie aus Themes/Plugins verwenden!)

[merefield (Robert)]

@david

die Kernspalten werden mit derselben API definiert, die Sie von Themes/Plugins verwenden!

Ja, das ist mir bei einer Code-Suche aufgefallen, schön!

[isaac (Isaac Janzen)]

@david

cc @isaac. Wenn ich raten müsste: Vielleicht muss die neue Logik aktualisiert werden, um nicht kategorisierte Themen zu behandeln?

Fixed

[merefield (Robert)]

F: Ist es möglich, eine vollständige Komponente einer Zelle zuzuweisen, nicht nur eine <template>?

Was wäre zum Beispiel, wenn ich einen transparenten Button in einer Zelle anzeigen möchte, der eine minimale JavaScript-Logik erfordert?

[david (David Taylor)]

@merefield

F: Ist es möglich, eine vollständige Komponente einer Zelle zuzuweisen, nicht nur eine <template>?

Yup! Technisch gesehen erstellt ein bloßer <template>-Tag technisch gesehen eine „Nur-Vorlage-Komponente“. Ähnlich wie die Art von Komponente, die Sie erhalten, wenn Sie eine bloße .hbs-Datei im Verzeichnis components/ ablegen.

Daher ja, der Import und die Übergabe einer normalen Komponentenklasse funktionieren genauso. Es funktioniert sogar mit klassischen Komponenten! (obwohl wir natürlich die Verwendung der moderneren Glimmer-Komponenten empfehlen würden).

[merefield (Robert)]

Das ist absolut fantastisch!

Das ändert … sehr viel!

[merefield (Robert)]

Dumme Frage, vielleicht.

Aber wie wendet man Änderungen auf … mobile Themenliste an?

[david (David Taylor)]

Für Mobilgeräte gibt es eine Reihe neuer Plugin-Ausgänge (einschließlich Wrapper-Ausgänge).

Alternativ können Sie einen ValueTransformer verwenden, um die Desktop-Ansicht überall zu erzwingen (wir tun dies für Topic-Thumbnails).

Ich plane, nächste Woche eine detailliertere Dokumentation zum Thema „Anpassen der Themenliste“ zu schreiben (Documentation > Developer Guides), daher werde ich diese Informationen dort aufnehmen.