Comments walkthrough

The following guide is dedicated to exploring various functionalities related to the comments feature. It will also explain how the comments feature integrates with other editor features.

# Adding comments

Let’s start with creating a new comment thread. After pressing the related button in the toolbar, an annotation is displayed. This signifies that a comment thread has been initiated, yet it does not contain any comments. The thread is submitted upon adding the first comment, which is done by clicking the ‘Comment’ button. If you click the ‘Cancel’ button the comment thread will be removed and disappear.

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

• Wide sidebar
• Narrow sidebar (as shown in this guide)
• Inline

This is further explained in detail in this guide.

As shown in the image above, each displayed comment in the thread is associated with its author, its picture (avatar), and the time it was created.

In each comment’s top right corner, available actions are displayed based on user permissions (see link for details). Note: ‘Resolve’ and ‘Remove’ buttons next to the first comment apply to the entire thread. Whereas selecting ‘Remove’ action for subsequent comments deletes only the chosen comment.

Note, that it is possible to add custom actions to this dropdown as well as implement other customizations for the comment thread view (link to related tutorial).

At the bottom of the annotation, there is an input field where users can type to keep the discussion going. The availability of this input is also connected to specific permissions.

# 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 and its annotation is positioned next to the highlighted content. Users can discuss by adding more comments to the thread.

# Resolved

After clicking the resolve button, the thread becomes resolved and is moved to the comments archive.

The thread can be accessed in a dedicated dropdown, and clicking on it redirects the user to the element within the content where the thread was initiated and shows the highlight. What’s more, users can still keep discussing in that thread. But remember, if you respond to a resolved thread, it will go back to the “open” state.

A resolved comment thread looks different from an open one. There is a yellow bar within the annotation, where the main part is the context – the text on which the thread was created. If the thread was initiated on an image, its alt text will be set as the context.

A comment thread may be created on a block element that has no textual information. In this case, the default context information “Comment was made on an element” will be displayed.

Next to the context you can find the Reopen button which is the second way to reopen the thread.

Additionally, you can see that details about when and by whom the thread was resolved are shown at the end of the comments list. This information will disappear once you reopen the thread.

# Unlinked

When the document content related to a comment thread is removed from the document, the comment thread becomes unlinked and is moved to the comments archive as well. Since it has not been technically resolved, it does not display resolve-related information.

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

Keep in mind that 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 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, a discussion can still be conducted, and it will reopen the thread, however, the thread will not be shown in the document, unless its related content is restored (as described above).
Since these two states are handled 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 cannot be restored. This action can be performed only using the UI and must be additionally confirmed.

# States relation and flow

For those who 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 and this will be discussed in the section below.

# Revision history

When it comes to revision history, it is important to understand the difference between unlinked and resolved/deleted comment threads.

An unlinked comment thread will be reopened when the revision is restored, as the commented content will be available again in the editor.

On the contrary, a resolved or deleted comment thread will not be restored, as the revision history feature does not restore the comment thread state.

We believe that this is the behavior expected by the user. When the user resolves or deletes the comment thread, their motivation is that the discussion was completed or was invalid. Even if the commented content is brought back, the state of the discussion is still finished, so the comment thread should stay in the archive (or stay deleted, which is not accessible).

This is different when the comment thread was archived only because its related content was gone. In such a 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” to differentiate from comments created “inside” the editor. This prevents confusion about identity and clarifies their origin.

In Word, you can also mark comment threads as resolved. After importing a document, these threads will be shown in the editor’s comment archive as resolved. However, the user info who resolved them will not be displayed since this information is not available in the Word file.

# Export to Word

After exporting the editor content to a Word file, all open and all resolved comment threads will be preserved while unlinked and deleted threads will not be available.