Développement de thèmes et de composants de thème Discourse

[Discourse]

Les thèmes Discourse et les composants de thème peuvent être utilisés pour personnaliser l’apparence, l’ambiance et les fonctionnalités du frontend de Discourse. Cette section des guides du développeur vise à fournir tout le matériel de référence dont vous avez besoin pour développer des thèmes simples pour un seul site, jusqu’aux composants de thème open source complexes.

Cette introduction vise à fournir une carte de tous les outils et API pour le développement de thèmes. Si vous préférez un tutoriel étape par étape pour le développement de thèmes, accédez directement à :

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…

Thèmes vs. Composants de Thème

Les Thèmes Discourse peuvent être utilisés pour personnaliser l’expérience utilisateur du frontend à l’aide de CSS et de JavaScript. Chaque thème possède son propre dépôt git, et les administrateurs de communauté peuvent généralement les installer et les gérer via le panneau d’administration de Discourse, même sur des plateformes d’hébergement mutualisé.

Les Composants de Thème sont des thèmes destinés à être utilisés avec d’autres composants de thème, dans le cadre d’un thème global. D’un point de vue développement, les composants de thème et les thèmes sont presque identiques. Dans ces guides, les termes « Thème » et « Composant de Thème » sont utilisés de manière interchangeable.

Prérequis

Tout d’abord, assurez-vous de comprendre comment utiliser les thèmes et les composants de thème existants dans Discourse. L’utilisation de thèmes prêts à l’emploi est le moyen le plus rapide et le plus sûr de personnaliser votre communauté. Si vous avez besoin de plus, il est temps d’envisager d’écrire votre propre thème.

Dans le cadre de l’architecture globale de Discourse, les thèmes Discourse sont construits à l’aide des technologies standard HTML, CSS, JavaScript, et utilisent des concepts Ember pour les interfaces utilisateur plus avancées. Ces guides de référence supposent une compréhension de base de ces technologies et renvoient vers des références externes lorsque cela est possible.

Discourse est un projet en évolution rapide, et en tant que tel, tout thème personnalisé nécessitera une maintenance au fil du temps. Assurez-vous d’en tenir compte dans vos processus de planification et de développement.

Démarrage

• Theme CLI
• Theme Creator
• Structure des fichiers du thème

Personnalisation du Frontend

• Schemes de couleurs
• API JavaScript
• Outlets
• Transformers
• modifyClass

Plus !

Consultez le reste des Guides du Développeur !

---

Ce document est contrôlé par version - suggérez des modifications sur github.

[rsigg]

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

@Discourse

https://github.com/discourse/discourse/blob/main/app/assets/javascripts/discourse/app/controllers/composer.js#L578

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

Et plus loin dans la même section :

@Discourse

https://github.com/discourse/discourse/blob/master/app/assets/javascripts/discourse/app/components/discovery-categories.js

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

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

[Overgrow]

@Discourse

Si vous voulez exécuter des scripts lorsqu’un composant est chargé, vous pouvez utiliser quelque chose comme ceci

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>

[Don]

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

[Overgrow]

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

[ddsgad (DDSGadget)]

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 ?

[NateDhaliwal]

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

[ddsgad (DDSGadget)]

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 ?

[ddsgad (DDSGadget)]

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 ?

[ddsgad (DDSGadget)]

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…

[david (David Taylor)]

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

• Install the Discourse Theme CLI console app to help you build themes

• Using Plugin Outlet Connectors from a Theme or Plugin

• Customizing the topic list

• Introducing Discourse developer toolbar

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

[ddsgad (DDSGadget)]

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.

[david (David Taylor)]

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.

[Arkshine]

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

[NateDhaliwal]

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