Comments walkthrough

This guide explores various functionalities related to the comments feature. It also explains how the comments feature integrates with other editor features.

# Comments and comment threads

Selecting a content fragment and pressing the toolbar button displays an annotation in the editor. This signifies that a comment thread was initiated, however, it does not contain any comments yet. The thread is submitted upon adding the first comment, which happens when you click the “Comment” button. If you click the “Cancel” button, the comment thread will be removed.

Comment thread views are also called “annotations” or “balloons.” You can display annotations in one of three different display modes:

• A wide sidebar
• A narrow sidebar (as shown in this guide)
• Inline

You can read more about these modes in the Annotations display mode guide.

# Comment thread view

Each comment in a thread is shown with its author, their picture (avatar), and the comment creation time.

The top-right corner of each comment displays actions available based on user permissions.

The “Resolve” and “Remove” buttons next to the first comment apply to the entire thread. Using the “Remove” action for any following comments deletes only the selected comment.

You can add custom actions to this dropdown and create other customizations for the comment thread view.

At the bottom of the annotation, there is an input field. Users can type in it to keep the discussion going. The availability of this input depends on user permissions.

# Comment thread states

Created comment threads can assume various states over their lifecycle.

# Open

This is the default state of a comment thread. The thread is available in the document, with its annotation positioned next to the highlighted content. Users can discuss by adding more comments (replies) to the thread.

# Resolved

After clicking the “Resolve” button, the thread becomes resolved. It is moved to the comments archive.

You can access a resolved thread in a dedicated dropdown . Clicking a resolved thread redirects you to the highlighted content element where the thread was initiated.

A resolved comment thread looks different from an open one. There is a yellow bar within the annotation, whose main part is the context:

• For textual content – This is the text on which the thread was created.
• For an image – This will be its alternative text.
• For a block element with no textual information – The bar will display the default context information “Comment was made on an element.”

You can reopen a resolved comment thread by:

• Replying to it in the comments archive.
• Clicking the “Reopen” button next to the context.

At the end of the comments list, you can see the details of when and by whom the thread was resolved. This information will disappear when you reopen the thread.

# Unlinked

When you remove the document content related to a comment thread from the document, the comment thread becomes unlinked. It is then moved to the comments archive. Since it has not been technically resolved, it does not display the usual related information.

You can still interact with the unlinked thread inside the comments archive. However, since the related content is removed, it will not be highlighted in the editor. The thread will also not reopen after adding a new comment.

You can resolve and reopen an unlinked thread as these two states are handled separately.

An unlinked thread will be restored when its related content is restored in the document. This can happen after using undo, restoring an old revision (through the {@features/revision-history revision history feature}), or loading earlier (legacy) document data that contains the related content.

# Unlinked and resolved

Threads can also exist in a combined state of being both unlinked and resolved, inheriting the behavior of both states.

This means that in such a thread, you can continue the discussion, which will reopen the thread. However, the thread will not show in the document unless you restore the related content (as described above).

Since the editor handles these two states separately, a comment thread may become resolved, unlinked, and then reopened and linked in any order.

# Deleted

Threads in this state have been permanently removed and you cannot restore them. You can delete a comment thread only using the UI. You must confirm this action before a comment thread is permanently deleted.

# States’ relation and flow

If you prefer a visual representation, the following diagram illustrates the various states of a comment thread:

# Integration with other features

Certain features integrate with comment threads in non-obvious ways. Such cases are presented in the section below.

# Revision history

It is important to understand the difference between unlinked and resolved or deleted comment threads when using revision history.

1. Restoring a revision will reopen an unlinked comment thread. This is because the commented content is available again in the editor.
2. Restoring a revision will not restore a resolved or deleted comment thread. The revision history feature does not restore the comment thread state.

This is the behavior expected by the user. When the user resolves or deletes a comment thread, their motivation is that the discussion was completed or was invalid. Even if you bring back the commented content, the discussion is still concluded. The comment thread should therefore stay in the archive (or stay deleted and inaccessible).

This is different when a comment thread is archived because its related content is gone. In this case, the discussion is still relevant when the removed content is restored.

# Import from Word

The comments feature is also integrated with the import from Word feature. All comments from imported Word documents are shown as annotations but they are marked as “external.” This aims to differentiate them from comments created inside the editor. It also prevents confusion about the identity of the comment author and clarifies the comment’s origin.

You can mark comment threads as resolved in Word. After importing a document, such threads will appear in the editor’s comment archive as resolved. However, the details on who resolved them will not be displayed since this information is unavailable in the Word file.

# Export to Word

After exporting the editor content to a .docx file using the export to Word feature:

• All open and resolved comment threads will be preserved.
• Unlinked and deleted threads will not be available.

# Clipboard

Comment markers are retained in the clipboard when you cut-and-paste commented content around the document. Similarly, if you drag-and-drop part of the editor content, the comments will be moved together accordingly. This is applied to resolved comment threads as well.

Please be aware, that the comment markers will be moved only if the whole comment content was moved. If only a part of a comment was cut-and-pasted or drag-and-dropped, the comment marker will stay on the original content. This was designed to prevent confusion from duplicated comments.

If you would like to enable retaining comment markers also for copy-and-paste, you need to add an appropriate setting to the editor configuration.