Changements de la liste des sujets à venir - comment préparer thèmes et plugins

[david (David Taylor)]

Dans le cadre de notre quête continue de standardisation des systèmes de rendu dans la base de code de Discourse, nous remplaçons l’implémentation de la liste des sujets.

Auparavant, cela utilisait une approche “raw handlebars” (.hbr), et pouvait être personnalisé via des remplacements de modèles et des raw-plugin-outlets. La nouvelle implémentation de la liste des sujets utilise des composants Glimmer modernes, et a été construite à partir de zéro pour être personnalisable de manière durable.

La nouvelle implémentation est maintenant disponible derrière le paramètre glimmer_topic_list_mode.

• disabled : utilise la liste des sujets “raw handlebars” héritée.
• auto : détectera la compatibilité de vos plugins et thèmes actuels. Si certains sont incompatibles, il utilisera le système hérité ; sinon, il utilisera la nouvelle implémentation.
• enabled : utilisera la nouvelle implémentation de la liste des sujets. Si vous avez des plugins ou des thèmes incompatibles, votre site risque d’être endommagé.

Nous avons déjà mis à jour la plupart de nos thèmes et plugins officiels pour qu’ils soient compatibles avec le nouveau menu. Cependant, si vous utilisez des plugins, des thèmes ou des composants de thème tiers qui personnalisent la liste des sujets, leur mise à jour sera nécessaire.

Des avertissements seront imprimés dans la console du navigateur, identifiant la source de l’incompatibilité.

Calendrier de déploiement

Ce sont des estimations approximatives sujettes à modification

T4 2024 :

• implémentation principale terminée
• mise à jour des thèmes/plugins officiels (en cours)
• activé sur Meta
• publication des conseils de mise à niveau

T1 2025 :

• mise à jour des thèmes/plugins officiels

• glimmer_topic_list_mode par défaut sur auto ; messages de dépréciation dans la console activés

• les dépréciations déclencheront une bannière d’avertissement pour les administrateurs pour les problèmes restants

• les plugins et thèmes tiers devraient être mis à jour

• 1er mars - activation de la nouvelle liste des sujets pour tous les sites. La valeur par défaut du paramètre du site sera changée en enabled, mais il sera toujours possible de revenir à disabled.

T2 2025

• après le 1er avril - suppression définitive du mode hérité et du code associé.

Qu’est-ce que cela signifie pour moi ?

Si votre plugin ou thème contient des fichiers ‘raw handlebars’ (nommés .hbr ou .raw.hbs), ils devront être mis à jour pour être compatibles avec la nouvelle version. Les fichiers .hbs réguliers pour les composants/routes Ember ne sont pas affectés par ce changement.

Des mises à jour seront également nécessaires si vous utilisez modifyClass sur component:topic-list ou component:topic-list-item.

Si votre site a l’une de ces personnalisations incompatibles, des messages d’avertissement seront imprimés dans la console du développeur du navigateur, y compris des informations sur le thème/plugin qui en est la cause.

Quels sont les remplacements ?

Certains des anciens raw-plugin-outlets ont été convertis en Plugin Outlets réguliers. Ceux-ci peuvent être mis à jour de manière 1:1.

Les personnalisations plus avancées devront être évaluées au cas par cas. La nouvelle liste des sujets dispose d’un certain nombre de nouvelles API pour une personnalisation facile et robuste. Pour en savoir plus, consultez :

Customizing the topic list

The topic-list is one of the most-used and most-customized user-interfaces in Discourse. There are many different tools available to theme and plugin developers to achieve this customization, each with their own advantages, disadvantages and maintenance considerations. CSS-based Customization The safest and most common customization method is CSS. As with any other Discourse customization: the more complex your changes, the more maintenance is likely to be required in your theme or plugin. Gen…

Voici quelques exemples :

• discourse-assign introduit une nouvelle colonne à une liste de sujets spécifique.

• discourse-calendar utilise l’un des nouveaux plugin outlets pour afficher le badge de date de l’événement.

• discourse-solved utilise un nouveau valueTransformer pour remplacer le modifyClass précédent.

Qu’en est-il des autres personnalisations ?

