Nous avons récemment travaillé à la mise à jour de l’en-tête de Discourse, en passant du système de rendu « widget » hérité aux composants Glimmer modernes. Ce changement est désormais disponible dans le cœur de Discourse, derrière le paramètre du site glimmer header mode.
Calendrier approximatif
(estimations très approximatives - sujettes à modification dans les deux sens)
T1 2024 :
-
implémentation principale terminée et activée sur Meta -
publication des conseils de mise à niveau ; messages de dépréciation dans la console activés -
début du travail de mise à jour de tous les plugins et thèmes officiels et tiers
T2 2024 :
-
début de l’activation par défaut de la nouvelle implémentation de l’en-tête -
les thèmes et plugins officiels et tiers sont prêts pour la mise à niveau -
les messages de dépréciation commencent à déclencher une bannière d’avertissement pour les administrateurs en cas de problèmes restants
T3 2024 :
-
publication d’un sujet d’annonce pour une plus grande visibilité : Preparing your community for behind-the-scenes header changes -
semaine du 5 août 2024 (v3.4.0.beta1) : nouvel en-tête activé par défaut pour tous les sites. Il restera possible pour les administrateurs de revenir à l’ancien en-tête en basculant le paramètre du site « glimmer header mode ». -
semaine du 2 septembre 2024 : suppression finale du drapeau de fonctionnalité et du code hérité
Qu’est-ce que cela signifie pour moi ?
Si votre plugin ou thème utilise des API « widget » pour personnaliser l’en-tête, ceux-ci devront être mis à jour pour être compatibles avec le nouvel en-tête.
Comment essayer le nouvel en-tête ?
Dans la dernière version de Discourse, le nouvel en-tête est automatiquement activé lorsque tous vos thèmes et plugins sont compatibles.
Si vos thèmes/plugins ne sont pas compatibles, l’ancien en-tête sera toujours utilisé, et un avertissement sera affiché dans la console, en plus des messages de dépréciation existants. Une bannière d’avertissement sera également affichée aux administrateurs dans l’interface utilisateur.
Dans le cas peu probable où ce système automatique ne fonctionnerait pas comme prévu, vous pouvez temporairement remplacer ce « drapeau de fonctionnalité automatique » via le paramètre du site glimmer header mode. Si vous le faites, veuillez nous indiquer la raison dans ce sujet.
Dois-je mettre à jour mon plugin/thème ?
Pour déterminer si votre personnalisation doit être mise à jour, vérifiez si elle utilise decorateWidget, changeWidgetSetting, reopenWidget ou attachWidgetAction sur l’un de ces widgets :
- header
- site-header
- header-contents
- header-buttons
- user-status-bubble
- sidebar-toggle
- header-icons
- header-topic-info
- header-notifications
- home-logo
- user-dropdown
ou utilise l’une de ces méthodes d’API de plugin :
addToHeaderIconsaddHeaderPanel
Toutes ces actions provoqueront désormais l’affichage de messages de dépréciation dans la console. Les identifiants de dépréciation sont :
discourse.add-header-paneldiscourse.header-widget-overrides
Si vous utilisez plus d’un thème sur votre instance, assurez-vous de vérifier chacun d’eux.
Avis aux administrateurs
À partir du 20 juin 2024, nous avons activé l’avis aux administrateurs pour les dépréciations mentionnées ci-dessus.
Si votre instance a été déployée après cette date et que vos plugins, thèmes ou composants de thèmes actuels déclenchent l’un des avertissements de dépréciation, le message suivant s’affichera uniquement pour les administrateurs* :
Ce message sert uniquement à alerter les administrateurs qu’ils doivent agir prochainement pour moderniser les personnalisations concernées : les anciennes personnalisations continueront de fonctionner jusqu’à ce que nous supprimions la base de code héritée.
Quelles sont les alternatives ?
Chaque thème/plugin est différent, mais voici quelques orientations pour les cas d’usage les plus courants :
addToHeaderIcons
Pour les icônes d’en-tête personnalisées, nous recommandons de supprimer votre code et d’installer le composant de thème officiel Custom Header Links (Icons) Theme Component. Si cela ne répond pas à vos besoins, consultez ci-dessous les détails sur les modifications de code requises :
L’API de plugin addToHeaderIcons a été dépréciée au profit de la nouvelle API headerIcons. Elle permet d’ajouter, de supprimer ou de réorganiser des icônes dans l’en-tête. Elle nécessite qu’un composant soit transmis.
Le composant peut être transmis comme suit :
| Avant | Après |
|---|---|
| api.addToHeaderIcons(“widget-foo”) | api.headerIcons.add(“foo”, FooIcon) |
| api.decorateWidget(“header-icons:before”, () => return helper.h(“div”, “widget-foo”)) | api.headerIcons.add(“foo”, FooIcon, { before: “search” }) |
| api.decorateWidget(“header-icons:after”, () => return helper.h(“div”, “widget-foo”)) | api.headerIcons.add(“foo”, FooComponent, { after: “search” }) |
Cet exemple utilise le format de balise de modèle d’Ember (gjs) pour définir un composant en ligne et le transmettre à l’API headerButtons.add :
// .../discourse/api-initializers/add-my-button.gjs
import DButton from "discourse/components/d-button";
import { apiInitializer } from "discourse/lib/api";
export default apiInitializer("1.0", (api) => {
api.headerIcons.add("some-unique-name", <template>
<li><DButton class="icon btn-flat" @href="/u" @icon="address-book" /></li>
</template>);
});
Ou pour un menu déroulant, vous pouvez utiliser <DMenu au lieu de <DButton :
import DButton from "discourse/components/d-button";
import { apiInitializer } from "discourse/lib/api";
import DMenu from "float-kit/components/d-menu";
export default apiInitializer("1.0", (api) => {
api.headerIcons.add("some-unique-name", <template>
<li>
<DMenu class="icon btn-flat" @icon="address-book">
<DButton @translatedLabel="User 1" @href="/u/user1" />
<DButton @translatedLabel="User 2" @href="/u/user2" />
<DButton @translatedLabel="User 3" @href="/u/user3" />
</DMenu>
</li>
</template>);
});
Exemples de commits de mise à niveau :
decorateWidget("header-buttons:*")
Pour les liens d’en-tête personnalisés, nous recommandons de supprimer votre code et d’installer le composant de thème officiel Custom Header Links Theme Component. Si cela ne répond pas à vos besoins, consultez ci-dessous les détails sur les modifications de code requises :
Le widget header-buttons a été déprécié et nous avons introduit une API de plugin headerButtons. Elle permet d’ajouter, de supprimer ou de réorganiser des boutons dans l’en-tête. Elle nécessite qu’un composant soit transmis.
| Avant | Après |
|---|---|
| api.decorateWidget(“header-buttons:before”) | api.headerButtons(“button-name”, ButtonComponent, { before: “auth” }) |
| api.decorateWidget(“header-buttons:after”) | api.headerButtons(“button-name”, ButtonComponent, { after: “auth” }) |
changeWidgetSetting(...) pour les widgets d’en-tête
Les utilisations les plus courantes de
changeWidgetSettingpeuvent être réalisées à l’aide de ces composants de thème :Si ceux-ci ne correspondent pas à votre cas d’usage, continuez la lecture…
Certaines personnalisations des widgets d’en-tête utilisaient l’API changeWidgetSetting.
Bien qu’il n’existe pas de remplacement direct pour des personnalisations comme celle ci-dessus, en raison du fonctionnement des champs des composants Glimmer, nous avons introduit une nouvelle API de plugin dans Discourse 3.3.0.beta3 pour gérer certains de ces cas.
registerValueTransformer peut être utilisé pour remplacer des valeurs marquées dans le code source comme remplaçables ; cette approche est similaire à celle des emplacements de plugin.
Nous avons déjà ajouté deux transformateurs pour les cas d’usage que nous avons identifiés comme courants dans notre base de code source :
-
home-logo-href: peut être utilisé pour remplacer l’URL dans l’ancre du logo d’accueil. Voir la sectionhome-logoci-dessous pour des exemples. -
header-notifications-avatar-size: peut être utilisé pour modifier la taille de l’image récupérée pour l’avatar de l’utilisateur dans l’en-tête. Exemple :
Le code ci-dessous :
api.changeWidgetSetting(
"header-notifications",
"avatarSize",
settings.header_avatars_size
);
Serait converti en :
api.registerValueTransformer(
"header-notifications-avatar-size",
() => settings.header_avatars_size
);
Ces transformateurs doivent être ajoutés au code source de Discourse. Si vous en avez besoin d’un autre, veuillez nous le faire savoir en publiant votre cas d’usage ci-dessous.
Plus de détails sur les nouvelles API de transformateur de valeur sont disponibles ici.
home-logo
Nous avons introduit un emplacement de plugin home-logo en remplacement des décorations de widget home-logo:before ou home-logo:after. Vous pouvez utiliser la convention de nommage automatique __before et __after dans votre fichier de connecteur pour spécifier où votre contenu personnalisé doit être placé.
Plus de détails sur la convention de nommage des fichiers de connecteur avant/après sont disponibles ici.
| Avant | Après |
|---|---|
| api.decorateWidget(“home-logo:before”) | Déplacer le contenu vers /connectors/home-logo__before |
| api.decorateWidget(“header-buttons:after”) | Déplacer le contenu vers /connectors/home-logo__after |
Modification de l’URL de l’ancre du logo d’accueil :
Un besoin très courant est de modifier l’URL vers laquelle pointe le home-logo. Nous avons introduit le transformateur de valeur home-logo-href pour répondre à cela. Exemples :
-
pour changer le lien vers une URL statique
api.registerValueTransformer("home-logo-href", () => "https://example.com"); -
pour retourner une URL dynamique basée sur l’utilisateur actuel
api.registerValueTransformer("home-logo-href", () => { const currentUser = api.getCurrentUser(); return `https://example.com/${currentUser.username}`; }); -
pour retourner une URL basée sur un paramètre de composant de thème
api.registerValueTransformer("home-logo-href", () => { return settings.example_logo_url_setting; });
Et les autres personnalisations ?
Si votre personnalisation ne peut pas être réalisée à l’aide de CSS, de PluginOutlets ou des nouvelles API que nous avons introduites, veuillez nous le faire savoir en créant un nouveau sujet Development pour en discuter.
Comment mettre à jour un thème/plugin pour prendre en charge à la fois l’ancien et le nouvel en-tête ?
Toutes les nouvelles API et emplacements de plugin listés dans ce document sont pris en charge à la fois par le nouvel et l’ancien en-tête. Vous n’avez donc besoin de faire qu’une seule mise à jour de votre thème/plugin maintenant, et les utilisateurs seront prêts pour le passage.




