Usando a API JS

[Discourse]

A API JavaScript do Discourse permite que temas e plugins façam amplas personalizações na experiência do usuário. A maneira mais simples de usá-la é criar um novo tema no painel de administração, clicar em “Editar Código” e, em seguida, ir para a aba JS.

Para temas baseados em arquivos, a API pode ser usada criando um arquivo no diretório api-initializers. Para temas, é {theme}/javascripts/api-initializers/init-theme.gjs, e para plugins, é {plugin}/assets/javascripts/discourse/api-initializers/init-plugin.js. O conteúdo deve ser:

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

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

Todas as APIs disponíveis estão listadas no código-fonte plugin-api.gjs no núcleo do Discourse, juntamente com uma breve descrição e exemplos.

Para um tutorial completo, incluindo exemplos de uso da API JS, confira:

Theme Developer Tutorial: 1. Introduction

This tutorial will teach you how to create a Discourse Theme or Theme Component from the ground up. While this topic assumes no previous experience working on Discourse themes, it does assume some prior experience using HTML, CSS and JavaScript. It’ll also help if you know your way around GitHub. What are Discourse themes? A theme or theme component is a set of files packaged together designed to either modify Discourse visually or to add new features. Themes In general, themes are not suppo…

---

Este documento tem controle de versão - sugira alterações no github.

[DeanMarkTaylor (Dean Taylor)]

What’s the best way to “import” as a Site Customisation? - is it just to use require?

Whilst this works:

<script type="text/discourse-plugin" version="0.1">
var HamburgerMenuComponent = require('discourse/components/hamburger-menu').default;
</script>

This does not:

<script type="text/discourse-plugin" version="0.1">
import {default as HamburgerMenuComponent2 } from 'discourse/components/hamburger-menu';

</script>

Where I get this error:

<script type="text/discourse-js-error">unknown: 'import' and 'export' may only appear at the top level (3:0)
  1 | Discourse._registerPluginCode('0.1', api => {
  2 |   
> 3 | import {default as HamburgerMenuComponent2 } from 'discourse/components/hamburger-menu';
    | ^
  4 | 
  5 | 
  6 | }); at <eval>:8695:14</script>

[eviltrout (Robin Ward)]

Instead of importing it, you can look it up with

api.container.lookupFactory('component:hamburger-menu')

[Nuck (Emma Lejeck)]

Is there a way to get access to the h helper from virtual-dom in a site customization? I’m trying to add a simple dropdown widget to use in our header, and I can’t get that darned h, even though I can get createWidget

[Yuun (Sam)]

Does:

h = require('virtual-dom').h;

not work?

[Nuck (Emma Lejeck)]

@Yuun

Does:

h = require(‘virtual-dom’).h;

not work?

Yes it does! Works perfectly, thanks a ton!

[eviltrout (Robin Ward)]

I wouldn’t recommend doing it that way as it would likely break future compatibility. You can use this for now but I’ll try to introduce a workaround shortly that will be safer long term.

[Nuck (Emma Lejeck)]

@eviltrout

I wouldn’t recommend doing it that way as it would likely break future compatibility. You can use this for now but I’ll try to introduce a workaround shortly that will be safer long term.

Makes sense, it’s kinda circumventing the whole Plugin API thing and relying on implementation details of the ES6 compilation output, both things that are Dangerous™

Anyways, I’ll definitely keep an eye out for a better solution

[eviltrout (Robin Ward)]

I’ll try to get to it soon and I’ll reply in this topic, so watch it and you’ll see

[eviltrout (Robin Ward)]

Actually thinking about it, the decorateWidget helper gets called with an object that has the h method. How are you inserting your widget if not via a decorator?

If you could post code that would be helpful.

[Nuck (Emma Lejeck)]

@eviltrout

How are you inserting your widget if not via a decorator?

{{mount-widget}} in a template for a plugin outlet.

[eviltrout (Robin Ward)]

Ah that’s clever – I didn’t think people would try that. Okay, let me try something out.

[eviltrout (Robin Ward)]

Okay, I’ve added h to the pluginApi object as long as you request plugin api v0.3:

<script type="text/discourse-plugin" version="0.3">
  console.log(api.h('b', ['hello', 'world']));
</script>

That should work for you!

Add `h` helper to `plugin-api` in v0.3

[NateDhaliwal]

@Discourse

<script type="text/discourse-plugin" version="0.1">

Isso agora está obsoleto a partir de:

Modernizing inline script tags for templates & JS API

Using <script type='text/discourse-plugin> or <script type='text/x-handlebars'> in themes is now deprecated. Any use of these tags in themes should be updated according to the instructions below. Regular <script> and <script type='text/javascript'> are unaffected by this change. Timeline These are rough estimates, subject to change May 2025 - console deprecation messages enabled July 2025 - admin warning banners enabled Late September 2025 - removal of feature Converting <script ty…

[david (David Taylor)]

Atualizado aqui e em vários outros documentos com controle de versão. Obrigado pelo aviso, @NateDhaliwal

[jenmck (jen)]

@Discourse

Todas as APIs disponíveis estão listadas no código-fonte de plugin-api.gjs no core do Discourse, juntamente com uma breve descrição e exemplos.

Este link não está mais funcionando, recebo esta mensagem:

O branch main do discourse não contém o caminho app/assets/javascripts/discourse/app/lib/plugin-api.gjs.

[NateDhaliwal]

Ah, isso ocorre porque os arquivos javascript foram movidos para o diretório frontend/ em vez de app/assets/javascripts/.

Abri um PR:

Change app/assets/javascripts/ to frontend/

[NateDhaliwal]

Aumentando este PR. Poderia ser revisado? Obrigado!