Writing Extensions | FastComments Docs

Développement d'extensions

Contexte

FastComments offre la possibilité d'étendre notre fonctionnalité principale via des scripts que nous appelons Extensions.

Une Extension peut ajouter du balisage supplémentaire au widget de commentaires, des écouteurs d'événements, et exécuter du code arbitraire.

Ici vous trouverez des exemples d'extensions que nous avons en production, ainsi que la documentation sur la façon d'écrire des extensions.

Le cycle de vie de l'extension

Le script de chaque extension est récupéré et exécuté avant que le widget de commentaires ne commence à récupérer le premier ensemble de commentaires et à afficher l'interface utilisateur.

Au chargement initial, les données suivantes seront ajoutées à l'objet extension :

config - Une référence à l'objet config.
translations - Une référence à l'objet translations.
commentsById - Une référence à tous les commentaires par id.
root - Une référence au nœud DOM racine.

Les extensions doivent redéfinir les fonctions souhaitées, que le widget de commentaires invoquera aux moments appropriés.

Définir une extension

La plus petite extension possible serait:

Une extension simple

Copy

Run

(function () {
    const extension = FastCommentsUI.extensions.find((extension) => {
        return extension.id === 'my-extension';
    });
})();

Pour cet exemple, enregistrez ceci sous my-extension.js, et rendez-le disponible à https://example.com/my-extension.min.js.

Cette extension ne fait rien, sauf qu'au chargement elle récupère l'objet créé Extension par la bibliothèque principale de commentaires.

Cet objet Extension est un singleton et n'est pas partagé avec d'autres extensions.

Ensuite, pour charger notre extension, nous devons en informer le widget de commentaires. Par exemple:

Using a Custom Extension

Copy

Run

<script async src="https://cdn.fastcomments.com/js/embed-v2-async.min.js"></script>
<div id="fastcomments-widget"></div>
<script>
window.fcConfigs = [{
    "tenantId": "demo",
    "extensions": [
        {
            "id": "my-extension",
            "path": "https://example.com/my-extension.min.js"
        }
    ]
}];
</script>

Pour des exemples fonctionnels, voir la section suivante.

Exemples d'extensions

Chez FastComments, nous écrivons nos propres extensions en utilisant la même API. Vous pouvez consulter le code non minifié de ces extensions aux points de terminaison suivants :

Mode sombre

L'extension Mode sombre est chargée de façon conditionnelle lorsqu'une page « sombre » est détectée. Cette extension ajoute simplement du CSS au widget de commentaires. Ainsi, nous n'avons pas à charger le CSS du mode sombre lorsqu'il n'est pas nécessaire.

https://fastcomments.com/js/comment-ui/extensions/comment-ui.dark.extension.js

Modération

Lorsque l'utilisateur actuel est modérateur, nous utilisons l'extension de modération.

C'est un bon exemple pour ajouter des écouteurs d'événements basés sur les clics, effectuer des requêtes API, et ajouter des éléments au menu et aux zones de commentaires.

https://fastcomments.com/js/comment-ui/extensions/comment-ui.moderation.extension.js

Chat en direct

L'extension Chat en direct (en combinaison avec d'autres configurations et styles) transforme le widget de commentaires en un composant de chat en temps réel.

https://fastcomments.com/js/comment-ui/extensions/live-chat.extension.js

L'objet d'extension

L'objet d'extension se compose de la définition suivante :

JSDoc de l'extension

Copy

Run

/**
 * The FastCommentsUI extension object. Used for lazy-loading certain components. For example, the review system is not
 * used by all customers, so we only load that extension when we want it.
 *
 * @typedef {Object} FastCommentsUIExtension
 * @property {string} id
 * @property {Element} scriptNode
 * @property {Element} root - Le nœud DOM racine du widget.
 * @property {string} [css]
 * @property {Object} config - L'objet de configuration FastComments.
 * @property {Object} commentsById - Une référence à un objet contenant tous les commentaires par id, qui est tenu à jour.
 * @property {Object} translations - Une référence à toutes les traductions.
 * @property {Function} reRenderComment - Une référence à une fonction pouvant être appelée pour réafficher un commentaire.
 * @property {Function} removeCommentAndReRender - Une référence à une fonction pouvant être appelée pour supprimer un commentaire de la mémoire et réafficher la partie appropriée du DOM.
 * @property {Function} newBroadcastId - Une référence à une fonction pouvant être appelée pour créer un nouvel identifiant de diffusion (broadcast id) et l'ajouter à la liste locale d'identifiants de diffusion à ignorer.
 * @property {FastCommentsUIExtensionSetupEventHandlers} [setupEventHandlers]
 * @property {FastCommentsUIExtensionPrepareCommentForSavingCallback} [prepareCommentForSaving]
 * @property {FastCommentsUIExtensionNewCommentCallback} [newComment]
 * @property {FastCommentsUIExtensionReplyAreaFilter} [replyAreaFilter] - Filtre HTML pour la zone de commentaire.
 * @property {FastCommentsUIExtensionWidgetFilter} [widgetFilter] - Filtre HTML pour l'ensemble du widget lors du rendu.
 * @property {FastCommentsUIExtensionCommentTopFilter} [commentFilter] - Filtre HTML pour chaque commentaire avant le rendu.
 * @property {FastCommentsUIExtensionReplyAreaFilter} [commentMenuFilter] - Filtre HTML pour le menu de chaque commentaire avant le rendu.
 * @property {FastCommentsUIExtensionMenuFilter} [menuFilter] - Filtre HTML pour l'ensemble du widget lors du rendu.
 * @property {FastCommentsUIExtensionReplyAreaTop} [replyAreaTop] - (HÉRITAGE) Retourne du HTML à ajouter en haut de la zone de réponse.
 * @property {FastCommentsUIExtensionWidgetTopCallback} [widgetTop] - (HÉRITAGE) Retourne du HTML à ajouter en haut du widget.
 * @property {FastCommentsUIExtensionCommentTopCallback} [commentTop] - (HÉRITAGE) Retourne du HTML à ajouter en haut de l'élément de commentaire.
 * @property {FastCommentsUIExtensionCommentBottomCallback} [commentBottom] - (HÉRITAGE) Retourne du HTML à ajouter en bas de l'élément de commentaire.
 * @property {FastCommentsUIExtensionMenuBottomCallback} [menuBottom] - (HÉRITAGE) Retourne du HTML à ajouter en bas de l'élément de menu pour chaque commentaire.
 * @property {FastCommentsUIExtensionRenderCallback} [onRender]
 * @property {FastCommentsUIExtensionConnectionStatusCallback} [onLiveConnectionStatusUpdate]
 * @property {FastCommentsUIExtensionInitialRenderCallback} [onInitialRenderComplete]
 * @property {FastCommentsUIExtensionPresenceUpdateCallback} [onPresenceUpdate]
 */
   
