Collaborative comments

The CollaborativeComments plugin makes it possible to add comments to any part of content in CKEditor 5.
Commented text is marked as highlighted and the corresponding comment is displayed in the sidebar that needs to be prepared on the integration side.

Collaborative Comments design.

# Installation

The collaborative comments feature requires the CollaborativeEditing plugin to work. The collaborative editing plugin takes care of sending comment markers in text. It also ensures that all clients have the same document version when a user adds a comment to a part of it.

This tutorial starts where the Collaborative editing tutorial ends, so if you do not have a working collaboration setup ready yet, go there first.

When you have the collaboration package included in your custom build, you can add the HTML structure and initialize the editor with the collaborative comments plugin.

# HTML structure

The collaborative comments plugin requires a two-column layout to be prepared before the editor initialization:

The main column for the editor element.
The sidebar column as a container for the sidebar with comments.

The column order and size are not important here. The sidebar can be placed on the right or on the left side and any column size can be set in CSS.

What is important is that the editor and sidebar elements should be positioned elements (relative for its children) and should have the same top offset for their positioned children. When the editor top offset is not the same as the sidebar top offset, the comments and their corresponding markers will be misaligned.

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <title>CKEditor 5 Collaboration with comments</title>
        <style type="text/css">
         .container {
             /* To create the column layout. */
             display: flex;

             /* To make the container relative for its children. */
             position: relative;
         }

         .container .ck.ck-editor {
             /* To stretch the editor to max 700px 
                (just to look nice for this example but it can be any size). */
             width: 100%;
             max-width: 700px;
         }

         .container .sidebar {
            /* Set some size for the sidebar (it can be any). */
            min-width: 300px;

            /* Add some distance. */
            padding: 0 10px;
         }
        </style>
    </head>
    <body>
        <div class="container">
    	    <div class="editor">
    	        <p>Let's edit this together!</p>
    	    </div>
        	<div class="sidebar"></div>
        </div>
    </body>
    <script src="dist/bundle.js"></script>
</html>

# Editor initialization

With an HTML structure as above you can initialize the editor. In this example classic editor is used but, like every other plugin, it will work with any editor creator.

To make collaborative comments work you need to make 3 changes in the code from the Collaborative editing tutorial:

Import CollaborativeComments and add it to the list of plugins.
Add the comment button to the toolbar. If you use the ImageToolbar plugin, add the comment button to the image toolbar separately.
Add the sidebar configuration.

An updated sample should look like this:

import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';
import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
import EasyImageUpload from '@ckeditor/ckeditor5-easy-image/src/easyimage';
import ImageToolbar from '@ckeditor/ckeditor5-image/src/imagetoolbar';

import CollaborativeComments from '@ckeditor/ckeditor5-collaboration/src/collaborativecomments';

ClassicEditor
    .create( document.querySelector( '.editor' ), {
        plugins: [ Essentials, Paragraph, Bold, Italic,
            EasyImageUpload, ImageToolbar, CollaborativeComments ],
        cloudServices: {
            // PROVIDE CORRECT VALUES HERE:
            tokenUrl: 'https://example.com/cs-token-endpoint',
            uploadUrl: 'https://your-organization-id.cke-cs.com/easyimage/upload/',
            webSocketUrl: 'your-organization-id.cke-cs.com/ws/',
            documentId: 'collabComments'
        },
        toolbar: [ 'bold', 'italic', 'imageUpload', 'comment' ],
        image: {
            toolbar: [ 'comment' ]
        },
        sidebar: {
            container: document.querySelector( '.sidebar' )
        },
    } )
    .then( editor => {
        window.editor = editor;
    } )
    .catch( error => console.error( error ) );

Note that you do not need to manually import the CollaborativeEditing plugin anymore. The collaborative comments plugin requires it and will enable it automatically.

This is it. You should now be able to add collaborative comments to your document, and you should see them on all clients.

# Saving comments

To make the integration work out of the box, all comments are saved in CKEditor Cloud Services, so there is no need to handle comments content or users. However, if any comment is added to the document, its position in the text is included in the body:

> editor.getData();
<- '<p>They are <comment id="b39dd790" type="start"></comment>awesome<comment id="b39dd790" type="end"></comment>.</p>'

The position of comments in the body is marked with custom <comment> tags. Separate elements for the beginning and the end of a comment are used to make cleanup simpler when you want to render the page using the content generated by the editor.

There is nothing to worry about this extra markup. However, if your application filters HTML content, for example to prevent XSS, make sure to leave <comment> tags in place, at least for the purpose of passing the content back to the editor for further editing. If <comment> tags are missing, the editor will not know about them.

So, with the example content above, to display the document on your website the <comment> tags may be removed:

<p>They are awesome.</p>

When launching the editor, though, make sure to include them in the HTML:

<div class="container">
    <div class="editor">
        <p>They are <comment id="b39dd790" type="start"></comment>awesome<comment id="b39dd790" type="end"></comment>.</p>
    </div>
    <div class="sidebar"></div>
</div>

# Theme customization

Using the power of CSS Variables it is really easy to override the default design of comments. This action can be done by adding an extra .css file.

CSS Variables in comments.

The image above shows you which variables are responsible for every component in the comments sidebar.

# Example of comments customization with CSS Variables

With Inheritance of CSS Variables you can change the default :root values of variables in the .ck-sidebar scope. Adding these properties to your .css file or into the <head> section of the web page will override this plugin design.

Check out the color sheet for the full list of customizable colors. You can also browse other files with CSS Variables in CKEditor 5.

/* Change the default yellow color of the comment marker in the content to green. */
:root {
    --ck-color-comments-marker: hsl(127, 98%, 83%);
    --ck-color-comments-marker-active: hsl(127, 98%, 68%);
}

.ck-sidebar {
    --ck-color-comments-background: #ecf5f0;
    --ck-color-comments-separator: #64ca6d;
    --ck-color-comments-remove-background: #eccbcb;

    --ck-color-comments-count: #807e81;

    --ck-color-comments-icon: #0f5c2f;
    --ck-color-comments-info: #1eb35c;

    --ck-comments-button-size: 0.85em;

    --ck-user-avatar-size: 35px;
    --ck-user-avatar-background: #239855;
}

/* You can even change the appearance of a single element. */
.ck-sidebar .ck-comment__wrapper:first-of-type {
    --ck-color-comments-info: #8e9822;
    --ck-user-avatar-background: #8e9822;
}

The examples above will generate the following comments designs:

Custom CSS Variables in comments.