Ce guide explique comment intégrer et afficher une liste de sujets Discourse sur des sites externes en utilisant JavaScript, vous permettant de mettre en valeur le contenu du forum, tel que des discussions ou des annonces, sur des blogs, des sites web ou d’autres plateformes de contenu externes.
Niveau utilisateur requis : Administrateur
Résumé
L’intégration de sujets Discourse sur des sites externes vous permet d’afficher des listes de sujets de votre forum Discourse directement sur d’autres sites. Cette intégration aide à générer du trafic vers votre forum et à maintenir l’engagement de votre audience avec le contenu de votre communauté. Les sujets intégrés apparaissent sous forme de widget JavaScript qui s’intègre à la structure DOM de votre site, facilitant ainsi la personnalisation via CSS.
Activer l’intégration des sujets
Pour configurer l’intégration des sujets sur votre site externe :
- Accédez à Admin > Avancé > Intégration et basculez vers l’onglet Paramètres. Activez le paramètre du site
embed_topics_list.
- Ajoutez le script d’intégration dans la section
<head>HTML de votre site externe :
<script src="https://discourse.example.com/javascripts/embed-topics.js"></script>
Remplacez discourse.example.com par l’URL réelle de votre forum Discourse.
- Placez l’élément de liste des sujets à l’endroit où vous souhaitez afficher les sujets (par exemple, dans un article de blog ou sur une page individuelle du site) :
<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 celui de votre site Discourse, ajoutez le domaine de votre site externe dans Admin > Avancé > Intégration > Hôtes.
Par exemple, si votre site Discourse est situé à yourdiscourseforum.com et que vous souhaitez intégrer des sujets sur yourexternalsite.com, vous devez ajouter yourexternalsite.com à votre liste d’hôtes autorisés.
Vous ne pouvez pas intégrer de sujets provenant 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 l’affichage de vos sujets :
discourse-url- L’URL de votre site Discourse (obligatoire)template- Options de style d’affichage :basic(par défaut) - Affiche les titres des sujets sous forme de lienscomplete- Affiche le titre, le nom d’utilisateur, l’avatar, la date de création, l’heure de la dernière réponse, le nombre de likes, le nombre de réponses et l’image mise en avant/miniature
per-page- Nombre de sujets à afficher (limité par le paramètre du site cachéembed_topic_limit_per_page, par défaut 200)category- ID de catégorie pour filtrer les sujets d’une catégorie spécifiquetags- Filtrer les sujets par des balises spécifiquesallow-create- Lorsqu’il est défini sur true, affiche un bouton « Nouveau sujet »embed-class- Ajoute une classe CSS personnalisée au conteneur de la liste des sujets intégrés (lettres alphanumériques, tirets et underscores uniquement)top-period- Afficher les meilleurs sujets 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 en utilisant du SCSS personnalisé dans votre panneau Admin > Apparence > Thèmes et composants. Cliquez sur votre thème actuel ou par défaut, puis cliquez sur Modifier le code. Vous pouvez ensuite sélectionner Show_advanced et choisir CSS intégré 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 de balise significatifs pour afficher du contenu pertinent pour votre audience.
- Définissez une valeur
per-pageappropriée pour ne pas submerger les visiteurs. - Testez vos sujets intégrés sur différentes tailles d’écran pour garantir un design réactif.
- 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 courants et solutions
Les sujets ne s’affichent pas sur un domaine externe
Problème : Les sujets intégrés apparaissent comme une boîte vide ou grise lorsqu’ils sont consultés sur un domaine externe.
Solution : Ajoutez le domaine externe aux hôtes de votre site Discourse dans Admin > Avancé > Intégration > Hôtes. 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 du script
Problème : Le script d’intégration échoue à 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.
- Assurez-vous que le paramètre du site
embed_topics_listest activé. - Vérifiez que votre site Discourse ne nécessite 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 le contenu de catégories sécurisées auxquels les utilisateurs anonymes n’ont pas accès.
FAQ
Q : Puis-je intégrer des sujets provenant 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ù les liens de sujets s’ouvrent ?
R : Par défaut, les liens de sujets s’ouvrent dans la fenêtre parente. Vous pouvez modifier ce comportement via une personnalisation CSS ou JavaScript.
