Discourse a la capacité d’intégrer les commentaires d’un sujet sur un site distant à l’aide d’une API Javascript qui crée une IFRAME. Pour un exemple de cela en action, consultez le blog de Coding Horror. Le blog est géré via Ghost mais les commentaires sont intégrés depuis son forum Discourse.
Une chose importante à noter avec cette configuration est que les utilisateurs doivent naviguer vers votre forum pour publier des réponses. Ceci est intentionnel, car nous estimons que l’interface de publication sur un forum Discourse est actuellement beaucoup plus riche que ce que nous pourrions intégrer via Javascript.
Ce guide vous montrera comment configurer l’intégration de commentaires sur votre propre blog ou site web.
Comment ça marche
Dans Discourse, un sujet est composé de nombreux messages. Lorsque vous intégrez Discourse sur un autre site, vous liez un document (article de blog, page HTML, etc.) à un seul sujet. Lorsque les gens publient dans ce sujet, leurs commentaires apparaîtront automatiquement sur la page sur laquelle vous l’avez intégré.
Vous avez le choix de laisser Discourse créer les sujets automatiquement lorsqu’une nouvelle intégration est détectée, ou vous pouvez créer les sujets vous-même à l’avance.
Configuration de Discourse pour l’intégration (configuration simple)
La configuration suivante intégrera un flux de commentaires sur une page d’une fausse URL de blog de http://example.com/blog/entry-123.html, à partir d’un forum discourse fonctionnant à =DISCOURSE=.
Domaine de
Domaine pour
-
Visitez Admin > Personnaliser > Intégration sur votre installation Discourse. https://=DISCOURSE=/admin/customize/embedding
-
Créez au moins un Hôte intégrable. Il doit s’agir du nom d’hôte (domaine) où vous souhaitez intégrer vos commentaires. Dans ce cas, l’hôte est
=BLOG=– notez l’absence dehttp://et de chemin.-
Liste d’autorisation des chemins vous permet de spécifier les chemins sur l’hôte distant qui accepteront votre intégration.
-
Publier dans la catégorie - si vous fournissez une catégorie avec l’hôte que vous entrez, les messages importés de cet hôte se retrouveront automatiquement dans cette catégorie. Différents hôtes peuvent publier dans différentes catégories.
-
Balises - vous pouvez attribuer des balises à appliquer automatiquement aux sujets créés à partir d’un hôte donné.
-
Auteur du message - vous pouvez facultativement remplacer l’utilisateur créant le sujet par hôte. Si non défini, la valeur par défaut de l’onglet Messages et Sujets est utilisée.
-
-
Accédez à l’onglet Messages et Sujets et remplissez le champ Nom d’utilisateur pour la création de sujet. C’est l’utilisateur qui créera les sujets lorsque de nouvelles intégrations seront trouvées. Supposons que notre discours ait un utilisateur nommé eviltrout, la valeur est donc
eviltrout. -
Insérez le HTML suivant sur la page web à l’adresse
http://=BLOG=/blog/entry-123.html
<div id='discourse-comments'></div>
<script type="text/javascript">
DiscourseEmbed = {
discourseUrl: 'https://discourse.example.com/',
discourseEmbedUrl: 'http://example.com/blog/entry-123.html',
// className: 'CLASS_NAME',
};
(function() {
var d = document.createElement('script'); d.type = 'text/javascript'; d.async = true;
d.src = DiscourseEmbed.discourseUrl + 'javascripts/embed.js';
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(d);
})();
</script>
Les parties configurables du fragment se trouvent dans l’objet DiscourseEmbed. discourseUrl est le chemin complet vers la base de votre discourse, y compris la barre oblique finale. discourseEmbedUrl est le document qui intègre actuellement un flux de commentaires.
Si vous configurez cela correctement, la première fois que vous visitez http://=BLOG=/blog/entry-123.html, il tentera de charger les commentaires pour l’article de blog. Comme il n’y en a pas, il demandera au forum Discourse de créer un nouveau sujet en arrière-plan. Un nouveau sujet sera créé par eviltrout et le contenu du premier message sera exploré depuis votre blog et le texte sera extrait automatiquement.
Une fois que le nouveau sujet est créé, les utilisateurs peuvent y publier, et leurs commentaires seront automatiquement affichés la prochaine fois que http://=BLOG=/blog/entry-123.html sera visité.
className est facultatif et ajoutera une classe de votre choix à l’intégration afin que vous puissiez la personnaliser avec du CSS.
Astuce : Si votre blog a plusieurs auteurs, vous pouvez ajouter une balise
<meta name="discourse-username" content="author_username">à chaque page. Lorsque Discourse explorera la page pour créer le sujet, il utilisera cette balise meta pour déterminer l’auteur du message, annulant le nom d’utilisateur par défaut défini dans les paramètres d’administration.
Intégration sur plus d’une page
Dans l’exemple ci-dessus, nous avons codé en dur notre URL http://=BLOG=/blog/entry-123.html lors de l’intégration du fragment de Javascript. Cela ne suffira généralement pas car de nombreux sites comportent de nombreuses pages générées automatiquement. Par exemple, sur un blog, chaque entrée reçoit généralement sa propre page. Pour prendre en charge cela, placez le même fragment sur chaque page sur laquelle vous souhaitez afficher des commentaires, mais remplacez la valeur passée à discourseEmbedUrl par l’URL de la page actuelle. Sur mon blog, j’utilise la valeur suivante pour discourseEmbedUrl : 'http://eviltrout.com<%= current_page.url %>' – à mesure que de nouvelles pages de blog sont créées, de nouveaux sujets seront créés pour elles automatiquement sur Discourse.
Stylisation de votre contenu intégré
Vous avez la possibilité d’ajouter une feuille de style pour vos commentaires intégrés. Utilisez la section CSS intégré de l’éditeur de thème à Admin > Personnaliser > Thèmes > [votre thème] > Modifier CSS/HTML et vous pourrez ajouter une feuille de style personnalisée qui sera servie avec vos commentaires intégrés. Par défaut, nous pensons que la mise en page est agréable sur un fond blanc, mais si votre site a une disposition unique, vous voudrez la styliser vous-même.
(Facultatif) Ajout d’un flux pour le sondage
Comme mentionné ci-dessus, Discourse explorera automatiquement tout site sur lequel il est intégré. Cependant, le HTML peut parfois être difficile à analyser et il se peut qu’il n’extraie pas correctement le contenu de vos messages. De nombreux blogs et sites web prennent en charge les flux RSS/Atom pour la syndication, et Discourse peut l’utiliser pour extraire le contenu de vos articles de blog plus précisément.
Discourse est livré avec le plugin de sondage RSS (inclus par défaut). Si vous avez un flux RSS ou Atom configuré sur le site dans lequel vous intégrez Discourse, vous pouvez activer le paramètre de site rss_polling_enabled et ajouter l’URL de votre flux via Admin > Plugins > Sondage RSS. Une fois l’URL du flux ajoutée, Discourse analysera le flux et publiera ses messages dans la catégorie appropriée en fonction des Hôtes Autorisés que vous ajoutez à vos paramètres d’Intégration.
(Configuration alternative) Lien vers des sujets existants
Certaines personnes préfèrent ne pas laisser Discourse créer automatiquement des sujets sur leurs forums. Elles souhaitent créer les sujets elles-mêmes, puis simplement indiquer au code d’intégration quel sujet associer. Vous pouvez le faire en modifiant légèrement votre code d’intégration :
<div id='discourse-comments'></div>
<script type="text/javascript">
window.DiscourseEmbed = {
discourseUrl: 'https://=DISCOURSE=/',
topicId: 12345
};
(function() {
var d = document.createElement('script'); d.type = 'text/javascript'; d.async = true;
d.src = window.DiscourseEmbed.discourseUrl + 'javascripts/embed.js';
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(d);
})();
</script>
La seule différence est que nous avons remplacé discourseEmbedUrl par l’identifiant d’un sujet de Discourse. Si vous faites cela, aucun sujet ne sera créé et les commentaires de ce sujet seront affichés automatiquement.
Définition de la politique de référent
En raison des modifications récentes (septembre 2020) apportées à la politique de référent par défaut définie par de nombreux navigateurs, Discourse définit désormais explicitement par défaut la politique de référent de l’iframe sur \"no-referrer-when-downgrade\". Si, pour des raisons de sécurité, votre site nécessite une politique de référent plus stricte, celle-ci peut être définie en ajoutant une valeur discourseReferrerPolicy à l’objet DiscourseEmbed du script d’intégration. Par exemple :
DiscourseEmbed = { discourseUrl: 'https://forum.example.com/',
discourseEmbedUrl: '<your_posts_canonical_URL>',
discourseReferrerPolicy: 'strict-origin-when-cross-origin'};
Interrogation programmatique des détails de l’intégration
Nous disposons d’un point de terminaison d’API pour interroger les détails de l’intégration en utilisant l’embed_url comme paramètre :
curl 'https://meta.discourse.org/embed/info?embed_url=https://blog.discourse.org/2021/04/discourse-team-grows-to-50' -H 'API-KEY: logapikeygoeshere' -H 'API-USERNAME: apiusernamehere'
Et la réponse est :
{
"topic_id": 187794,
"post_id": 925017,
"topic_slug": "discourse-team-grows-to-50-blog",
"comment_count": 2
}
Intégration des commentaires à partir d’un site privé
Pour les instances privées de Discourse, si Discourse se trouve sur un sous-domaine du domaine du blog, les commentaires seront affichés pour les utilisateurs connectés à Discourse. Les utilisateurs qui ne sont pas connectés à Discourse verront un message de « connexion refusée ». Si Discourse et le blog se trouvent sur des domaines complètement séparés, aucun commentaire ne sera affiché pour les forums privés.
Dépannage
Le problème le plus courant rencontré par les utilisateurs lors de l’intégration de Discourse est la définition de la valeur correcte pour les hôtes intégrables que vous avez ajoutés. Assurez-vous de vérifier qu’il s’agit uniquement du domaine de votre site, et qu’il ne contient pas de barres obliques supplémentaires ou de caractères non valides.