Utilisation de l'API JS

[Discourse]

L’API JavaScript de Discourse permet aux thèmes et aux plugins d’apporter des personnalisations étendues à l’expérience utilisateur. La manière la plus simple de l’utiliser consiste à créer un nouveau thème depuis le panneau d’administration, à cliquer sur « Modifier le code », puis à accéder à l’onglet JS.

Pour les thèmes basés sur des fichiers, l’API peut être utilisée en créant un fichier dans le répertoire api-initializers. Pour un thème, il s’agit de {theme}/javascripts/api-initializers/init-theme.gjs, et pour un plugin, de {plugin}/assets/javascripts/discourse/api-initializers/init-plugin.js. Le contenu doit être le suivant :

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

export default apiInitializer((api) => {
  // Votre code ici
});

Toutes les API disponibles sont répertoriées dans le code source de plugin-api.gjs du noyau de Discourse, accompagnées d’une brève description et d’exemples.

Pour un tutoriel complet, incluant des exemples d’utilisation de l’API JS, consultez :

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…

---

Ce document est sous contrôle de version - proposez des modifications sur 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!

https://github.com/discourse/discourse/commit/b10b6c673d5f4936d0ee107e16531df106fae75e

[NateDhaliwal]

@Discourse

`

`

Ceci est maintenant obsolète à 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)]

Mis à jour ici, et dans un tas d’autres documents avec gestion de version. Merci de l’info @NateDhaliwal

[jenmck (jen)]

@Discourse

Toutes les API disponibles sont listées dans le code source de plugin-api.gjs de Discourse core, avec une courte description et des exemples.

Ce lien ne fonctionne plus, j’obtiens ce message :

La branche main de discourse ne contient pas le chemin app/assets/javascripts/discourse/app/lib/plugin-api.gjs.

[NateDhaliwal]

Ah, c’est parce que les fichiers javascript ont été déplacés dans le répertoire frontend/ au lieu de app/assets/javascripts/.

J’ai ouvert une PR :

Change app/assets/javascripts/ to frontend/

[NateDhaliwal]

Remontée de cette PR. Pourrait-elle être examinée ? Merci !

[MarkDoerr]

Fusionné en décembre.