Using the Annotations API

The TinyMCE Annotations API provides the ability to add, modify, and delete annotations; listen to selection events and retrieve all annotations with the same annotation name. The Annotations API is a part of the TinyMCE core and functions in the same way as the formatting APIs in TinyMCE core.

The primary value that the Annotations API provides is that it tags each annotation with a unique identifier(uid) accessible through editor.annotator. This highlights the annotated content and wraps it in annotation markers. These markers can either stay in the content or be removed on getContent, depending on the user configuration (persistent setting).

Using the Annotator

Perform the following procedure to set up the TinyMCE Annotations feature:

1. Configure the Annotate Button

To configure the annotate button on your toolbar:

setup: (editor) => {
  editor.ui.registry.addButton('annotate-alpha', {
    text: 'Annotate',
    onAction: () => {
      const comment = prompt('Comment with?');
      editor.annotator.annotate('alpha', {
        comment
      });
      editor.focus();
    }
  })
}

2. Registering the Annotator

The annotator API supports multiple annotation functions. Each annotation function must be registered with the annotator (editor.annotator).

editor.on('init', () => {
  editor.annotator.register('alpha', {
    persistent: true,
    decorate: (uid, data) => ({
      attributes: {
        'data-mce-comment': data.comment ? data.comment : '',
        'data-mce-author': data.author ? data.author : 'anonymous'
      }
    })
  });
});

This will register an annotation with the name alpha. In our example, when an alpha is being added to the document, a span marker will be created with class alpha and a data attribute for the author.

The data passed through here is the same as the data specified when calling the annotate API. decorate is used to turn the annotation data into a document object model (DOM) representation. The uid passed through to decorate is either the uid field in the data object (if it exists), or a randomly generated uid if it does not. Annotator will be responsible for putting the uid on the span. The user does not need to do that part.

3. Making the Annotator Available

For adding the annotate tool to the toolbar that is registered with alpha set the value of the toolbar to:

toolbar: 'annotate-alpha'

4. Applying Annotations

After registering an annotation, use it by applying it to the current selection. For content that can be annotated, see: Supported content.

If the selection is collapsed (single cursor rather than ranged selection) and is within a word, it will first perform a word grab function and then apply the annotation to the resulting word selection.

The API to apply an annotation is annotate. Annotations can be programmatically applied to selected content using:

editor.annotator.annotate('alpha', {
  author: 'me'
});

The data passed through { author: 'me' } is passed to the decorate function specified during registration for the particular annotation (here: alpha). This data can be any object. In this way, users can tag markers with any attributes/classes they want on a per-annotation basis. Here, we will end up with a span with a data-author attribute set to me. If the user wants, they can specify a uid as part of the data here. This is used instead of a randomly generated uid when passing through as the first argument to decorate.

Example of specifying your own uid:

editor.annotator.annotate('alpha', {
  uid: 'use-this-id-instead-of-your-random-one-annotator!',
  author: 'me'
});

5. Listening to Selection Events

The Annotator API notifies the user when the selection cursor moves in or out of a specified annotation. For example, for the alpha scenario:

editor.annotator.annotationChanged('alpha', (state, name, obj) => {
  if (state === false) {
    // NOTE: name will be 'alpha' here
    console.log(`We are no longer in a ${name} area`);
  } else {
    console.log(`We are now in comment: ${obj.uid}`);
  }
});

The obj parameter is only set if the state is true. And the state is

  • true when the selection cursor moves in to an annotation; and

  • false when the selection cursor moves out of an annotation.

When state is true, and the obj parameter is set, the parameter has two fields:

  • uid, which is the uid of the annotation currently nearest (in the DOM hierarchy) to the selection cursor.

  • nodes, which is an array of DOM nodes which make up this annotation. nodes are made available to users in case the user might want to tag these nodes with a class to say that they are the active annotations.

The annotationChanged listeners should only fire when the state or the uid changes. The full API is:

/**
* Executes the specified callback when the current selection matches the annotation or not.
*
* @method annotationChanged
* @param {String} name Name of annotation to listen for
* @param {function} callback Calback with (state, name, and data) fired when the annotation
* at the cursor changes. If state if false, data will not be provided.
*/
annotationChanged: (name: string, callback): void

Interactive example

Use the following example to create the Annotate API:

  • TinyMCE

  • HTML

  • JS

  • Edit on CodePen

