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.
Examples
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

{ getEventLog: () ⇒ EventLog[] }

Fired when a comment is added, resolved, deleted, edited, or replied to.

CommentChange event

This feature is only available for TinyMCE 6.1 and later.

Fired when a comment is added, resolved, deleted, edited, or replied to. Contains the getEventLog API for retrieving log of comment changes.

Example: the CommentChange event

tinymce.init({
  selector: 'textarea',
  plugins: 'tinycomments',
  toolbar: 'addcomment showcomments',
  init_instance_callback: (editor) => {
    editor.on('CommentChange', (evt) => {
      console.log(evt.getEventLog());
    });
  }
});

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.

Returns a log with information and timestamps of all changes to comments, including when:

  • A new comment is added (and who added it).

  • A comment is edited (and who edited it).

  • A reply to a comment is added (and who added the reply).

  • A comment is resolved (and who resolved the comment).

  • A comment is deleted (and who deleted the comment).

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:

Example: using getEventLog()

const comments = tinymce.activeEditor.plugins.tinycomments;

console.log(comments.getEventLog());
console.log(comments.getEventLog(
  { after: '2022-02-22T12:34:56Z' }  // ISO-8601 standard: YYYY-MM-DDThh:mm:ssZ
));

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.

This notification 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');
            }
          });
        }
      }
    });
  }
});