Écrire des extensions

Le script pour chaque extension est récupéré et invoqué avant que le widget de commentaires ne commence à récupérer le premier jeu de commentaires et à rendre 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.

La plus petite extension possible serait :

Une extension simple

Copy Run

1

2(function () {

3 const extension = FastCommentsUI.extensions.find((extension) => {

4 return extension.id === 'my-extension';

5 });

6})();

7

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

Cette extension ne fait rien ; au chargement, elle récupère simplement l'objet Extension créé 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 :

Utilisation d'une extension personnalisée

Copy Run

1

2<script async src="https://cdn.fastcomments.com/js/embed-v2-async.min.js"></script>

3<div id="fastcomments-widget"></div>

4<script>

5window.fcConfigs = [{

6 "tenantId": "demo",

7 "extensions": [

8 {

9 "id": "my-extension",

10 "path": "https://example.com/my-extension.min.js"

11 }

12 ]

13}];

14</script>

15

Pour des exemples fonctionnels, voir la section suivante.

L'objet extension est constitué de la définition suivante :

JSDoc de l'objet Extension

Copy Run

1

2/**

3 * L'objet extension FastCommentsUI. Utilisé pour le chargement différé de certains composants. Par exemple, le système d'avis n'est pas

4 * utilisé par tous les clients, donc nous ne chargeons cette extension que lorsque nous en avons besoin.

5 *

6 * @typedef {Object} FastCommentsUIExtension

7 * @property {string} id

8 * @property {Element} scriptNode

9 * @property {Element} root - Le nœud DOM racine du widget.

10 * @property {string} [css]

11 * @property {Object} config - L'objet de configuration FastComments.

12 * @property {Object} commentsById - Une référence vers un objet contenant tous les commentaires par id, qui est maintenu à jour.

13 * @property {Object} translations - Une référence vers toutes les traductions.

14 * @property {Function} reRenderComment - Une référence vers une fonction qui peut être invoquée pour re-rendre un commentaire.

15 * @property {Function} removeCommentAndReRender - Une référence vers une fonction qui peut être invoquée pour supprimer un commentaire de la mémoire et re-rendre la partie appropriée du DOM.

16 * @property {Function} newBroadcastId - Une référence vers une fonction qui peut être invoquée pour créer un nouvel identifiant de diffusion et l'ajouter à la liste locale des identifiants de diffusion à ignorer.

17 * @property {Function} [withSessionId] - À appeler avec une URL de requête et un callback. Invoque le callback avec l'URL plus l'identifiant de session du visiteur ajouté lorsque les cookies tiers sont bloqués (même chemin que les requêtes de commentaire et de vote), ou l'URL inchangée sinon. Lorsqu'aucun identifiant de session n'est disponible de cette manière, ajoute le dernier identifiant de session anonyme donné à rememberAnonSessionId, le cas échéant. Non utilisé pour le SSO.

18 * @property {Function} [rememberAnonSessionId] - À appeler avec l'anonSessionId renvoyé par une réponse. Le serveur n'en renvoie un qu'à un invité dont la requête n'avait pas de cookie de session, et jamais pour une session connectée. Il est conservé dans localStorage (ou en mémoire lorsque le stockage est indisponible) afin que withSessionId l'envoie lors des requêtes suivantes et que l'invité conserve une seule identité.

19 * @property {FastCommentsUIExtensionSetupEventHandlers} [setupEventHandlers]

20 * @property {FastCommentsUIExtensionPrepareCommentForSavingCallback} [prepareCommentForSaving] - Appelé avec le commentaire sur le point d'être publié. Retourner false pour annuler la soumission (par exemple lorsqu'un sondage joint est incomplet).

21 * @property {FastCommentsUIExtensionNewCommentCallback} [newComment]

22 * @property {FastCommentsUIExtensionReplyAreaFilter} [replyAreaFilter] - Filtre le HTML de la zone de commentaire.

23 * @property {FastCommentsUIExtensionWidgetFilter} [widgetFilter] - Filtre le HTML de l'ensemble du widget lors du rendu.

24 * @property {FastCommentsUIExtensionCommentTopFilter} [commentFilter] - Filtre le HTML de chaque commentaire avant le rendu.

25 * @property {FastCommentsUIExtensionReplyAreaFilter} [commentMenuFilter] - Filtre le HTML du menu de chaque commentaire avant le rendu.

26 * @property {FastCommentsUIExtensionMenuFilter} [menuFilter] - Filtre le HTML de l'ensemble du widget lors du rendu.

27 * @property {FastCommentsUIExtensionReplyAreaTop} [replyAreaTop] - (LEGACY) Retourne le HTML à ajouter en haut de la zone de réponse.

28 * @property {FastCommentsUIExtensionWidgetTopCallback} [widgetTop] - (LEGACY) Retourne le HTML à ajouter en haut du widget.

29 * @property {FastCommentsUIExtensionCommentTopCallback} [commentTop] - (LEGACY) Retourne le HTML à ajouter en haut de l'élément de commentaire.

30 * @property {FastCommentsUIExtensionCommentBottomCallback} [commentBottom] - (LEGACY) Retourne le HTML à ajouter en bas de l'élément de commentaire.

31 * @property {FastCommentsUIExtensionCommentBottomCallback} [commentContentBottom] - Retourne le HTML à ajouter après le texte du commentaire, à l'intérieur de l'élément de contenu du commentaire (utilisé par les sondages).

32 * @property {Function} [replyAreaInputBottom] - Retourne le HTML à ajouter à l'intérieur du cadre de saisie du commentaire, sous le champ de texte (utilisé par les sondages pour l'éditeur de sondage intégré). Reçoit l'identifiant du commentaire parent, ou null pour la zone de réponse racine.

33 * @property {Function} [onPollUpdate] - Appelé avec l'événement en direct lorsque les nombres de votes d'un sondage sur la page changent.

34 * @property {Function} isSiteAdmin - Indique si le visiteur est un administrateur ou un modérateur du tenant. Connu après la première récupération.

35 * @property {FastCommentsUIExtensionMenuBottomCallback} [menuBottom] - (LEGACY) Retourne le HTML à ajouter en bas de l'élément de menu de chaque commentaire.

36 * @property {FastCommentsUIExtensionRenderCallback} [onRender]

37 * @property {FastCommentsUIExtensionConnectionStatusCallback} [onLiveConnectionStatusUpdate]

38 * @property {FastCommentsUIExtensionInitialRenderCallback} [onInitialRenderComplete]

39 * @property {FastCommentsUIExtensionPresenceUpdateCallback} [onPresenceUpdate]

40 */