/**
 * @callback FastCommentsUIExtensionSetupEventHandlers
 * @param {Element} element - L'élément racine.
 * @param {Object.<string, Function>} clickListeners - Les gestionnaires d'événements pour les clics, par nom de classe, qui peuvent être modifiés par référence.
 * @returns void
 */
/**
 * @callback FastCommentsUIExtensionWidgetTopCallback
 * @param {Object} moduleData
 * @returns {string}
 */
/**
 * @callback FastCommentsUIExtensionWidgetFilter
 * @param {Object} moduleData
 * @param {Object} html
 * @returns {string}
 */
/**
 * @callback FastCommentsUIExtensionCommentTopCallback
 * @param {Object} comment
 * @returns {string}
 */
/**
 * @callback FastCommentsUIExtensionCommentTopFilter
 * @param {Object} comment
 * @param {string} html
 * @returns {string}
 */
/**
 * @callback FastCommentsUIExtensionCommentBottomCallback
 * @param {Object} comment
 * @returns {string}
 */
/**
 * @callback FastCommentsUIExtensionMenuBottomCallback
 * @param {Object} comment
 * @returns {string}
 */
/**
 * @callback FastCommentsUIExtensionMenuFilter
 * @param {Object} comment
 * @param {string} html
 * @returns {string}
 */
/**
 * @callback FastCommentsUIExtensionRenderCallback
 * @returns {string}
 */
/**
 * @callback FastCommentsUIExtensionConnectionStatusCallback
 * @param {boolean} isConnected
 * @returns {void}
 */
/**
 * @callback FastCommentsUIExtensionInitialRenderCallback
 * @returns {void}
 */
/**
 * @callback FastCommentsUIExtensionReplyAreaTop
 * @param {Object|null} currentUser
 * @param {boolean} isSaving
 * @param {boolean} isReplyOpen
 * @param {string|null} parentId
 * @returns {string}
 */
/**
 * @callback FastCommentsUIExtensionReplyAreaFilter
 * @param {Object|null} currentUser
 * @param {boolean} isSaving
 * @param {boolean} isReplyOpen
 * @param {string|null} parentId
 * @param {string|null} html
 * @returns {string}
 */
/**
 * @callback FastCommentsUIExtensionPrepareCommentForSavingCallback
 * @param {Object} comment
 * @param {string} parentId
 */
/**
 * @callback FastCommentsUIExtensionNewCommentCallback
 * @param {Object} comment
 */
/**
 * @callback FastCommentsUIExtensionPresenceUpdateCallback
 * @param {Object} update
 */

L'API d'extension

Interagir avec l'Extension est simple, car nous définissons simplement des références aux fonctions que nous souhaitons invoquer.

Pour reprendre l'exemple précédent, supposons que nous voulons ajouter du HTML au haut de chaque commentaire :

Une extension simple - Suite

Copy

Run

(function () {
    const extension = FastCommentsUI.extensions.find((extension) => {
        return extension.id === 'my-extension';
    });
    extension.commentFilter = function(comment, html) {
        return `<h3>The user's name is ${comment.commenterName}!</h3>` + html;
    }
})();

Chaque fois que vous renverrez du HTML comme ceci, il sera fusionné dans l'interface utilisateur via un algorithme de diff du DOM.

Déclencher manuellement le re-rendu d'un commentaire

Nous pouvons attendre le chargement initial de la page et relancer manuellement le rendu d'un commentaire en invoquant reRenderComment:

Relancer le rendu d'un commentaire

Copy

Run

(function () {
    const extension = FastCommentsUI.extensions.find((extension) => {
        return extension.id === 'my-extension';
    });
    let renderCount = 0;
    extension.commentFilter = function(comment, html) {
        renderCount++;
        return `<h3>The render count is ${renderCount}!</h3>` + html;
    }
    extension.onInitialRenderComplete = function() {
        setInterval(function() {
            extension.reRenderComment(extension.commentsById[Object.keys(extension.commentsById)[0]], function renderDone() {
                console.log('Comment re-render done.');
            });
        }, 2000); // délai non requis, juste un exemple.
    }
})();

Langue 🇨🇦 Français (Canada)

Contexte

API

Développement d'extensions

Contexte

Le cycle de vie de l'extension

Définir une extension

Exemples d'extensions

Mode sombre

Modération

Chat en direct

L'objet d'extension

L'API d'extension

Déclencher manuellement le re-rendu d'un commentaire