Développer les thèmes de discours et les composants du thème

Documentation Guides pour les développeurs
, ,
1

Discourse Themes and Theme Components can be used to customize the look, feel and functionality of Discourse’s frontend. This section of the developer guides aims to provide all the reference materials you need to develop simple themes for a single site, right up to complex open-source theme components.

This introduction aims to provide a map of all the tools and APIs for theme development. If you prefer a step-by-step tutorial for theme development, jump straight to:

Themes vs. Theme Components

Discourse Themes can be used to customize the frontend user experience using CSS and JavaScript. Each theme has its own git repository, and community admins can generally install and manage them via the Discourse admin panel, even on shared hosting platforms.

Theme Components are themes which are intended for use alongside other Theme Components, as part of an overall Theme. From a development point of view, Theme Components and Themes are almost identical. In these guides, the phrase “Theme” and “Theme Component” are used interchangeably.

Prerequisites

Firstly, make sure you understand how to use existing themes and theme components in Discourse. Using ready-made themes is the quickest and safest way to customize your community. If you need more, then it’s time to consider writing your own theme.

As part of Discourse’s overall architecture, Discourse Themes are built using standard HTML, CSS, JavaScript technologies, and make use of Ember concepts for more advanced UIs. These reference guides assume a base-level understanding of these technologies, and link out to external references where possible.

Discourse is a fast-moving project, and as such any custom theme will require maintenance over time. Make sure you consider this as part of your planning & development processes.

Getting Started

Frontend Customization

More!

Check out the rest of the Developer Guides !

This document is version controlled - suggest changes on github.

142 « J'aime »
136

De nombreux liens et références obsolètes et/ou erronés dans la section The PluginApi - modifyClass() section.

Ce fichier a tellement changé que checkReplyLength n’existe même plus…

Et plus loin dans la même section :

Ce lien aboutit simplement à une erreur « 404 - Page non trouvée »…

J’ai abandonné l’utilisation de cette documentation après cela…

4 « J'aime »
137

Un message a été divisé dans un nouveau sujet : Modèle ou widget de carte utilisateur ?

138

La documentation semble un peu obsolète sur ce point… (de plus, api.modifyClass se plaint d’un pluginId manquant). Comment puis-je exécuter un script lorsque about-page est chargé ? Celui-ci ne semble pas fonctionner (pas d’erreurs cependant). J’ai eu des résultats mitigés avec d’autres composants. Merci.

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

api.modifyClass("component:about-page", {
  pluginId: 'discourse-about-theme',

  didInsertElement() {
    this._super(...arguments);
    console.log("Welcome to the about page!");
  }

});

</script>
1 « J'aime »
139

Bonjour :wave: about-page est maintenant en .gjs, ce qui signifie également qu’il n’est plus modifiable de cette manière. Si vous souhaitez apporter des modifications, vous devez utiliser l’un des connecteurs disponibles sur cette page.

Vous pouvez les vérifier facilement avec Plugin outlet locations theme component ou vérifier dans le fichier \u003cPluginOutlet\u003e.

4 « J'aime »
142

Merci beaucoup. C’est logique. J’ai utilisé un connecteur à la place, cela fonctionne bien.

2 « J'aime »
143

Ce guide est-il encore exact ? J’ai lu l’intégralité du guide pour essayer de créer un composant de thème, puis j’ai examiné les exemples de composants de thème et aucun d’entre eux n’utilise les instructions qu’ils sont censés utiliser. Par exemple, en examinant le composant de thème discourse-brand-header, il semble qu’il ait été refactorisé, passant de l’utilisation de choses comme api.createwidget dans header.html à l’utilisation d’un code totalement différent avec des initialiseurs, des composants, etc. Un code extrêmement complexe. Le guide parle de l’utilisation de la méthode API avec des widgets, mais ce n’est pas du tout ce que tous les composants utilisent. Existe-t-il un guide mis à jour ou quelque chose pour utiliser les composants ?

Modification : Le site prétend que l’API des widgets disparaît, mais existe-t-il des guides sur ce qu’il faut utiliser à la place ? L’intégralité du guide ici semble être basée sur du code obsolète ?

3 « J'aime »
144

C’est vrai. Le guide devrait être mis à jour. Cependant, certaines parties sont toujours très pertinentes, comme la structure des fichiers, etc.

2 « J'aime »
145

Oui, il semble que SCSS soit pertinent, mais sinon, il semble que tous les composants de thème d’exemple utilisent des Composants et aient été refactorisés dans une base de code entièrement différente de ce qui est enseigné ici. J’ai parcouru tous les composants auxquels ils font référence dans la section API des plugins et chacun d’eux a été refactorisé d’une manière totalement différente de ce qui est enseigné ici dans le guide. Les Widgets ne sont plus du tout utilisés. Tout est Composants. Existe-t-il un guide sur la façon d’utiliser correctement les nouveaux Composants alors que les Widgets disparaissent ?

2 « J'aime »
146

J’ai donc découvert ce post par exemple, tout juste maintenant : Upcoming Header Changes - Preparing Themes and Plugins - donc ils ont tout refactorisé des widgets hérités aux composants Glimmer ? Mais ce tutoriel est entièrement composé de widgets hérités. Que sont exactement les composants Glimmer et existe-t-il des guides ? J’ai de la chance d’avoir découvert cela tôt, avant de commencer à développer avec des widgets hérités. Peut-être ajouter une note dans ce guide indiquant que les widgets sont hérités et ne devraient plus être utilisés ?

2 « J'aime »
147

Ok, je vois que Glimmer est un nouveau composant Ember. Mais j’ai jeté un coup d’œil au code du TOC de Discourse et oh là là… ce qui nécessitait auparavant une dizaine de lignes de code en a maintenant des centaines réparties sur de nombreux fichiers avec des classes complexes, des décorateurs, etc. Je suppose qu’Ember a eu un moment “React” et a décidé de rendre les choses vraiment compliquées à nouveau. Il semble que les composants de thème ne soient plus faciles, avec une simple API de widget, mais nécessitent un codage approfondi…

2 « J'aime »
148

@ddsgad oui, vous avez raison, la plupart de ce guide est extrêmement obsolète. J’ai récemment travaillé sur des améliorations générales de la documentation et j’espère mettre à jour/remplacer celui-ci dans les prochaines semaines.

Comme vous l’avez mentionné, des exemples concrets comme DiscoTOC peuvent être une bonne référence. Et voici quelques guides spécifiques plus à jour :

Pour des informations générales sur Ember et ses composants, je vous recommande de consulter les guides Ember.

6 « J'aime »
149

Merci pour ces liens. Très utile. Actuellement, nous personnalisons essentiellement des éléments dans un sujet de discussion (premier message) pour créer de meilleurs designs, nous avons donc pu tout faire avec du JavaScript Vanilla (querySelectorAll etc.) et du SCSS, donc je suppose que nous nous en tiendrons à cela pour l’instant.

3 « J'aime »
150

Le tutoriel long et obsolète dans le message d’origine a maintenant été remplacé par des informations d’introduction/de signalisation plus générales, y compris un lien vers un tout nouveau tutoriel en 7 étapes qui suit des modèles de développement de thèmes beaucoup plus modernes.

4 « J'aime »
151

J’ai tout lu, j’ai apprécié ! Bien expliqué et très bonne introduction !

3 « J'aime »
152

J’adore ces guides ! J’ai enfin déchiffré api.decorateCookedElement, merci encore pour la documentation utile !

4 « J'aime »