Question

A context toolbar can only contain either buttons that are defined for a normal toolbar, or buttons specifically registered for launching a ContextForm. The buttons comes as a list of strings, where each string is a registered name of a button.

Registering a context toolbar

A context toolbar is registered by calling the addContextToolbar API in the registry. The specification is as follows:

Name	Description
predicate	This controls when the context toolbar will appear
position	This controls where the context toolbar will appear with regards to the current cursor
scope	This controls whether the predicate is a node-based predicate, or an editor-based predicate. See context toolbar proirity section below, for more details.
items	A list of strings which represent either a registered toolbar button, or a registered context form launcher.

Launching a context toolbar programmatically

There is an editor event called contexttoolbar-show that can be fired to show a context toolbar at the current selection. The event takes a parameter toolbarKey which specifies the name of the registered context form or context toolbar to show.

Context toolbar priority

There are two settings that determine determine the priority: predicate and scope. The priority system mirrors the old inlite theme from TinyMCE 4. The predicate is a function that takes in the current context position and returns a boolean. The scope is either node or editor. The whole priority process works as follows:

1. The current cursor position is stored to use as the first current context position.
2. For this current context position, each predicate with scope: node in the registered ContextForm is called. Currently, the order they are checked-in cannot be specified. The first predicate that passes will win and that ContextForm will be shown.
3. If no predicates (scope: node) match the current context position, then all of the scope: editor predicates are tried. The first one that matches the editor context wins.
4. If no scope: editor predicates match, then the new context position is calculated by going up the tree one level to the parent node. All scope: node predicates are then checked again. As soon as one matches, it wins and that ContextForm is shown. If nothing matches, it goes up the tree and tries again.

Note: Only scope: node predicates are checked at this stage. The scope: editor predicate is only checked once and that check only happens in (2).

Caution: Since the order in which the ContextForms and ContextToolbars are checked is not specified, try not to have their predicates overlap.

Positioning context toolbars

There are three options for positioning are: selection, line, or node.

• A selection position will place the context toolbars above or below the current selection, centred if possible.
• A line position will place the context toolbars to the right (or left in Right-to-Left languages) of the current selection.
• A node position will place the context toolbars relative to the bounds of a node (e.g. a table or image). It applies to a selected node that does not match the selection due to CSS properties (like float).

Example configuration

This example shows how the quickbars plugin adds the standard selection context toolbar and an example of a custom toolbar for image alignment. The context toolbar will show whenever any content is selected.

TinyMCE HTML JS Edit on CodePen

<textarea id="context-toolbar">
  <p>Clicking on the example image below will show the newly configured context toolbar.</p>

  <p style="text-align: center;">
    <img title="TinyMCE Logo" src="//www.tiny.cloud/images/glyph-tinymce@2x.png" alt="TinyMCE Logo" width="110" height="97" />
  </p>

  <p>Select a word in this sentence, to see the other newly configured context toolbar.</p>

  <p>Clicking on text should not invoke the context toolbar</p>
</textarea>

tinymce.init({
  selector: 'textarea#context-toolbar',
  height: 350,
  setup: function (editor) {
    editor.ui.registry.addContextToolbar('imagealignment', {
      predicate: function (node) {
        return node.nodeName.toLowerCase() === 'img'
      },
      items: 'alignleft aligncenter alignright',
      position: 'node',
      scope: 'node'
    });

    editor.ui.registry.addContextToolbar('textselection', {
      predicate: function (node) {
        return !editor.selection.isCollapsed();
      },
      items: 'bold italic | blockquote',
      position: 'selection',
      scope: 'node'
    });
  }
});