Modernisierung von Inline-Script-Tags für Templates & JS API

[david (David Taylor)]

Die Verwendung von <script type='text/discourse-plugin'> oder <script type='text/x-handlebars'> in Themes ist jetzt veraltet. Jede Verwendung dieser Tags in Themes sollte gemäß den folgenden Anweisungen aktualisiert werden.

Reguläre <script> und <script type='text/javascript'> sind von dieser Änderung nicht betroffen.

Zeitplan

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

• Mai 2025 - Konsolen-Deprecation-Meldungen aktiviert

• Juli 2025 - Admin-Warnbanner aktiviert

• Ende September 2025 März 2026 - Entfernung der Funktion

Konvertierung von <script type='text/x-handlebars'>

Vorlagen, die mit dieser Methode eingeführt wurden, sollten in dedizierte .hbs-Dateien verschoben oder in .gjs-Dateien umstrukturiert werden.

Um bei HBS zu bleiben, können Connector-Vorlagen platziert werden in:

{theme}/javascripts/discourse/connectors/{outlet-name}/{connector-name}.hbs

und Komponenten-Vorlagen können platziert werden in:

{theme}/javascripts/discourse/components/{component-name}.hbs

Seit März 2026 sind auch .hbs-Dateien veraltet. Nachdem Sie diese Konvertierung vorgenommen haben, fahren Sie mit den Anweisungen unter Deprecating .hbs file extension in themes and plugins fort.

Um Connectors und Komponenten im modernen .gjs-Format zu erstellen, lesen Sie dieses Kapitel des Theme-Entwickler-Tutorials:

Theme Developer Tutorial: 4. Using Outlets to insert and replace content

Discourse uses the Ember JS Framework for its user interface. On top of Ember, Discourse provides a number of APIs to allow themes to customize the user interface. The most commonly-used API is Plugin Outlets. These outlets are positioned throughout Discourse core, and allow themes to render Ember Components inside them. Those components are given access to some contextual information called “outlet args”. Some outlets also “wrap” part of the core user interface, which allows themes to add the…

Konvertierung von <script type='text/discourse-plugin'>

Code in diesen Tags kann in eine dedizierte JavaScript-Datei migriert werden.