Si votre personnalisation ne peut pas être réalisée à l’aide des nouvelles API que nous avons introduites, veuillez nous en informer en créant un nouveau sujet Dev pour en discuter.

Je suis un auteur de plugin/thème. Comment mettre à jour un thème/plugin pour prendre en charge l’ancienne et la nouvelle liste de sujets pendant la transition ?

Les nouveaux plugin outlets sont rendus dans les anciennes et les nouvelles implémentations de la liste des sujets. Donc : lorsque vous avez implémenté le nouveau, supprimez simplement l’ancien connecteur raw-plugin-outlet.

Pour les personnalisations basées sur DAG qui remplacent les template-overrides ou les outlets non modernisés, vous devrez maintenir les deux implémentations pendant la période de transition.

Une fois que votre thème/plugin prend en charge les anciennes et les nouvelles implémentations, vous pouvez ajouter ce commentaire magique en haut de tous vos fichiers .hbr :

{{!-- has-modern-replacement --}}

Cela supprimera les messages de dépréciation et permettra d’utiliser la nouvelle implémentation lorsqu’elle est en mode “auto”.

[pfaffman (Jay Pfaffman)]

@david

Si votre plugin ou thème contient des fichiers ‘raw handlebars’ (nommés .hbr ou .raw.hbs), ceux-ci devront être mis à jour pour être compatibles avec la nouvelle version.

Désolé d’être pointilleux, mais cela ne signifie-t-il pas plutôt « si votre plugin ou thème contient des fichiers ‘raw handlebars’ qui ont quelque chose à voir avec la liste des sujets, alors ils doivent être mis à jour » ?

Mes fichiers raw handlebars qui concernent d’autres modèles vont continuer à aller bien, n’est-ce pas ? Ou les fichiers raw handlebars disparaissent-ils complètement ? (Je pense qu’ils sont nécessaires pour des modèles/routes supplémentaires, n’est-ce pas ?)

[david (David Taylor)]

« Raw handlebars » signifie nos modèles spécifiques à Discourse, qui ont l’extension de fichier .hbr (ou historiquement .raw.hbs). Nous n’avons utilisé ce système que pour la liste des sujets et certains éléments internes d’« autocomplétion ».

Les autres fichiers .hbs (par exemple pour les composants Ember ou les routes) ne sont pas affectés.

Je mettrai à jour le message initial pour clarifier cela. Merci @pfaffman !

Edit : voilà :

@david

Si votre plugin ou thème contient des fichiers « raw handlebars » (nommés .hbr ou .raw.hbs), ceux-ci devront être mis à jour pour être compatibles avec la nouvelle version. Les fichiers .hbs classiques pour les composants/routes Ember ne sont pas affectés par ce changement.

[pfaffman (Jay Pfaffman)]

@david

« Raw handlebars » fait référence à nos modèles spécifiques à Discourse, qui ont l’extension de fichier .hbr (ou historiquement .raw.hbs).

Oh. Vous avez vraiment essayé de clarifier. Vous avez explicitement indiqué les extensions. Je ne pense pas que vous puissiez être plus clair. Je pense que c’est de ma faute.

Mais peut-être qu’ajouter la phrase supplémentaire m’aurait aidé à pouvoir lire.

[Don]

Merci de partager. J’ai eu peur de ça pendant longtemps et ça arrive… Cela ne semble pas être une course facile… Mais le transformateur de valeur le rendra probablement plus facile.

[merefield (Robert)]

Je pense que GitHub - discourse/discourse-topic-excerpts: Add topic excerpts to all topics in the topic list n’a pas encore été mis à jour ?

[david (David Taylor)]

Oui, nous avons encore beaucoup de thèmes/plugins officiels en attente de mise à niveau. Je vais étendre ce point à la première semaine du premier trimestre dans l’OP

[merefield (Robert)]

Merci ! J’apprécie l’expérience développeur jusqu’à présent ! Je vous ferai savoir si TLP soulève des problèmes lorsque j’y arriverai.

[david (David Taylor)]

Génial ! La liste officielle des miniatures de sujets (topic-list-thumbnails) est l’une de celles que nous avons fini de mettre à jour, elle pourrait donc servir de référence utile.