<textarea id="annotations">
  <p><img style="display: block; margin-left: auto; margin-right: auto;" title="Tiny Logo" src="https://www.tiny.cloud/docs/images/logos/android-chrome-256x256.png" alt="TinyMCE Logo" width="128" height="128"></p>
  </p>
  <h2 style="text-align: center;">Welcome to the TinyMCE Cloud demo!</h2>
  <h5 style="text-align: center;">Note, this includes some "enterprise/premium" features.<br>Visit the <a href="https://www.tiny.cloud/pricing">pricing page</a> to learn more about our premium plugins.</h5>
  <p>Please try out the features provided in this full featured example.</p>

  <h2>Got questions or need help?</h2>
  <ul>
    <li>Our <a href="https://www.tiny.cloud/docs/tinymce/6/">documentation</a> is a great resource for learning how to configure TinyMCE.</li>
    <li>Have a specific question? Try the <a href="https://stackoverflow.com/questions/tagged/tinymce" target="_blank" rel="noopener"><code>tinymce</code> tag at Stack Overflow</a>.</li>
    <li>We also offer enterprise grade support as part of <a href="https://www.tiny.cloud/pricing">TinyMCE premium subscriptions</a>.</li>
  </ul>

  <h2>A simple table to play with</h2>
  <table style="border-collapse: collapse; width: 100%;" border="1">
    <thead>
      <tr>
        <th>Product</th>
        <th>Cost</th>
        <th>Really?</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>TinyMCE Cloud</td>
        <td>Get started for free</td>
        <td>YES!</td>
      </tr>
      <tr>
        <td>Plupload</td>
        <td>Free</td>
        <td>YES!</td>
      </tr>
    </tbody>
  </table>

  <h2>Found a bug?</h2>
  <p>If you think you have found a bug please create an issue on the <a href="https://github.com/tinymce/tinymce/issues">GitHub repo</a> to report it to the developers.</p>

  <h2>Finally ...</h2>
  <p>Don't forget to check out our other product <a href="http://www.plupload.com" target="_blank">Plupload</a>, your ultimate upload solution featuring HTML5 upload support.</p>
  <p>Thanks for supporting TinyMCE! We hope it helps you and your users create great content.<br>All the best from the TinyMCE team.</p>
</textarea>
tinymce.init({
  selector: 'textarea#annotations',
  toolbar: [ 'annotate-alpha' ],
  menubar: false,
  height: '750px',
  content_style: '.mce-annotation { background-color: darkgreen; color: white; } ' +
    'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }',
  setup: (editor) => {
    editor.ui.registry.addButton('annotate-alpha', {
      text: 'Annotate',
      onAction: () => {
        const comment = prompt('Comment with?');
        editor.annotator.annotate('alpha', {
          uid: 'custom-generated-id',
          comment: comment
        });
        editor.focus();
      },
      onSetup: (btnApi) => {
        editor.annotator.annotationChanged('alpha', (state, name, obj) => {
          console.log('Current selection has an annotation: ', state);
          btnApi.setEnabled(!state);
        });
      }
    });

    editor.on('init', () => {
      editor.annotator.register('alpha', {
        persistent: true,
        decorate: (uid, data) => ({
          attributes: {
            'data-mce-comment': data.comment ? data.comment : '',
            'data-mce-author': data.author ? data.author : 'anonymous'
          }
        })
      });
    });
  }
});

Retrieving All Annotations for a Particular Annotation Name

The Annotator API allows retrieving an object of all of the uids for a particular annotation type (e.g. alpha), and the nodes associated with those uids. For example, to retrieve all alpha annotations, this code is used:

const annotations = editor.annotator.getAll('alpha');
const nodesInFirstUid = annotations['first-uid'];

Assuming that there is a uid called first-uid, the above code shows how to access the nodes used for making that annotation. The full API is:

/**
* Retrieve all the annotations for a given name
*
* @method getAll
* @param {String} name the name of the annotations to retrieve
* @return {Object} an index of annotations from uid => DOM nodes
*/
getAll: (name)

Deleting an Annotation

Use the remove API to delete a particular annotation at the cursor. It will remove the closest annotation that matches the name. For example,

editor.annotator.remove('alpha');

This bypasses any other annotations that might be closer to the selection cursor and removes annotations which are alpha annotations. If there are no annotations of that name, it will do nothing. The full API is:

/**
* Removes any annotations from the current selection that match
* the name
*
* @param remove
* @param {String} name the name of the annotation to remove
*/
remove: (name)

Supported content

  • Text

  • Blocks

    This feature is only available for TinyMCE 6.1 and later.