Commands, Events and APIs for the Comments plugin
Commands
The Comments plugin provides the following TinyMCE commands.
Command | Description |
---|---|
tc-delete-conversation-at-cursor |
Attempts to delete the comment at the current cursor position. A confirmation dialog will be shown prior to deletion. |
tc-try-delete-all-conversations |
Attempts to delete all comments in the editor. A confirmation dialog will be shown prior to deletion. |
tinymce.activeEditor.execCommand('tc-delete-conversation-at-cursor');
tinymce.activeEditor.execCommand('tc-try-delete-all-conversations');
Events
The following events are provided by the Tiny Comments plugin.
Name | Data | Description |
---|---|---|
mce-tinycomments-update |
N/A |
Fired when the comments sidebar is opened or closed. |
CommentChange |
|
Fired when a comment is added, resolved, deleted, edited, or replied to. |
APIs
The Comments plugin provides the getEventLog()
API, as well as an annotator named 'tinycomments'
created using the editor.annotator
API.
getEventLog()
This feature is only available for TinyMCE 6.1 and later. |
The getEventLog
returns a log that contains information and timestamps of all changes to comments, including when:
-
A new comment is added.
{
"type": "create",
"timestamp": "2024-10-01T03:07:53.771Z",
"conversationUid": "annotation-r1nn5xdo5ye",
"conversationContext": "Welcome",
"conversationContent": "new comment"
},
-
A comment is edited.
{
"type": "edit-comment",
"timestamp": "2024-10-01T03:08:06.551Z",
"conversationUid": "annotation-r1nn5xdo5ye",
"commentUid": "annotation-r1nn5xdo5ye",
"conversationContext": "Welcome",
"conversationContent": "new comment",
"conversationCreatedAt": "2024-10-01T03:07:53.771Z",
"commentContent": "new comment (Edit comment)",
"commentAuthor": {
"author": "DEMO USER",
"authorName": "DEMO USER"
},
"conversationAuthor": {
"author": "DEMO USER",
"authorName": "DEMO USER"
}
},
-
A reply to a comment is added.
{
"type": "reply",
"timestamp": "2024-10-01T03:07:53.771Z",
"conversationUid": "annotation-r1nn5xdo5ye",
"commentUid": "annotation-uh00rb41kma",
"conversationContext": "Welcome",
"conversationContent": "new comment (Edit comment)",
"conversationCreatedAt": "2024-10-01T03:07:53.771Z",
"commentContent": "reply to existing comment",
"conversationAuthor": {
"author": "DEMO USER",
"authorName": "DEMO USER"
}
},
-
A comment is resolved.
{
"type": "resolve",
"timestamp": "2024-10-01T03:08:25.783Z",
"conversationUid": "annotation-r1nn5xdo5ye",
"conversationContext": "Welcome",
"conversationContent": "new comment (Edit comment)",
"conversationAuthor": {
"author": "DEMO USER",
"authorName": "DEMO USER"
}
},
-
A comment is deleted.
{
"type": "delete-comment",
"timestamp": "2024-10-01T03:08:23.292Z",
"conversationUid": "annotation-r1nn5xdo5ye",
"commentUid": "annotation-uh00rb41kma",
"conversationContext": "Welcome",
"conversationContent": "new comment (Edit comment)",
"commentContent": "reply to existing comment",
"commentAuthor": {
"author": "DEMO USER",
"authorName": "DEMO USER"
},
"conversationAuthor": {
"author": "DEMO USER",
"authorName": "DEMO USER"
}
},
The event log can be retrieved either in full or with the after
option, which restricts the returned list to Comment events after a time-stamp date in the ISO-8601 format, both shown in the following:
The 'tinycomments'
annotator
The Comments plugin provides an annotator named 'tinycomments'
, constructed using the editor.annotator
API.
The 'tinycomments'
annotator is used to annotate content with conversations attached, and is available for use in each of the editor.annotator
API methods.
The 'tinycomments'
annotator, like all editor APIs, can only be accessed after the editor is initialized.
Example: using the 'tinycomments'
annotator to notify when conversations are selected
This example makes use of the annotationChanged
method in the editor.annotator
API to create a custom notification.
The below notification example displays for five seconds every time any content with a 'tinycomments'
annotation is selected.
tinymce.init({
selector: 'textarea',
plugins: 'tinycomments',
toolbar: 'addcomment showcomments',
setup: (editor) => {
editor.on('init', () => {
editor.annotator.annotationChanged('tinycomments', (selected, annotatorName, context) => {
if (selected) {
editor.notificationManager.open({
text: `The content you have selected contains a conversation. ${annotatorName}: ${context.uid}.`,
type: 'info',
timeout: 5000
});
}
});
});
}
});
Example: using the 'tinycomments'
annotator to highlight conversations without showing comments
This example makes use of the getAll
method in the editor.annotator
API to highlight every element annotated by 'tinycomments'
.
When the 'highlightcomments'
button on the toolbar is toggled on, every annotated element is highlighted aquamarine
, without requiring the user to show comments.
tinymce.init({
selector: 'textarea',
plugins: 'tinycomments',
toolbar: 'addcomment showcomments highlightcomments',
setup: (editor) => {
editor.ui.registry.addToggleButton('highlightcomments', {
icon: 'highlight-bg-color',
onAction: (api) => {
api.setActive(!api.isActive());
const conversations = editor.annotator.getAll('tinycomments');
for (const [conversation, elements] of Object.entries(conversations)) {
elements.forEach((element, _) => {
if (api.isActive()) {
element.style.setProperty('background-color', 'aquamarine');
} else {
element.style.removeProperty('background-color');
}
});
}
}
});
}
});