Context toolbar
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:
- The current cursor position is stored to use as the first current context position.
- 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 willwin
and that ContextForm will be shown. - If no predicates (
scope: node
) match the current context position, then all of thescope: editor
predicates are tried. The first one that matches the editor context wins. - If no
scope: editor
predicates match, then the new context position is calculated by going up the tree one level to the parent node. Allscope: 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. Thescope: 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'
});
}
});