Modernizando etiquetas de script en línea para plantillas y API de JS

[david (David Taylor)]

El uso de <script type='text/discourse-plugin'> o <script type='text/x-handlebars'> en temas está ahora obsoleto. Cualquier uso de estas etiquetas en temas debe actualizarse siguiendo las instrucciones a continuación.

Los <script> y <script type='text/javascript'> regulares no se ven afectados por este cambio.

Cronología

Estas son estimaciones aproximadas, sujetas a cambios

• Mayo de 2025 - Habilitados los mensajes de obsolescencia en la consola

• Julio de 2025 - Habilitadas las pancartas de advertencia para administradores

• Finales de septiembre de 2025 Marzo de 2026 - Eliminación de la funcionalidad

Conversión de <script type='text/x-handlebars'>

Las plantillas introducidas con este método deben moverse a archivos .hbs dedicados, o refactorizarse a archivos .gjs.

Para mantenerlo como HBS, las plantillas de conector se pueden colocar en:

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

y las plantillas de componente se pueden colocar en:

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

Desde marzo de 2026, los archivos .hbs también están obsoletos. Después de realizar esta conversión, continúe con las instrucciones en Deprecating .hbs file extension in themes and plugins

Para crear conectores y componentes en el formato .gjs moderno, consulte este capítulo del tutorial para desarrolladores de temas:

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…

Conversión de <script type='text/discourse-plugin'>

El código dentro de estas etiquetas se puede migrar a un archivo JavaScript dedicado.

Si desarrolla su tema a través de la interfaz del panel de administración, copie el código de la etiqueta <script> y muévalo a la pestaña JS (donde dice // your code here).

Si desarrolla su tema localmente, cree un nuevo archivo en

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

luego agregue este contenedor y coloque su código en el lugar indicado:

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

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

En las etiquetas de script, la única forma de importar otros módulos de JS era usando la sintaxis require(). Aunque esto seguirá funcionando en un archivo .js, pronto será obsoleto, por lo que ahora sería un buen momento para convertirlo a importaciones ES6 modernas. Por ejemplo:

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

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

Para obtener más información sobre los inicializadores de JS:

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]

Quizás una pregunta muy tonta, pero tengo un componente de tema muy muy simple que puse directamente en la consola de administración bajo `

[NateDhaliwal]

Ahora está la pestaña JS, así que probablemente puedas usar api.renderInOutlet ahora.

[jimkleiber]

@NateDhaliwal

Aquí está la pestaña de JS ahora, así que probablemente puedas usar api.renderInOutlet ahora.

@david

Si desarrollas tu tema a través de la interfaz del panel de administración, copia el código de \u003cscript\u003e y muévelo a la pestaña JS (donde dice // tu código aquí).

Ah, no vi que esto también fuera posible con conectores/componentes, pero en el artículo vinculado encontré esto:

@system

El componente más simple es un “componente solo de plantilla”, y se puede crear así:

const MyComponent = \u003ctemplate\u003eHola Mundo\u003c/template\u003e;
api.renderInOutlet("some-outlet", MyComponent);

// O en una línea
api.renderInOutlet("some-outlet", \u003ctemplate\u003eHola Mundo\u003c/template\u003e);

¡Quizás sea más fácil de lo que pensaba, gracias!

[Sujeeva_Tissaarachchi]

¡Gracias por esta publicación!
Puede ser una pregunta muy básica, creo:
Dado que no tenemos un entorno de pruebas (sandbox), necesito estar seguro antes de continuar.
Tengo que actualizar un tema afectado, así que, ¿es correcto si digo que todo el código relacionado con “Script” de la pestaña “head” debe moverse a la pestaña JS, como se ilustra a continuación?

[NateDhaliwal]

Casi, pero no del todo. Querrás eliminar las etiquetas de script y cambiar las importaciones a algo como:

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

Luego, pega todo esto en la pestaña de JS, dentro de:

@david

export default apiInitializer((api) => {
  // Tu código aquí
});

[BradCray (Brad Chamberlain)]

Nuestro sitio de Discourse (alojado por Discourse) está generando actualmente la siguiente barra de error (que es lo que me llevó a este hilo):

No tengo conocimiento de que hayamos realizado ninguna personalización del tema ‘Light’ por nuestra cuenta, y al mirar su página de administración, no veo nada que sugiera que esto sea algo más que el valor predeterminado proporcionado por el sistema (pero podría estar pasando algo por alto fácilmente).

Para un sitio alojado como el nuestro, ¿es probable que se resuelva solo con el tiempo o requiere alguna acción por nuestra parte?

Gracias,
-Brad

[david (David Taylor)]

Deberás tomar medidas para resolver esto; no desaparecerá por sí solo.

Eché un vistazo rápido a tu sitio en las herramientas de desarrollador de Chrome y parece que el código relevante está relacionado con la adición del idioma ‘chapel’ a highlightjs.

Si visitas tu tema ‘Light’ y haces clic en ‘editar código’, deberías poder encontrarlo en una de las pestañas HTML. Luego puedes seguir las instrucciones del OP de este tema para moverlo a la pestaña ‘JS’.

[BradCray (Brad Chamberlain)]

¡Gracias @david! Había olvidado que habíamos hecho algunas personalizaciones para obtener el resaltado de Chapel y no estoy seguro de haber llegado por mi cuenta desde el banner de error, así que aprecio la ayuda y las indicaciones.

-Brad

[marco084]

Tengo un archivo .html simple:

<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>

Estoy algo confundido con las diferentes formas de hacer esta migración. Agradecería si alguien me explicara qué hacer. Gracias

[Lhc_fl (Linca)]

Solo renderInOutlet al conector

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]

Gracias. Lo intenté y no funcionó

Esta es mi estructura y estos son

below-site-header.js

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

Y below-siteheader-connectors.hbs

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

Soy nuevo en esto, así que cualquier ayuda es bienvenida. Tomé este repositorio de un desarrollador anterior.

[NateDhaliwal]

Hola, ¿podrías compartir el enlace a tu repositorio de Github? ¡Gracias!

[Yuun (Sam)]

Así que he pegado mi pequeño script “make-avatar-bigger” en la pestaña JS (desde Desktop - head), y eso funciona bastante simple, pero ¿hay al menos una forma rápida y sucia de mantenerlo aplicándose solo en Desktop? Mis avatares móviles también son ahora grandes y todo se ve bastante tonto.

El código de referencia es:

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

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

[NateDhaliwal]

Hmm… ¿quizás ajustar esto con CSS?

[Yuun (Sam)]

¡Eso funcionó perfectamente, gracias!

[Lhc_fl (Linca)]

Solo un recordatorio amistoso: changeWidgetSetting en post-avatar es una API obsoleta y se eliminará pronto.

Quizás deberías cambiar tu código a esto:

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]

Creo que también hay un componente de tema official para esto. Avatar Size and Shape

No estoy seguro de si se ajusta al caso de uso particular, pero parece que debería (con la ventaja adicional de que alguien lo arreglará si necesita actualizarse )

[Yuun (Sam)]

¡Me he actualizado de rápido y sucio a oficialmente compatible, gracias a todos!

[ES-Alexander]

Tenga en cuenta que para las personas con componentes heredados (que utilizan un manejo separado de escritorio/móvil) que la pestaña JS solo está disponible en la sección Común. ¡Espero que esto le ahorre a alguien más algunas búsquedas!