Wenn Sie Ihr Theme über die Admin-Panel-Oberfläche entwickeln, kopieren Sie den Code aus dem <script> und verschieben Sie ihn in die JS-Registerkarte (dort, wo // your code here steht).

Wenn Sie Ihr Theme lokal entwickeln, erstellen Sie eine neue Datei unter

{theme}/javascripts/discourse/api-initializers/init-theme.js

Fügen Sie dann diese Hüllfunktion hinzu und platzieren Sie Ihren Code an der angegebenen Stelle:

import { apiInitializer } from "discourse/lib/api";

export default apiInitializer((api) => {
  // Your code here
});

In Skript-Tags war die einzige Möglichkeit, andere JS-Module zu importieren, die require()-Syntax. Obwohl dies in einer .js-Datei weiterhin funktionieren wird, wird es bald veraltet sein. Es wäre also ein guter Zeitpunkt, es auf moderne ES6-Imports umzustellen. Zum Beispiel:

- const I18n = require("discourse-i18n").default;
+ import I18n from "discourse-i18n";

- const { h } = require("virtual-dom");
+ import { h } from "virtual-dom";

Weitere Informationen zu JS Initializern finden Sie unter:

Theme Developer Tutorial: 6. Using the JS API

In the last couple of chapters, we’ve explored how to use the JavaScript API to render content into outlets. renderInOutlet is the most commonly-used API, but there are a ton more! In this chapter we’ll try out a few of them, and show you how to discover more. Common API methods getCurrentUser() api.getCurrentUser() will return information about the current user, or null if nobody is logged in. This can be used for all sorts of things, including per-group logic, or rendering a user’s username i…

[jimkleiber]

Vielleicht eine sehr dumme Frage, aber ich habe eine sehr, sehr einfache Theme-Komponente, die ich direkt in die Admin-Konsole unter \u003chead\u003e eingefügt habe:

<script type="text/x-handlebars" data-template-name="/connectors/top-notices/whos-online-below-site-header">
{{whos-online}}
</script>

Wenn ich diesem Beitrag richtig folge, bedeutet das, dass ich jetzt einen separaten Theme-Komponenten-Ordner erstellen, ihn auf GitHub hosten und die Komponente hinzufügen muss, nur um etwas so Einfaches wie das Hinzufügen zu einem Plugin-Outlet zu tun?

Ich hoffe es nicht, da dies die meisten meiner einfachen Theme-Komponenten brechen würde

[NateDhaliwal]

Da es jetzt den JS-Tab gibt, können Sie wahrscheinlich api.renderInOutlet verwenden.

[jimkleiber]

@NateDhaliwal

Hier ist jetzt der JS-Tab, sodass Sie wahrscheinlich api.renderInOutlet verwenden können.

@david

Wenn Sie Ihr Theme über die Admin-Panel-Oberfläche entwickeln, kopieren Sie den Code aus dem <script> und verschieben Sie ihn in den JS-Tab (wo “// Ihr Code hier” steht).

Ah, ich hatte nicht gesehen, dass dies auch mit Connectors/Komponenten möglich ist, aber im verlinkten Artikel habe ich Folgendes gefunden:

@system

Die einfachste Komponente ist eine „nur-Template-Komponente“ und kann so erstellt werden:

const MyComponent = <template>Hallo Welt</template>;
api.renderInOutlet("some-outlet", MyComponent);

// Oder in einer Zeile
api.renderInOutlet("some-outlet", <template>Hallo Welt</template>);

Vielleicht einfacher als ich dachte, danke!

[Sujeeva_Tissaarachchi]

Vielen Dank für diesen Beitrag!
Vielleicht eine sehr grundlegende Frage, glaube ich:
Da wir keine Sandbox haben, muss ich sicher sein, bevor ich fortfahre.
Ich muss ein betroffenes Theme aktualisieren. Bin ich also richtig, wenn ich sage, dass der gesamte Code, der sich auf „Skript“ aus dem „Kopf“-Tab bezieht, in den JS-Tab verschoben werden muss, wie unten gezeigt:

[NateDhaliwal]

Fast, aber noch nicht ganz. Sie sollten die Skript-Tags entfernen und die Importe ändern in etwa so:

import { ajax } from "discourse/lib/ajax";

Fügen Sie dann alles hier in den JS-Tab ein, innerhalb von:

@david

export default apiInitializer((api) => {
  // Ihr Code hier
});

[BradCray (Brad Chamberlain)]

Unsere Discourse-Seite (gehostet von Discourse) generiert derzeit die folgende Fehlermeldung (was mich zu diesem Thread geführt hat):

Ich bin mir nicht bewusst, dass wir das ‘Light’-Theme selbst angepasst haben, und wenn ich mir die Admin-Seite ansehe, sehe ich nichts, was darauf hindeutet, dass es sich um mehr als die vom System bereitgestellte Standardeinstellung handelt (aber ich könnte leicht etwas übersehen).

Ist es wahrscheinlich, dass sich dies bei einer gehosteten Seite wie unserer im Laufe der Zeit von selbst löst, oder erfordert es eine Aktion von unserer Seite?

Danke,
-Brad

[david (David Taylor)]

Sie müssen Maßnahmen ergreifen, um dies zu beheben – es wird nicht von selbst verschwinden.

Ich habe mir Ihre Website kurz in den Chrome-Entwicklertools angesehen, und es sieht so aus, als ob der relevante Code mit dem Hinzufügen der Sprache „chapel“ zu highlightjs zusammenhängt.

Wenn Sie Ihr „Light“-Theme besuchen und auf „Code bearbeiten“ klicken, sollten Sie dies unter einem der HTML-Tabs finden. Dann können Sie die Anweisungen im OP dieses Themas befolgen, um es in den „JS“-Tab zu verschieben.

[BradCray (Brad Chamberlain)]

Danke @david! Ich hatte vergessen, dass wir einige Anpassungen vorgenommen hatten, um die Chapel-Hervorhebung zu erhalten, und ich bin mir nicht sicher, ob ich allein vom Fehlerbanner dorthin gelangt wäre. Daher schätze ich die Hilfe und die Hinweise.

-Brad

[marco084]

Ich habe eine einfache .html-Datei:

<script type='text/x-handlebars' data-template-name='/connectors/below-site-header/oprs-top-container'>
    <div id='WW_T_D_1' class='oprs-top-leaderboard'></div>
</script>

Ich bin etwas verwirrt über die verschiedenen Möglichkeiten, diese Migration durchzuführen. Ich wäre dankbar, wenn mir jemand erklären könnte, was zu tun ist. Danke

[Lhc_fl (Linca)]

Nur renderInOutlet an den Connector

import { apiInitializer } from "discourse/lib/api";

export default apiInitializer((api) => {
  api.renderInOutlet("below-site-header", <template>
    <div id='WW_T_D_1' class='oprs-top-leaderboard'></div>
  </template>);
});

[marco084]

Danke. Ich habe es versucht und es hat nicht funktioniert

Das ist meine Struktur und das sind

below-site-header.js

export function test() {
    let test2 = document.querySelector('.test');
    console.log('test ', test2);
}

Und below-siteheader-connectors.hbs

<div class="test"></div>

Ich bin neu hier, daher ist jede Hilfe willkommen. Ich habe dieses Repo von einem früheren Entwickler übernommen.

[NateDhaliwal]

Hallo, könnten Sie bitte den Link zu Ihrem Github-Repo teilen? Danke!

[Yuun (Sam)]

Ich habe also mein kleines „make-avatar-bigger“-Skript in den JS-Tab (aus Desktop – head) eingefügt, und das funktioniert einfach genug, aber gibt es zumindest eine schnelle und schmutzige Möglichkeit, es nur auf dem Desktop anzuwenden? Meine mobilen Avatare sind jetzt auch groß und das sieht alles ziemlich albern aus.

Der Code für die Referenz lautet:

import { apiInitializer } from "discourse/lib/api";

export default apiInitializer((api) => {
  api.changeWidgetSetting('post-avatar', 'size', '70');
});

[NateDhaliwal]

Hmm… vielleicht mit CSS anpassen?

[Yuun (Sam)]

Das hat perfekt funktioniert, danke!

[Lhc_fl (Linca)]

Nur eine freundliche Erinnerung: changeWidgetSetting auf post-avatar ist eine veraltete API und wird bald entfernt.

Vielleicht sollten Sie Ihren Code wie folgt ändern:

import { apiInitializer } from "discourse/lib/api";

export default apiInitializer((api) => {
  const site = api.container.lookup("service:site");
  if (!site.mobileView) {
    api.modifyClass("component:post/avatar", (SuperClass) =>
      class extends SuperClass {
        get size() {
          return "70";
        }
      }
    );
  }
});

[JammyDodger]

Ich glaube, es gibt auch eine #offizielle Theme-Komponente dafür? Avatar Size and Shape

Ich bin mir nicht sicher, ob sie für den speziellen Anwendungsfall passt, aber es scheint, als ob sie es sein sollte (mit dem zusätzlichen Bonus, dass jemand sie repariert, wenn sie aktualisiert werden muss )

[Yuun (Sam)]

Ich bin von “quick 'n dirty” auf offiziell unterstützt aufgerüstet, danke an alle!

[ES-Alexander]

Hinweis für Personen mit älteren Komponenten (die separate Desktop-/Mobilfunkbehandlung verwenden): Der JS-Tab ist nur im Abschnitt “Allgemein” verfügbar – hoffentlich erspart dies anderen einige Suchvorgänge