Ce guide explique comment intégrer et afficher une liste de sujets Discourse sur des sites Web externes à l’aide de JavaScript, vous permettant ainsi de présenter le contenu du forum tel que des discussions ou des annonces sur des blogs, des sites Web ou des plateformes de contenu externes.
Niveau d’utilisateur requis : Administrateur
Résumé
L’intégration de sujets Discourse sur des sites Web externes vous permet d’afficher des listes de sujets de votre forum Discourse directement sur d’autres sites. Cette intégration permet de générer du trafic vers votre forum et de maintenir votre public engagé avec le contenu de votre communauté. Les sujets intégrés apparaissent sous la forme d’un widget JavaScript qui s’intègre à la structure DOM de votre site, ce qui facilite la personnalisation via CSS.
Activer l’intégration des sujets
Pour configurer l’intégration des sujets sur votre site externe :
-
Accédez à votre tableau de bord d’administration Discourse et cliquez sur
site_settings. Recherchez et activez le paramètre de siteembed_topics_list. -
Ajoutez le script d’intégration à la section
<head>HTML de votre site externe :<script src="https://discourse.example.com/javascripts/embed-topics.js"></script>Remplacez
discourse.example.compar l’URL de votre forum Discourse réel. -
Placez l’élément de liste de sujets là où vous souhaitez afficher les sujets (par exemple, dans un article de blog ou sur une page de site individuelle) :
<d-topics-list discourse-url="https://discourse.example.com" category="1234" per-page="5"></d-topics-list> -
Si vous intégrez des sujets sur un domaine différent de votre site Discourse, ajoutez le domaine de votre site externe à Admin > Avancé > Intégration > Hôtes.
Par exemple, si votre site Discourse est situé à
votrefourumdiscourse.comet que vous souhaitez intégrer des sujets survotre-site-externe.com, vous devez ajoutervotre-site-externe.comà votre liste d’hôtes autorisés.
Vous ne pouvez pas intégrer de sujets d’un site Discourse privé nécessitant une connexion.
Paramètres de configuration
L’élément d-topics-list prend en charge les attributs suivants pour personnaliser votre affichage de sujets :
discourse-url- L’URL de votre site Discourse (obligatoire)template- Options de style d’affichage :basic(par défaut) - Affiche des informations minimales sur le sujetcomplete- Affiche le titre, le nom d’utilisateur, l’avatar, la date de création et la vignette
per-page- Nombre de sujets à affichercategory- ID de catégorie pour filtrer les sujets d’une catégorie spécifiquetags- Filtrer les sujets par des étiquettes spécifiquesallow-create- Lorsqu’il est défini surtrue, affiche un bouton “Nouveau sujet”top_period- Afficher les sujets les plus populaires d’une période spécifique :allyearlyquarterlymonthlyweeklydaily
Vous pouvez combiner plusieurs paramètres pour affiner l’affichage de votre liste de sujets. Par exemple :
<d-topics-list
discourse-url="https://discourse.example.com"
category="5"
tags="announcements"
per-page="10"
template="complete">
</d-topics-list>
Personnalisation de l’apparence
Vous pouvez styliser les sujets intégrés à l’aide de SCSS personnalisé dans votre panneau Admin > Personnaliser > Thèmes. Cliquez sur votre thème actuel ou par défaut et cliquez sur Modifier le code. Vous pouvez ensuite sélectionner Show_advanced et choisir Embedded CSS pour ajouter votre code personnalisé :
Voici un exemple de SCSS pour créer une mise en page en grille :
.topics-list {
display: grid;
grid-template-columns: repeat(2, 1fr);
.topic-list-item {
.main-link {
border: 1px dotted gray;
padding: 0;
}
.topic-column-wrapper {
flex-direction: column-reverse;
.topic-column.details-column {
width: 100%;
}
.topic-column.featured-image-column .topic-featured-image img {
max-width: initial;
max-height: initial;
width: 100%;
}
}
}
}
Bonnes pratiques
- Utilisez des filtres de catégorie et d’étiquettes pertinents pour afficher le contenu pertinent pour votre public.
- Définissez une valeur
per-pageappropriée pour éviter de submerger les visiteurs. - Testez vos sujets intégrés sur différentes tailles d’écran pour garantir une conception réactive.
- Envisagez d’utiliser le modèle
completepour un meilleur attrait visuel lorsque l’espace le permet. - Examinez régulièrement votre liste d’hôtes autorisés pour vous assurer que seuls les domaines autorisés peuvent intégrer vos sujets.
Problèmes et solutions courants
Les sujets ne s’affichent pas sur le domaine externe
Problème : Les sujets intégrés apparaissent comme une boîte vide ou grise lorsqu’ils sont visualisés sur un domaine externe.
Solution : Ajoutez le domaine externe aux Admin > Personnaliser > Intégration > Hôtes autorisés de votre site Discourse. Assurez-vous d’inclure le sous-domaine correct (par exemple, si votre site utilise www.example.com, ajoutez www.example.com plutôt que simplement example.com).
Erreurs de chargement de script
Problème : Le script d’intégration ne parvient pas à se charger ou renvoie des erreurs de connexion.
Solution :
- Vérifiez que l’URL Discourse dans la source de votre script est correcte et accessible.
- Vérifiez que le paramètre de site
embed_topics_listest activé. - Assurez-vous que votre site Discourse n’exige pas de connexion pour les sujets publics.
Comportement du contexte SameSite
Dans les contextes SameSite où le site d’intégration et le forum partagent un domaine parent, Discourse respecte le statut de connexion et affiche les résultats en conséquence. Les utilisateurs connectés peuvent voir du contenu provenant de catégories sécurisées auxquelles les utilisateurs anonymes ne peuvent pas accéder.
FAQ
Q : Puis-je intégrer des sujets d’un site Discourse privé ?
R : Non, l’intégration de sujets ne fonctionne qu’avec des sites Discourse publics. Les sites privés nécessitant une connexion ne peuvent pas être intégrés.
Q : Puis-je intégrer plusieurs listes de sujets sur la même page ?
R : Oui, vous pouvez inclure plusieurs éléments <d-topics-list> sur la même page avec différents paramètres pour afficher diverses collections de sujets.
Q : Comment intégrer des sujets avec des images mises en avant ?
R : Utilisez le paramètre template="complete" dans votre élément <d-topics-list> pour afficher les sujets avec des miniatures et des images mises en avant.
Q : Puis-je modifier l’endroit où s’ouvrent les liens des sujets ?
R : Par défaut, les liens des sujets s’ouvrent dans la fenêtre parente. Vous pouvez modifier ce comportement via une personnalisation CSS ou JavaScript.
