Writing Extensions

Developing Extensions

Context

FastComments provides the ability to extend our core functionality via scripts we call Extensions.

An Extension can add additional markup to the comment widget, event listeners, and run arbitrary code.

Here you will find examples of extensions we have in production, as well as documentation on how to write extensions.

The Extension Lifecycle

The script for each extension is fetched and invoked before the comment widget begins fetching the first set of comments and rendering the UI.

On initial load, the following data will be tagged onto the extension object:

config - A reference to the config object.
translations - A reference to the translations object.
commentsById - A reference to all comments by id.
root - A reference to the root DOM node.

Extensions should override the desired functions, which the comment widget will invoke at the appropriate times.

Defining an Extension

The smallest extension possible would be:

A Simple Extension

Copy

Run

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

For the sake of this example, save this as my-extension.js, and make it available at https://example.com/my-extension.min.js.

This extension does not do anything, except on load it fetches the extension object created by the core comment library.

This Extension object is a singleton and is not shared with any other extensions.

Next, to load our extension, we have to tell the comment widget about it. For example:

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>

For functional examples, see the next section.

Example Extensions

At FastComments, we write our own extensions, using the same API. You can view the unminified code for these extensions at the following endpoints:

Dark Mode

The Dark Mode extension is conditionally loaded when a "dark" page is detected. This extension simply adds some CSS to the comment widget. This way we do not have to load the dark mode CSS when it is not needed.

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

Moderation

When the current user is a moderator, we use the moderation extension.

This is a good example for adding click-based event listeners, making API requests, adding to the comment menu and comment areas.

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

Live Chat

The Live Chat extension (in combination with other configuration and styling) turns the comment widget into a live chat component.

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

The Extension Object

The extension object consists of the following definition:

Extension Object JSDoc

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 - The widget root dom node.
 * @property {string} [css]
 * @property {Object} config - The FastComments config object.
 * @property {Object} commentsById - A reference to an object with all comments by id, which is kept up to date.
 * @property {Object} translations - A reference to all translations.
 * @property {Function} reRenderComment - A reference to a function that can be invoked to re-render a comment.
 * @property {Function} removeCommentAndReRender - A reference to a function that can be invoked to remove a comment from memory and re-render the appropriate part of the DOM.
 * @property {Function} newBroadcastId - A reference to a function that can be invoked create a new broadcast id and add it to the local list of broadcast ids to ignore.
 * @property {FastCommentsUIExtensionSetupEventHandlers} [setupEventHandlers]
 * @property {FastCommentsUIExtensionPrepareCommentForSavingCallback} [prepareCommentForSaving] - Called with the comment about to be posted. Return false to cancel the submit (for example when an attached poll is incomplete).
 * @property {FastCommentsUIExtensionNewCommentCallback} [newComment]
 * @property {FastCommentsUIExtensionReplyAreaFilter} [replyAreaFilter] - Filter HTML for the comment area.
 * @property {FastCommentsUIExtensionWidgetFilter} [widgetFilter] - Filter HTML for the whole widget on render.
 * @property {FastCommentsUIExtensionCommentTopFilter} [commentFilter] - Filter HTML for each comment before render.
 * @property {FastCommentsUIExtensionReplyAreaFilter} [commentMenuFilter] - Filter HTML for each comment menu before render.
 * @property {FastCommentsUIExtensionMenuFilter} [menuFilter] - Filter HTML for the whole widget on render.
 * @property {FastCommentsUIExtensionReplyAreaTop} [replyAreaTop] - (LEGACY) Return HTML to add to the top of the reply area.
 * @property {FastCommentsUIExtensionWidgetTopCallback} [widgetTop] - (LEGACY) Return HTML to add to the top of the widget.
 * @property {FastCommentsUIExtensionCommentTopCallback} [commentTop] - (LEGACY) Return HTML to add to the top of the comment element.
 * @property {FastCommentsUIExtensionCommentBottomCallback} [commentBottom] - (LEGACY) Return HTML to add to the bottom of the comment element.
 * @property {FastCommentsUIExtensionCommentBottomCallback} [commentContentBottom] - Return HTML to add after the comment text, inside the comment content element (used by polls).
 * @property {Function} [replyAreaInputBottom] - Return HTML to add inside the comment input frame, below the text input (used by polls for the in-place poll editor). Receives the parent comment id, or null for the root reply box.
 * @property {Function} [onPollUpdate] - Called with the live event when the vote counts of a poll on the page change.
 * @property {Function} isSiteAdmin - Returns whether the viewer is an admin or moderator of the tenant. Known after the first fetch.
 * @property {FastCommentsUIExtensionMenuBottomCallback} [menuBottom] - (LEGACY) Return HTML to add to the bottom of the menu element for each comment.
 * @property {FastCommentsUIExtensionRenderCallback} [onRender]
 * @property {FastCommentsUIExtensionConnectionStatusCallback} [onLiveConnectionStatusUpdate]
 * @property {FastCommentsUIExtensionInitialRenderCallback} [onInitialRenderComplete]
 * @property {FastCommentsUIExtensionPresenceUpdateCallback} [onPresenceUpdate]
 */
   
/**
 * @callback FastCommentsUIExtensionSetupEventHandlers
 * @param {Element} element - The root element.
 * @param {Object.<string, Function>} clickListeners - The event handlers for clicks, by class name, which can be modified by reference.
 * @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
 */

The Extension API

Interacting with the Extension is simple, as we simply define references to functions we want invoked.

To build off the example earlier, let's say we want to add HTML to the top of each comment:

A Simple Extension - Continued

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;
    }
})();

Whenever you return HTML like this, it will get merged into the UI via a dom-diffing algorithm.

Manually triggering the re-render of a comment

We can wait for the initial page load and manually re-render a comment by invoking reRenderComment:

Re-Rending a Comment

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); // timeout not required, just an example.
    }
})();

Language 🇺🇸 English

Background

API

Writing Extensions

Developing Extensions

Context

The Extension Lifecycle

Defining an Extension

Example Extensions

Dark Mode

Moderation

Live Chat

The Extension Object

The Extension API

Manually triggering the re-render of a comment