Modernizando tags de script inline para templates e API JS

[david (David Taylor)]

O uso de <script type='text/discourse-plugin'> ou <script type='text/x-handlebars'> em temas está agora obsoleto. Qualquer uso dessas tags em temas deve ser atualizado de acordo com as instruções abaixo.

<script> e <script type='text/javascript'> regulares não são afetados por esta mudança.

Cronograma

Estas são estimativas aproximadas, sujeitas a alterações

• Maio de 2025 - Mensagens de depreciação no console ativadas

• Julho de 2025 - Banners de aviso para administradores ativados

• Final de setembro de 2025 Março de 2026 - remoção do recurso

Convertendo <script type='text/x-handlebars'>

Os templates introduzidos com este método devem ser movidos para arquivos .hbs dedicados, ou reestruturados para arquivos gjs.

Para manter como HBS, os templates de conectores podem ser colocados em:

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

e os templates de componentes podem ser colocados em:

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

Desde março de 2026, os arquivos .hbs também estão obsoletos. Após fazer esta conversão, prossiga para as instruções em Deprecating .hbs file extension in themes and plugins

Para construir conectores e componentes no formato moderno .gjs, consulte este capítulo do tutorial do desenvolvedor 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…

Convertendo <script type='text/discourse-plugin'>

O código dentro dessas tags pode ser migrado para um arquivo JavaScript dedicado.

Se você desenvolve seu tema através da interface do painel de administração, copie o código do <script>, e mova-o para a aba JS (onde está escrito // your code here).

Se você desenvolve seu tema localmente, crie um novo arquivo em

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

então adicione este wrapper, e coloque seu código no local indicado:

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

export default apiInitializer((api) => {
  // Seu código aqui
});

Em tags script, a única maneira de importar outros módulos JS era usando a sintaxe require(). Embora isso ainda funcione em um arquivo .js, em breve ficará obsoleto, então agora seria um bom momento para convertê-lo para imports ES6 modernos. Por exemplo:

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

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

Para mais informações sobre 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]

Talvez uma pergunta muito idiota, mas tenho um componente de tema muito, muito simples que coloquei diretamente no console de administração em \u003chead\u003e:

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

Se eu estiver seguindo este post corretamente, isso significa que agora terei que criar uma pasta de componente de tema separada, hospedá-la no GitHub e adicionar o componente apenas para algo tão simples quanto adicionar a um plugin outlet?

Espero que não, pois isso quebrará a maioria dos meus componentes de tema simples

[NateDhaliwal]

Agora existe a aba JS, então você provavelmente pode usar api.renderInOutlet agora.

[jimkleiber]

@NateDhaliwal

a guia JS agora, então você provavelmente pode usar api.renderInOutlet agora.

@david

Se você desenvolver seu tema através da interface do painel de administração, copie o código de \u003cscript\u003e e mova-o para a guia JS (onde diz // seu código aqui).

Ah, eu não tinha visto que isso era possível de fazer com conectores/componentes também, mas no artigo vinculado encontrei isso:

@system

O componente mais simples é um “componente apenas de template”, e pode ser criado assim:

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

// Ou em uma linha
api.renderInOutlet("some-outlet", \u003ctemplate\u003eHello World\u003c/template\u003e);

Talvez mais fácil do que eu pensava, obrigado!

[Sujeeva_Tissaarachchi]

Obrigado por esta postagem!
Pode ser uma pergunta muito básica, acredito:
Como não temos um sandbox, preciso ter certeza antes de prosseguir.
Preciso atualizar um tema afetado, então estou correto se disser que todo o código relacionado a "Script" da aba "head" precisa ser movido para a aba JS, como ilustrado abaixo:

[NateDhaliwal]

Quase, mas não exatamente. Você gostaria de remover as tags de script e alterar as importações para algo como:

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

Em seguida, cole tudo isso na aba JS, dentro de:

@david

export default apiInitializer((api) => {
  // Seu código aqui
});

[BradCray (Brad Chamberlain)]

Nosso site Discourse (hospedado pelo Discourse) está atualmente gerando a seguinte barra de erro (que é o que me levou a este tópico):

Não estou ciente de que tenhamos feito qualquer personalização do tema ‘Light’ por conta própria e, olhando sua página de administração, não vejo nada que sugira que isso seja mais do que o padrão fornecido pelo sistema (mas posso facilmente estar perdendo algo).

Para um site hospedado como o nosso, isso provavelmente se resolverá com o tempo ou requer alguma ação da nossa parte?

Obrigado,
-Brad

[david (David Taylor)]

Você precisará tomar medidas para resolver isso - não vai desaparecer por conta própria.

Dei uma olhada rápida no seu site nas ferramentas de desenvolvedor do Chrome, e parece que o código relevante está relacionado à adição do idioma ‘chapel’ ao highlightjs.

Se você visitar seu tema ‘Light’ e clicar em ‘editar código’, você deverá ser capaz de encontrar isso em uma das abas HTML. Então você pode seguir as instruções no OP deste tópico para movê-lo para a aba ‘JS’.

[BradCray (Brad Chamberlain)]

Obrigado @david! Eu tinha me esquecido que tínhamos feito algumas personalizações para obter o destaque do Chapel e não tenho certeza se teria chegado lá sozinho a partir do banner de erro, então aprecio a ajuda e as dicas.

-Brad

[marco084]

Tenho um arquivo .html simples:

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

Estou um pouco confuso com as diferentes maneiras de fazer essa migração. Agradeceria se alguém explicasse o que fazer. Obrigado

[Lhc_fl (Linca)]

Apenas renderInOutlet para o 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]

Obrigado. Eu tentei e não funcionou

Esta é a minha estrutura e estas são

below-site-header.js

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

E below-siteheader-connectors.hbs

<div></div>

Sou novo nisso, então qualquer ajuda é apreciada. Peguei este repositório de um desenvolvedor anterior.

[NateDhaliwal]

Olá, você poderia compartilhar o link para o seu repositório do Github? Obrigado!

[Yuun (Sam)]

Então, eu colei meu pequeno script “aumentar-avatar” na aba JS (em Desktop - head), e isso funciona de forma bem simples, mas existe pelo menos uma maneira rápida e fácil de mantê-lo aplicado apenas no Desktop? Meus avatares mobile também estão grandes agora e tudo parece meio bobo.

O código de referência é:

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

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

[NateDhaliwal]

Hmm… talvez ajustar isso com CSS?

[Yuun (Sam)]

Isso resolveu perfeitamente, obrigado!

[Lhc_fl (Linca)]

Apenas um lembrete amigável: changeWidgetSetting em post-avatar é uma API obsoleta e será removida em breve.

Talvez você deva alterar seu código para isto

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]

Acho que também existe um componente de tema official para isso? Avatar Size and Shape

Não tenho certeza se ele se encaixa no caso de uso específico, mas parece que deveria (com o bônus adicional de que alguém o corrigirá se precisar ser atualizado )

[Yuun (Sam)]

Fiz o upgrade de quick 'n dirty para oficialmente suportado, obrigado a todos!

[ES-Alexander]

Observação para pessoas com componentes legados (que usam tratamento separado para Desktop/Mobile) que a guia JS está disponível apenas na seção Comum - espero que isso poupe a alguém algumas pesquisas