41

42/**

43 * @callback FastCommentsUIExtensionSetupEventHandlers

44 * @param {Element} element - L'élément racine.

45 * @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.

46 * @returns void

47 */

48

49/**

50 * @callback FastCommentsUIExtensionWidgetTopCallback

51 * @param {Object} moduleData

52 * @returns {string}

53 */

54

55/**

56 * @callback FastCommentsUIExtensionWidgetFilter

57 * @param {Object} moduleData

58 * @param {Object} html

59 * @returns {string}

60 */

61

62/**

63 * @callback FastCommentsUIExtensionCommentTopCallback

64 * @param {Object} comment

65 * @returns {string}

66 */

67

68/**

69 * @callback FastCommentsUIExtensionCommentTopFilter

70 * @param {Object} comment

71 * @param {string} html

72 * @returns {string}

73 */

74

75/**

76 * @callback FastCommentsUIExtensionCommentBottomCallback

77 * @param {Object} comment

78 * @returns {string}

79 */

80

81/**

82 * @callback FastCommentsUIExtensionMenuBottomCallback

83 * @param {Object} comment

84 * @returns {string}

85 */

86

87/**

88 * @callback FastCommentsUIExtensionMenuFilter

89 * @param {Object} comment

90 * @param {string} html

91 * @returns {string}

92 */

93

94/**

95 * @callback FastCommentsUIExtensionRenderCallback

96 * @returns {string}

97 */

98

99/**

100 * @callback FastCommentsUIExtensionConnectionStatusCallback

101 * @param {boolean} isConnected

102 * @returns {void}

103 */

104

105/**

106 * @callback FastCommentsUIExtensionInitialRenderCallback

107 * @returns {void}

108 */

109

110/**

111 * @callback FastCommentsUIExtensionReplyAreaTop

112 * @param {Object|null} currentUser

113 * @param {boolean} isSaving

114 * @param {boolean} isReplyOpen

115 * @param {string|null} parentId

116 * @returns {string}

117 */

118

119/**

120 * @callback FastCommentsUIExtensionReplyAreaFilter

121 * @param {Object|null} currentUser

122 * @param {boolean} isSaving

123 * @param {boolean} isReplyOpen

124 * @param {string|null} parentId

125 * @param {string|null} html

126 * @returns {string}

127 */

128

129/**

130 * @callback FastCommentsUIExtensionPrepareCommentForSavingCallback

131 * @param {Object} comment

132 * @param {string} parentId

133 */

134

135/**

136 * @callback FastCommentsUIExtensionNewCommentCallback

137 * @param {Object} comment

138 */

139

140/**

141 * @callback FastCommentsUIExtensionPresenceUpdateCallback

142 * @param {Object} update

143 */

144

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

Pour prolonger l'exemple précédent, disons que nous voulons ajouter du HTML en haut de chaque commentaire :

Une extension simple - Suite

Copy Run

1

2(function () {

3 const extension = FastCommentsUI.extensions.find((extension) => {

4 return extension.id === 'my-extension';

5 });

6

7 extension.commentFilter = function(comment, html) {

8 return `<h3>The user's name is ${comment.commenterName}!</h3>` + html;

9 }

10})();

11

Chaque fois que vous renvoyez du HTML de cette manière, il sera fusionné dans l'interface 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 re-rendre manuellement un commentaire en appelant reRenderComment :

Re-rendu d'un commentaire

Copy Run

1

2(function () {

3 const extension = FastCommentsUI.extensions.find((extension) => {

4 return extension.id === 'my-extension';

5 });

6

7 let renderCount = 0;

8

9 extension.commentFilter = function(comment, html) {

10 renderCount++;

11 return `<h3>The render count is ${renderCount}!</h3>` + html;

12 }

13

14 extension.onInitialRenderComplete = function() {

15 setInterval(function() {

16 extension.reRenderComment(extension.commentsById[Object.keys(extension.commentsById)[0]], function renderDone() {

17 console.log('Comment re-render done.');

18 });

19 }, 2000); // timeout not required, just an example.

20 }

21})();

22