Utilizzo della JS API

[Discourse]

L’API JavaScript di Discourse consente a temi e plugin di apportare ampie personalizzazioni all’esperienza utente. Il modo più semplice per utilizzarla è creare un nuovo tema dal pannello di amministrazione, fare clic su “Modifica codice” e quindi accedere alla scheda JS.

Per i temi basati su file, l’API può essere utilizzata creando un file nella directory api-initializers. Per i temi è {theme}/javascripts/api-initializers/init-theme.gjs, e per i plugin è {plugin}/assets/javascripts/discourse/api-initializers/init-plugin.js. Il contenuto dovrebbe essere:

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

export default apiInitializer((api) => {
  // Il tuo codice qui
});

Tutte le API disponibili sono elencate nel codice sorgente di plugin-api.gjs nel core di Discourse, insieme a una breve descrizione ed esempi.

Per un tutorial completo, inclusi esempi di utilizzo dell’API JS, consulta:

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…

---

Questo documento è controllato tramite versione - suggerisci modifiche su 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

`

`

Questo è ora deprecato a partire da:

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

Aggiornato qui e in un sacco di altri documenti con controllo delle versioni. Grazie per la segnalazione @NateDhaliwal

[jenmck (jen)]

@Discourse

Tutte le API disponibili sono elencate nel codice sorgente di plugin-api.gjs in Discourse core, insieme a una breve descrizione ed esempi.

Questo link non funziona più, ricevo questo messaggio:

Il ramo main di discourse non contiene il percorso app/assets/javascripts/discourse/app/lib/plugin-api.gjs.

[NateDhaliwal]

Ah, questo perché i file javascript sono stati spostati nella directory frontend/ invece che in app/assets/javascripts/.

Ho aperto una PR:

Change app/assets/javascripts/ to frontend/

[NateDhaliwal]

Rilancio questa PR. Potrebbe essere revisionata? Grazie!