[david (David Taylor)]

@merefield

Je crois que GitHub - discourse/discourse-topic-excerpts: Add topic excerpts to all topics in the topic list n’a pas encore été mis à jour ?

@david

Ouais, nous avons encore beaucoup de thèmes/plugins officiels en attente de mise à niveau

Oh, désolé ! @isaac a mis à jour topic-excerpts la semaine dernière : DEV: Update plugin for `glimmer-topic-list` (#34) · discourse/discourse-topic-excerpts@0dd3c6c · GitHub

Donc, cela devrait fonctionner correctement sous la nouvelle liste de sujets

[merefield (Robert)]

Je reçois :

Les deux versions sont à jour.

[merefield (Robert)]

@david

discourse-assign introduit une nouvelle colonne dans une liste de sujets spécifique

lors de l’ajout d’une colonne, quelle est la manière stratégique d’ajouter un en-tête de colonne triable ?

en utilisant :

api.registerValueTransformer("topic-list-header-sortable-column"

en plus de l’autre transformateur ?

      api.registerValueTransformer(
        "topic-list-columns",

cela ne semble pas suffire ?

[david (David Taylor)]

@merefield

J’obtiens :

cc @isaac. Si je devais deviner : peut-être que la nouvelle logique doit être mise à jour pour gérer les sujets non catégorisés ?

@merefield

quelle est la manière stratégique d’ajouter un en-tête de colonne triable ?

Le transformateur que vous avez trouvé sert à remplacer la triabilité des colonnes existantes (par exemple, nous le faisons dans discourse-calendar pour empêcher toute autre méthode de tri d’être utilisée lorsque vous êtes sur la vue chronologique des sujets)

Si vous ajoutez une nouvelle colonne, vous devriez pouvoir définir votre en-tête en utilisant le composant SortableColumn. Par exemple, voici un exemple dans le cœur du système :

app/assets/javascripts/discourse/app/components/topic-list/header/activity-cell.gjs

app/assets/javascripts/discourse/app/components/topic-list/list.gjs

(une chose vraiment agréable avec la nouvelle API est que toutes les colonnes principales sont définies en utilisant la même API que celle que vous utilisez à partir des thèmes/plugins !)

[merefield (Robert)]

@david

les colonnes principales sont définies en utilisant la même API que celle que vous utilisez à partir des thèmes/plugins !

oui je l’ai remarqué lorsque j’ai fait une recherche de code, sympa !

[isaac (Isaac Janzen)]

@david

cc @isaac. Si je devais deviner : peut-être que la nouvelle logique doit être mise à jour pour gérer les sujets non catégorisés ?

Fixed

[merefield (Robert)]

Q : Est-il possible d’attribuer un composant complet à une cellule, pas seulement un <template> ?

Par exemple, que faire si je voulais afficher un bouton transparent dans une cellule qui nécessitait une logique JavaScript minimale ?

[david (David Taylor)]

@merefield

Q: Est-il possible d’attribuer un composant complet à une cellule, pas seulement un <template> ?

Oui ! Techniquement, une simple balise <template> crée techniquement un « composant uniquement basé sur un modèle ». Similaire au type de composant que vous obtenez lorsque vous déposez un fichier .hbs simple dans le répertoire components/.

Donc oui, importer et passer une classe de composant normale fonctionnera de la même manière. Cela fonctionnera même avec les composants classiques ! (bien que nous recommandions évidemment d’utiliser les composants Glimmer plus modernes).

[merefield (Robert)]

C’est absolument génial !

Ça change… beaucoup de choses !

[merefield (Robert)]

Question bête, peut-être.

Mais comment appliquer des modifications à… la liste de sujets mobile ?

[david (David Taylor)]

Pour mobile, nous avons un tas de nouveaux points de terminaison de plugins (y compris des points de terminaison wrapper).

Ou alternativement, vous pouvez utiliser un valueTransformer pour forcer la vue de bureau partout (nous le faisons pour les miniatures de sujets).

Je prévois d’écrire un guide plus détaillé sur la façon de personnaliser la liste des sujets dans la section Documentation > Developer Guides la semaine prochaine, je m’assurerai donc d’y inclure ces informations.